AutoDL Research Pilot

AutoDL Research Pilot gives Codex a practical way to answer two questions: should this experiment rent a GPU now, and which available GPU is worth renting?

The Enterprise Elastic workflow begins with the official AutoDL API. It reads the account balance and GPU stock filtered by region, CUDA, CPU, RAM, and price; deployments and private images are added when the token can access them. The scheduler joins that live state with workload-specific throughput evidence, compares total completion time and total cost, and builds an exact Container deployment request. The request stays local until a researcher approves it.

A high hourly rate is not automatically expensive. If a faster GPU cuts a 30-hour run to eight hours, it may finish sooner and cost less overall. Conversely, a top-end GPU can spend most of its time waiting on a DataLoader. Research Pilot models the run rather than ranking product names.

What it does

• Uses the official API as the control plane. Enterprise discovery, planning, deployment creation, listing, stopping, and deletion are first-class CLI and MCP operations.

• Makes availability executable. Stock is queried under the same region, CUDA, CPU/RAM, GPU-model, and price_to filters that are placed in the deployment.

• Optimizes the whole run. Runtime, setup, transfer, queueing, workload throughput, uncertainty, and known fixed costs feed one cost/time Pareto comparison.

• Understands research constraints. VRAM, budget, deadline, inventory, and run readiness are hard filters. Model, data, precision, seeds, batch semantics, and evaluation do not silently change to fit a cheaper card.

• Offers clear preferences. economy minimizes conservative total cost; time minimizes completion time within budget; balanced chooses a middle point; custom accepts your own weights.

• Keeps paid actions reviewable. Mutations are request previews by default. A confirmed Elastic create rechecks wallet capacity, duplicate run names, private-image access/presence, the full candidate inventory, and the deadline immediately before the API call.

• Ships as a CLI, MCP server, and Codex Skill. The Skill also covers GPU diagnosis, storage, images, foreground commands, checkpointing, and the Pro/Elastic lifecycle difference.

Related MCP server: Run:AI MCP Server

Quick start: Enterprise Elastic

Install

git clone https://github.com/chengxi271-commits/autodl-research-pilot.git
cd autodl-research-pilot
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[mcp]"
$env:AUTODL_TOKEN = "YOUR_TOKEN"

Linux / macOS:

source .venv/bin/activate
python -m pip install -e '.[mcp]'
export AUTODL_TOKEN='YOUR_TOKEN'

Keep the token in the process environment. The project never needs it in TOML, JSON, a command argument, or source control.

Describe this run

Copy the Enterprise examples and replace the image, command, regions, resource bounds, workload performance factors, and price ceilings:

cp examples/elastic.project.toml my-run.project.toml
cp examples/elastic.catalog.toml my-run.catalog.toml

The catalog is deliberately small. It lists the GPU profiles you are prepared to use, not every GPU AutoDL has ever offered. Set image_source to private for an account image or public for a UUID from AutoDL's API appendix. When dc_list spans regions, prepare the input and output storage in every listed region or narrow the list to the prepared one. Each performance_factor should come from the same workload or a clearly labeled estimate; each price_ceiling_cny is your maximum acceptable hourly price, not a claimed market quote.

Discover, plan, preview

autodl-pilot discover --catalog my-run.catalog.toml --output live-context.json

autodl-pilot live-plan --project my-run.project.toml --catalog my-run.catalog.toml --profile balanced --output run.plan.json

autodl-pilot apply-live-plan --plan run.plan.json

live-plan performs fresh discovery by default, so the separate discover command is optional. It is useful when you want to inspect what the API returned or freeze one read-only snapshot for discussion.

The preview contains the unique run name, exact GPU, available regions, image and source, foreground command, CPU/RAM range, and price ceiling. It makes no mutation call. Check selected.execution_ready; if it is false, selected.needs_input names the missing account access, image, or research gate. After reviewing an execution-ready request:

autodl-pilot apply-live-plan --plan run.plan.json --confirm

Confirmation reads wallet, active deployments with the same run name, the selected private image, and every catalog stock filter again. It checks that the conservative runtime still fits the frozen deadline, then calls POST /api/v1/dev/deployment. If the selected profile disappears or a previously unavailable candidate appears, it returns to planning instead of creating from a stale ranking or substituting an unapproved GPU.

How the decision works

For GPU profile g, the scheduler starts from a reference runtime and estimates:

compute time = reference runtime / workload performance factor
total time   = queue + setup + transfer + compute time
total cost   = fixed cost + billed time × hourly price ceiling × GPU count

Lower-confidence performance evidence expands the conservative time and cost. Candidates that miss a hard constraint never reach profile scoring. The survivors form a Pareto frontier: no frontier candidate is both slower and more expensive than another.

The API stock response reports idle card counts, not precise prices or benchmark speed. Research Pilot therefore keeps these facts separate:

1. AutoDL stock proves current availability under a price band.

2. The catalog records VRAM and workload performance evidence.

3. Elastic price_to caps what the deployment may accept; the planner uses that cap for a conservative bill.

The current live planner intentionally creates one-GPU Container deployments. AutoDL documents stock as a single-card query and warns that two idle cards may live on different hosts. Multi-GPU scheduling should follow a same-workload scaling test and explicit same-host evidence rather than an optimistic inventory sum.

Making the GPU choice smarter

AutoDL's official performance table is a useful prior, but its runs are single-card, use synthetic in-memory input, and omit CPU preprocessing and additional I/O. Prefer a short slice of the real model, precision, batch semantics, and data pipeline.

The bundled Skill follows a simple bottleneck rule:

• GPU at 0%: check device use and framework/CUDA compatibility.

• GPU steady above roughly 90%: a faster GPU or measured single-host multi-GPU run may help.

• GPU low or oscillating: inspect CPU, DataLoader workers, storage, and synchronization first.

• CUDA OOM: check stale processes and batch size 1 before deciding on larger VRAM.

• Process killed near the RAM limit: request more container memory, not more VRAM.

After a comparable successful run, feed its compute time, setup/transfer overhead, actual container rate, and measured bottleneck back into the matching catalog profile. That workload history, rather than a generic benchmark table, makes later choices improve.

It also treats storage as part of scheduling. Hot data belongs on /root/autodl-tmp; durable checkpoints and results belong on persistent storage such as /root/autodl-fs before an Elastic command exits. See the AutoDL field guide for the source-linked operating rules.

Personal Pro accounts

The official Pro API can read wallet, instances, status, snapshots, and private images, and can create, power on/off, and release instances. It does not publish a pre-allocation market catalog or stock endpoint. For a new Pro rental, use a fresh console quote with the offline planner:

autodl-pilot api wallet
autodl-pilot api instances
autodl-pilot api images
autodl-pilot plan --project project.toml --offers current-offers.toml --output pro.plan.json
autodl-pilot apply-plan --plan pro.plan.json

The current Pro snapshot documentation exposes raw payg_price fields without declaring their unit, so the client preserves them raw. Verify the allocated price in the console before a long run. Pro API creation is pay-as-you-go, accepts one to four GPUs, and exposes system-disk expansion; API power-on supports GPU mode, not the console's no-card mode.

The original offline example remains useful for testing the scheduler without a token:

autodl-pilot plan --project examples/project.toml --offers examples/offers.toml --profile balanced

Its prices are fixtures and cannot pass the current-quote execution gate.

Operating a deployment

autodl-pilot api deployments
autodl-pilot api containers --payload '{"deployment_uuid":"DEPLOYMENT_UUID","page_index":1,"page_size":10}'
autodl-pilot api events --payload '{"deployment_uuid":"DEPLOYMENT_UUID","page_index":1,"page_size":10,"offset":0}'

autodl-pilot deployment-stop DEPLOYMENT_UUID
autodl-pilot deployment-stop DEPLOYMENT_UUID --confirm

autodl-pilot deployment-delete DEPLOYMENT_UUID
autodl-pilot deployment-delete DEPLOYMENT_UUID --confirm

Elastic training should run in the foreground: when cmd exits, the container stops. A background python train.py & can leave billing and lifecycle behavior disconnected from the research job. Local data is not persistent after stop: without reuse it is released immediately; a reuse cache may retain leftovers but is neither guaranteed storage nor a restartable container. cmd_before_shutdown has only a five-second window, so checkpoint persistence belongs in the training command itself.

For Pro long runs launched over SSH, use screen, tmux, or a Jupyter terminal and write logs to a named file. Retrieve and verify results before release; stopping compute and deleting recoverable state are separate decisions.

CLI reference

All normal results and controlled errors are JSON. Run autodl-pilot --help for arguments.

Codex and MCP

Install the mcp extra and load this repository as a local Codex plugin. .mcp.json targets Windows; docs/mcp.unix.json is the Unix manifest. MCP exposes the same discovery, live planning, preview, confirmation, read, and lifecycle operations as the CLI.

The Codex Skill lives at skills/autodl-research-pilot/SKILL.md. A useful first prompt is:

Use the AutoDL API to inspect live Elastic stock, compare my supported GPU profiles in balanced mode, and show the exact deployment preview. Wait for my approval before creating it.

Scope

Version 0.2.0 implements the API-first Enterprise single-GPU Container path and retains Pro/offline planning. The API client is the control plane; SSH transfer, workload execution, metric collection, and checkpoint retrieval remain data-plane work coordinated by the Skill. Catalog feedback is Skill-guided rather than automatic telemetry. Runtime cost includes storage only when supplied as fixed_cost. Purchased Elastic duration-package balances are not modeled yet, so the estimate can overstate marginal cash cost when one applies.

Endpoint and unit boundaries are documented in AutoDL API Boundaries. This is a community project and is not affiliated with AutoDL.

Development

python -m unittest discover -s tests -v

CI runs the test suite on Python 3.11, 3.12, and 3.13. See CONTRIBUTING.md, SECURITY.md, and the issue tracker.

License

Apache-2.0