Run a command as a GPU job
run_jobRun one shell command as a job on its own fresh GPU machine. The command runs under bash in /workspace, and the machine stops (billing ends) as soon as the command exits. Billing is the machine's per-hour rate from when it is running until it stops, setup included. ALWAYS set max_runtime_minutes to a realistic upper bound for the command: a job that runs longer is stopped as timed_out. PREFER a list for gpu, e.g. ["H100", "A100-80GB:2", "L40S"]: the GPUs are tried in order, and with no capacity for any of them the job waits (status queued, queue_reason no_capacity, next_attempt_at) up to capacity_wait_minutes (default 30) instead of failing. To send code, pass files (path to text, up to 1 MB in all) or code.git (a repository and ref): it is put in /workspace/code before the command starts, and the command runs there. An agent with a shell and the Runcrate CLI can send a whole directory instead: runcrate run --code . -- . To keep results, write them to $RUNCRATE_OUTPUT_DIR (/workspace/outputs): they are kept 30 days after the job (up to 5 GB), whatever its status; list_job_artifacts and read_job_artifact return them. Or pass storage_id: the volume's files are in /workspace, and files written under /workspace are saved to the volume when the machine stops. For long or flaky work set max_retries: a machine that fails is replaced and the command runs again (RUNCRATE_JOB_ATTEMPT says which attempt), so write checkpoints to the volume and resume from them. count (or params, one variables object per job) runs many copies at once as a group (RUNCRATE_JOB_INDEX, RUNCRATE_JOB_COUNT), max_parallel at a time. The machine also gets the environment's secrets (list_secrets shows their names); variables of the same name win over them. Returns the job (status starting while its machine launches, or queued while it waits), or for count or params the group with its jobs. Its output is in get_job_logs (from after 0, each returned cursor as the next after; follow: true waits up to 25 s for new output; done is true at the end), and its status, exit_code and cost_usd in get_job. Statuses: queued, starting, running, then succeeded, failed, cancelled or timed_out. cancel_job stops a job early; rerun_job runs it again with changes. A retried call is not run twice: the job it already started is returned. The command starts once the GPU driver answers: on machines that install it after boot the job waits in starting for up to 20 minutes, and if the driver is still not ready then, the command runs anyway (usually failing on its GPU calls) and the job log says so. get_job_events shows each setup step. cost_usd covers the machine's whole time, not only the command's: from when its machine came up until it stopped, so setup before the command (pulling the image, waiting for the GPU driver, unpacking code) is included, at each machine's hourly rate (cost_per_hour is the current one's) and with every attempt added up. It is in USD to six decimal places, so a short run is not shown as $0, and while the job runs it is the cost so far. The charge on the billing page can differ slightly: machines billed by the minute are charged whole minutes, including about 30 seconds of teardown, and time some hosts report offline is not charged.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"gpu": "<gpu>",
"command": "<command>",
"max_runtime_minutes": "<max_runtime_minutes>"
},
"name": "run_job"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gpu | Yes | GPU type, e.g. "A4000", or a list to try in order, e.g. ["H100", "A100-80GB:2"]; ":2" sets that entry's GPU count, 1, 2, 4 or 8 (see list_gpu_types). A list waits for capacity on any of them. | |
| code | No | A git repository to fetch into /workspace/code before the command starts (a shallow fetch of ref). | |
| name | No | Job name, up to 63 characters (default job-<first 8 characters of the id>) | |
| tags | No | Labels to find the job by later with list_jobs tag, e.g. {"team": "ml", "run": "sweep-3"}. At most 20; keys are lower case letters, digits and _ . : - | |
| count | No | Run this many copies as a group (1 to 100). Each sees RUNCRATE_JOB_INDEX (0-based) and RUNCRATE_JOB_COUNT. | |
| files | No | Files to put in /workspace/code before the command starts: relative path to text, e.g. {"train.py": "...", "configs/base.yaml": "..."}. Up to 1 MB in all. Use code.git for more. | |
| image | No | Container image to run the command in (optional). /workspace is mounted, the GPUs are passed in, and the image is pulled before the max runtime starts. If the machine cannot pass GPUs into a container, the job fails before the command runs, unless allow_cpu_container is true. The image needs bash or sh. For a private image, pass image_registry_auth. Leave it out to run directly on the machine. | |
| params | No | One variables object per job, merged over variables, e.g. [{"LR": "0.1"}, {"LR": "0.01"}] for a sweep. Instead of count. | |
| region | No | Only run in this region, matched as for instances (optional; omit for any region) | |
| command | Yes | Shell command, run with bash in /workspace (in /workspace/code when code or files are given), e.g. "pip install -r requirements.txt && python train.py". Up to about 5 KB of ordinary shell; put longer scripts in files. | |
| retry_on | No | What is retried, with max_retries: machine_failure (always on) and nonzero_exit (the command failed). | |
| template | No | OS template from list_templates (default ubuntu-devbox) | |
| gpu_count | No | GPUs on the machine: 1, 2, 4 or 8 (default 1) | |
| variables | No | Environment variables for the command, e.g. {"HF_TOKEN": "hf_..."}. Keys use letters, digits and underscores. They win over the environment's secrets of the same name. Values are stored only encrypted, never returned. To pick the Runcrate environment the job runs in, use environment. | |
| workspace | No | Workspace ID (optional: defaults to the authenticated workspace) | |
| storage_id | No | Volume ID from list_volumes or create_volume (optional). Its files are in /workspace, and files written under /workspace are saved to it when the machine stops. Pass one to keep outputs. The volume must be in the same workspace and environment and not attached to another machine. | |
| environment | No | Environment name (optional: defaults to the environment this session acts in) | |
| max_retries | No | Run the command again on a new machine this many times at most when an attempt fails (default 0). A machine failure is always retried; a failing command only with retry_on or retry_exit_codes. The volume is saved after each attempt. | |
| webhook_url | No | https URL that gets a signed POST when the job finishes (optional). It is signed like this workspace's webhooks, or, when it has none, with a webhook_secret returned once in this answer. | |
| max_parallel | No | With count or params: how many of the group run at once (default all). The rest wait, queue_reason max_parallel. | |
| idempotency_key | No | Optional: the same key within 24 hours returns the job it started instead of starting another. Derived from this call when left out. | |
| retry_exit_codes | No | Retry only when the command exits with one of these codes (takes precedence over nonzero_exit). | |
| include_community | No | Let community hosts run it (off by default: datacenter machines only). A community host is run by an independent host, not a datacenter: the host operates the hardware and can access the machine, and it is not available on reserved terms. Only when the user asked for community hosts. | |
| allow_cpu_container | No | Run the image without GPUs when the machine cannot pass them into a container, instead of failing (default false). | |
| image_registry_auth | No | Sign in to the image's registry before the pull, with two env values named here (never the values themselves). | |
| max_runtime_minutes | Yes | Required. Longest the command may run, in minutes (1 to 10080, 7 days), counted from when it starts, for each attempt. Set a realistic bound for this command: past it the job is stopped as timed_out. | |
| capacity_wait_minutes | No | How long to wait for capacity on any of the GPUs before failing (0 to 1440, default 30). 0 fails at once. |