> ## Documentation Index
> Fetch the complete documentation index at: https://runcrate.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Run a command on its own GPU machine from the terminal and follow its logs until it ends.

export const RuncrateStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('runcrate-overrides')) {
    const s = document.createElement('style');
    s.id = 'runcrate-overrides';
    s.textContent = `
      /* Match Runcrate's rounding scale (--radius: 0.75rem) */
      .rounded-sm { border-radius: 0.5rem !important; }   /* 8px */
      .rounded-md { border-radius: 0.625rem !important; } /* 10px */
      .rounded-lg { border-radius: 0.75rem !important; }  /* 12px */
      .rounded-l-sm { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }
      .rounded-l-md { border-top-left-radius: 0.625rem !important; border-bottom-left-radius: 0.625rem !important; }
      .rounded-r-md { border-top-right-radius: 0.625rem !important; border-bottom-right-radius: 0.625rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.75rem !important; border-bottom-left-radius: 0.75rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.75rem !important; border-bottom-right-radius: 0.75rem !important; }

      /* Cards: never pure white in light mode */
      .card { background-color: #fcfcfc !important; border-radius: 0.75rem !important; }
      html.dark .card { background-color: #141414 !important; }

      /* Docs hero box */
      .rc-hero { background-color: #fcfcfc; border: 1px solid #e0e0e0; }
      html.dark .rc-hero { background-color: #141414; border-color: #242424; }
      html.dark .rc-hero h1 { color: #f5f5f5; }

      /* Runcrate scrollbar — thin, transparent track, hide-until-hover thumb */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<RuncrateStyles />

`runcrate run` starts a [job](/docs/jobs/overview): your command on a fresh GPU machine that stops, and stops billing, as soon as the command exits.

### Run a command

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
# Train on an A4000 with a volume in /workspace, for at most 2 hours
runcrate run --gpu A4000 --volume <volume-id> --max-runtime 2h -- python train.py

# Several commands, pipes or && go in one quoted string
runcrate run --gpu H100 --gpu-count 2 --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 --env HF_TOKEN=$HF_TOKEN --env WANDB_API_KEY=$WANDB_API_KEY -- python finetune.py

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

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`. Required. See `runcrate instances types`. |
| `--gpu-count` | GPUs on the machine, 1 to 8. Default 1. |
| `--max-runtime` | Longest the command may run: `90m`, `2h`, `1h30m` or bare minutes. Rounded up to whole minutes, 1m to 24h. 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` | Preferred region. |
| `--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:

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
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

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
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
```

### Job status

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
runcrate jobs status <job-id>          # Status, exit code and cost
runcrate jobs status <job-id> --json
```

### Logs

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
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

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
runcrate jobs cancel <job-id>
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.