Jobs

runcrate run starts a job: your command on a fresh GPU machine that stops, and stops billing, as soon as the command exits.

Run a command

# Train on an A4000 with PyTorch installed (the Finetune template) and a volume in /workspace, for at most 2 hours
runcrate run --gpu A4000 --template ubuntu-train --volume <volume-id> --max-runtime 2h -- python train.py

# Several commands, pipes or && go in one quoted string. pip keeps the installed PyTorch.
runcrate run --gpu H100 --gpu-count 2 --template ubuntu-train --max-runtime 6h -- 'pip install -r requirements.txt && python train.py'

# Pass secrets as environment variables (values are stored only encrypted, never returned)
runcrate run --gpu A4000 --template ubuntu-train --env HF_TOKEN=$HF_TOKEN --env WANDB_API_KEY=$WANDB_API_KEY -- python finetune.py

# Batch inference with vLLM, installed on the Inference template
runcrate run --gpu L40S --template ubuntu-inference --max-runtime 1h -- python batch_infer.py

# Run inside a container image
runcrate run --gpu L40S --image pytorch/pytorch:latest -- python eval.py

On every template python is Python 3. ubuntu-train has PyTorch 2.8 for CUDA 12.8 with Transformers, TRL and PEFT, and ubuntu-inference has vLLM 0.11; the default ubuntu-devbox has no PyTorch. See Templates and Python. Everything after -- is the command. A single argument is run as written. Several arguments are joined with spaces, and any argument holding spaces or shell characters is quoted first, so -- python -c 'print(1)' runs as typed. The command and its logs are visible to everyone in the workspace, so pass tokens with --env (or keep them in your environment’s secrets), never inside the command. run prints the job id, then follows the logs until the job ends.

Flags

Flag	Description
`--gpu`	GPU type, for example `A4000` or `H100:2`, or GPUs to try in order, comma separated: `H100,A100-80GB:2`. Required. See `runcrate instances types`.
`--gpu-count`	GPUs on the machine, 1 to 8, for the `--gpu` entries without a count. Default 1.
`--max-runtime`	Longest each attempt may run: `90m`, `2h`, `1h30m` or bare minutes. Rounded up to whole minutes, 1m to 168h (7 days). Default 1h, printed when you submit.
`--volume`	Volume id. Its files are in `/workspace`, and what you write there is saved back when the machine stops.
`--template`	OS template. Default `ubuntu-devbox`. See `runcrate templates`.
`--image`	Container image to run the command in. `/workspace` is mounted. GPUs reach the container only on machines with the NVIDIA container runtime; otherwise the log says so. Needs `bash` or `sh`.
`--env K=V`	Environment variable. Repeat for more.
`--name`	Job name, at most 63 characters. Default `job-<first 8 characters of the id>`.
`--region`	Only run in this region (a region from `runcrate instances types`, the start of one like `us-east`, or a city or country).
`--capacity-wait`	How long the job may wait for a free GPU before it fails: `0` to `24h`. Default 30m.
`--retries`	Retry a failed attempt on a new machine, up to this many times (0 to 10). Machine failures are retried. See Retries.
`--retry-on`	`nonzero_exit` also retries when your command fails (with `--retries`).
`--retry-exit-codes`	With `--retry-on nonzero_exit`, only these exit codes, for example `137,143`.
`--count`	Run this many copies as a group (1 to 100). Each sees `RUNCRATE_JOB_INDEX`. See Arrays.
`--params`	A JSON file (or `-` for stdin) holding a list of env objects: one job per entry, as a group.
`--max-parallel`	With `--count` or `--params`, run at most this many at once.
`--tag key=value`	Tag the job, to find it with `jobs list --tag`. Repeat for more.
`--webhook-url`	An https URL Runcrate calls with a signed POST when the job finishes. The signing secret is printed once. See Callbacks.
`--webhook-events`	`finished` (default), `started`, or both, comma separated.
`--code`	A directory (or `.tar.gz`) to upload and run in. It is packed without `.git`, `__pycache__` and `node_modules`, at most 1 GB, and the command runs in `/workspace/code`.
`--git`, `--git-ref`, `--git-token-env`	An https git repository to clone and run in (`/workspace/code`), its branch, tag or commit, and the env variable or secret holding a token for a private one.
`--registry-username-env`, `--registry-password-env`	The env variables or secrets holding the registry login for a private `--image`.
`--allow-cpu-container`	Run `--image` even on a machine whose containers cannot reach the GPU.
`--idempotency-key`	Submit at most once per key for 24 hours: running the same command again answers the first job. Each run sends a new key otherwise; when the answer to a submit is lost, the error prints the key it sent so you can re-run with it.
`--detach`	Print the job id and return without following logs.

Detach and re-attach

Press Ctrl-C while run follows logs to detach. The job keeps running, and run prints how to come back to it:

runcrate jobs logs -f <job-id>    # Follow the logs again
runcrate jobs cancel <job-id>     # Stop the job and its machine

Ctrl-C never cancels a job. Use jobs cancel for that.

Exit codes

runcrate run exits with the job’s result, so scripts and agents can check it:

Job status	Exit code
`succeeded`	0
`failed`	The command’s exit code, or 1 if the machine failed
`timed_out`	124
`cancelled`	130
Detached (Ctrl-C or `--detach`)	0

List jobs

runcrate jobs list                          # Newest first
runcrate jobs list --status running,queued  # Filter by status
runcrate jobs list --limit 50
runcrate jobs list -q                       # IDs only
runcrate jobs list --json
runcrate jobs list --tag project=vision     # Every tag given must match
runcrate jobs list --group <group-id>       # The jobs of one group
runcrate jobs list --search train --gpu H100 --since 24h

Job status

runcrate jobs status <job-id>          # Status, exit code and cost
runcrate jobs status <job-id> --json

Logs

runcrate jobs logs <job-id>       # Print the logs so far
runcrate jobs logs -f <job-id>    # Follow until the job ends

Logs are capped at 10 MB per job (the first 5 MB and the newest output are kept) and are kept 30 days after the job ends.

Cancel a job

runcrate jobs cancel <job-id>

The machine stops and the job becomes cancelled. Files under /workspace are saved to the volume.

Wait for a job

runcrate jobs wait <job-id>                 # Until it ends; exits with the job's code
runcrate jobs wait <job-id> --timeout 2h    # Exit 75 if it is still running then

jobs wait polls with a growing gap (2 s up to 30 s) and exits like runcrate run: 0, the command’s exit code, 124 or 130. With --timeout it exits 75 when the time passes first; the job keeps running.

Outputs

Files your command writes to $RUNCRATE_OUTPUT_DIR are kept 30 days after the job ends.

runcrate jobs artifacts <job-id>                     # Path, size and SHA-256 of each
runcrate jobs download <job-id>                      # All of them, into the current directory
runcrate jobs download <job-id> model.pt runs/ -o ./results

download keeps each file’s path, checks its SHA-256, and never replaces a file that exists unless you pass --force.

Rerun a job

runcrate jobs rerun <job-id>                                   # Same command and settings, as a new job
runcrate jobs rerun <job-id> --gpu H100 --max-runtime 4h --env EPOCHS=10

The new job keeps the old one’s env values (only whoever submitted it can reuse them). --env adds or replaces values; any other flag (--gpu, --gpu-count, --max-runtime, --capacity-wait, --retries, --tag, --name, --region, --image, --template, --volume) replaces that setting. It follows the logs like run, or returns with --detach.

Groups

--count or --params start a group: run prints each job’s id and returns.

runcrate run --gpu L40S --params sweep.json --max-parallel 4 -- 'python train.py --lr $LR'
runcrate jobs group status <group-id>    # How many jobs are in each status, and the cost
runcrate jobs group cancel <group-id>    # Cancel every job that has not ended (asks first; --yes skips)

Delete a job

runcrate jobs delete <job-id>          # Asks first
runcrate jobs delete <job-id> --yes

Deleting removes a job that ended with its logs and outputs. Cancel a live job first.

Welcome

SDKs

CLI

Inference

Compute

Schedules

Secrets

Storage

Dedicated Clusters

Billing

Account

Webhooks

FAQ

Jobs

Run a command

Flags

Detach and re-attach

Exit codes

List jobs

Job status

Logs

Cancel a job

Wait for a job

Outputs

Rerun a job

Groups

Delete a job

​Run a command

​Flags

​Detach and re-attach

​Exit codes

​List jobs

​Job status

​Logs

​Cancel a job

​Wait for a job

​Outputs

​Rerun a job

​Groups

​Delete a job

Run a command

Flags

Detach and re-attach

Exit codes

List jobs

Job status

Logs

Cancel a job

Wait for a job

Outputs

Rerun a job

Groups

Delete a job