# Run in the cloud

> Run the same simforge commands on SimForge's machines with --cloud, price them with --dry-run, cap them with --max-cost, and download the results.

Source: https://simforge.ai/docs/cloud

Add `--cloud` to a command and it runs on SimForge's hosted API instead of your runtime: the same command, the same scenario file, the same output. Use it for what your machine cannot do, such as photoreal renders without a large GPU, or many jobs at once.

> **Beta.** SimForge Cloud is open in beta. Paid compute (3D renders, evaluations, transfers, Recast and asset generation) runs on SimForge's machines; 2D is a browser/local visualization, not a cloud job. [Sign up](https://simforge.ai/?auth=sign-up) and start with $25 in free credits. Work the cloud does not run yet is refused with `cloud_not_open`: run the command without `--cloud`.

## Prices

| What you run | Price |
|---|---|
| 3D render | $1.00 per render |
| Closed-loop driving evaluation | $3.00 per scenario |
| Open-loop driving evaluation | $3.00 per scenario |
| Transfer to another map | $0.50 per scenario |
| Recast (log to scenario) | $1.00 per log |
| 3D asset generation | $1.00 per asset |

Each price is fixed before a run starts, and `--dry-run` shows it before anything runs. Prices are in cents on the command line (`--max-cost 100` is one dollar). Authoring, simulation, templates, OpenSCENARIO import and export, and validation are free.

- A new account starts with $25 in free credits, and a workspace spends what its credits cover: there is no daily limit. A paid run the workspace's credits do not cover is refused before anything starts (`insufficient_credits`), with a link to buy credits on the workspace's credits page. Credits are checked first, so this is the answer even for work the cloud does not run yet.
- 2D visualizations run in Studio's browser player or locally with `simforge render --mode 2d`; they do not use cloud credits or a cloud worker.
- A run that fails costs nothing. A partial or cancelled run is charged only for the jobs that finished, and Recast only when the log became a scenario.

## Price, cap, run, download

```sh
simforge render s.json --mode 3d --rig rig.json --out out-3d --cloud --dry-run
simforge render s.json --mode 3d --rig rig.json --out out-3d --cloud --max-cost 200 --wait --download
simforge simulate s.json --out sim --cloud --max-cost 50 --wait --download
```

- `--dry-run` returns the estimate (`costEstimateCents`) and starts nothing. On a scenario file it first saves the file to your workspace as an immutable revision (free), and the run that follows reuses exactly that revision. With `--max-cost` it still prices the run and adds `maxCost: {limitCents, exceeded}`: `exceeded: true` means the same command without `--dry-run` would be refused.
- `--max-cost` (in cents) is required with `--cloud`. A run whose estimate is above it is refused before anything starts (`budget_exceeded`); one the workspace's credits do not cover, with `insufficient_credits`. `--max-cost 0` runs only free work.
- `--wait` follows the run to `succeeded`, `failed`, `partial` or `cancelled`; `--download` then writes every artifact into `--out`, sha256-checked. Giving `--out` also waits and downloads; without it the command returns as soon as the run is submitted. While it waits, stderr gets a `run.progress` line with the run id straight away, then the run's status and its jobs on each change and at least every 30 seconds; the result still comes on stdout at the end.
- `--idempotency-key` makes resending a lost submission safe: the host answers with the original run and charges once.

The cloud runs `render`, `simulate`, `preview frame` and `preview clip`, Recast (log ingestion), transfer (below), and downloads hosted datasets as files ([Getting data out](/docs/datasets)). Reinforcement learning stays local.

Test a model by letting it drive your saved scenarios: **Run an evaluation** on Evaluations or Model Comparison. A closed-loop evaluation by Alpamayo 1.5 Nano, SimForge Pilot-4B v1.5 or Qwen Drive 1 4B costs **$3 per scenario**, including preparation. A model shows as temporarily unavailable while no machine is serving it. Pick a dataset or a few scenarios, review the total and the balance after it, then run.

```sh
simforge evaluate --cloud --model "Alpamayo 1.5 Nano" --dataset "My scenarios" --wait
```

The CLI prints the quote and asks before starting (`--yes` skips the prompt; `--dry-run` only quotes). `--scenarios "Crossing,Turning"` picks a subset. It prints the run URL and `--wait` follows progress. Only scenarios and maps your workspace can already use are offered.

An open-loop evaluation scores a driving model's predictions along one of your finished scenario renders and costs **$2 per scenario**, charged only when it succeeds. `--model` names the model that predicts (without it, the CLI lists the models you can run):

```sh
simforge open-loop run RENDER_RUN_ID --model MODEL --cloud --max-cost 200 --idempotency-key my-eval-1 --dry-run
```

`simforge open-loop list --model MODEL` lists one model's evaluations. `--model 'SimForge Pilot-4B v1.5'` and `--model 'Qwen Drive 1 4B'` both see through their own three cameras, so render the scenario with that rig first (`simforge rig init --preset qwen-drive-3cam --out rig.json`, then render with `--rig rig.json`); a render with another rig is refused, naming the preset. That render records the rig's native 10 fps unless you pass `--fps`. A render at another rate is still scored: each input is the nearest rendered frame, and the dry run and the run both say so in a note with the largest time offset used.

Scripted `closed-loop`, your own registered models, other endpoints, AlpaSim, comparisons and finished-run requeues stay locked with `403 evaluation_launch_disabled`. Use **Request evaluation** or **Use your own model** for an email request instead; requests start no work and charge nothing.

## Recast: bring your own logs

```sh
simforge import log drive.recording.json --map auto --name "left turn" --cloud --max-cost 100 --out ./drive
simforge import log drive.mcap --map auto --cloud --dry-run
```

Recast turns a recorded drive into an editable scenario: a recording (`simforge.recording/v1`) or a ROS 2 MCAP lidar log becomes a scenario on one of SimForge's maps. `--map auto` takes the recording's own map, or the map its GNSS path lies in. An MCAP log is perceived on a GPU worker first; its detector's weights are CC BY-NC-SA 4.0, so scenarios made from MCAP logs are for non-commercial use.

## Bring your own OpenSCENARIO file

```sh
simforge import openscenario cut-in.xosc --cloud --stage
simforge import openscenario cut-in.xosc --cloud --max-cost 100 --wait
```

The file is imported onto the SimForge map whose OpenDRIVE it names, and arrives as an editable scenario. `--stage` uploads the file and prices the import without starting it; a file whose road network is not a SimForge map is refused `osc_map_unknown` there, for free.

## The same event on another map

```sh
simforge transfer s.json --map yale-street --cloud --max-cost 50 --out ./yale
```

A transfer that lands creates a new scenario in the workspace and costs $0.50; one no site on the map accepts creates nothing, is charged nothing and exits 2 with its verdict. Each target map is its own transfer, priced on its own.

> Run transfer with `--cloud` for now. A local transfer needs the target map's `odr` derivative, which `simforge maps pull` does not install yet, so it stops with `map_facts_missing`.

## Follow a run

```sh
simforge runs list --limit 20
simforge runs watch <run-id>
simforge runs cancel <run-id>
simforge results download <run-id> --out ./results
simforge usage
```

A partial or cancelled run keeps the artifacts it produced.

## Hosted scenarios

A scenario stored in your workspace runs at an immutable revision, which pins the exact map version, actors and recordings:

```sh
simforge scenarios list --limit 20
simforge render <scenario-id> --revision <revision-id> --mode 3d --rig rig.json --out ./render --cloud --max-cost 100 --wait --download
```

To change a scenario and keep the original, copy it. The copy is a new scenario with the same map, actors, timeline and settings, named `<name> (copy)`; the original's renders and runs stay with the original. It lands in the original's dataset, or in your default dataset when you cannot change that one (`--dataset` picks another):

```sh
simforge scenarios copy <scenario-id> --name "Left turn, wet"
```

For a scenario shared from another workspace, the copy keeps its pinned recordings and provenance. If that original already has a copy in your target dataset, the existing copy opens instead of making another; the shared original stays read-only.

## Sign-in, scopes and API keys

`simforge login` asks for scopes that cover downloads and cloud runs. A CI job can use an API key instead: set `SIMFORGE_API_KEY` (`sfk_…`) and `SIMFORGE_API_URL`. The key acts in the workspace it was created in, and your workspace role still applies: a viewer only reads, runs need a member.

Managing keys needs the `keys:admin` scope, which a plain login does not ask for. `--scope` adds a scope to the default ones, so sign in again with it, then create the key:

```sh
simforge login --scope keys:admin          # the default scopes plus keys:admin
simforge keys create --name ci --expires-in-days 90
simforge keys list
simforge keys revoke <key-id>
```

A new key's secret (`sfk_…`) is printed once. You can also create and revoke keys in the browser, on your workspace's [API keys page](https://simforge.ai/dashboard/workspace/settings?view=api-keys). If `simforge auth status` then lists only `keys:admin` under `scopes`, the CLI is an older one that replaced the defaults: reinstall it (`curl -fsSL https://dev.simforge.ai/install.sh | sh`), or name every scope (`simforge login --scope keys:admin --scope runs:write …`) as its `insufficient_scope` hint prints.

An AI agent that calls the API without the CLI signs in through [auth.md](/auth.md): you approve it on simforge.ai with a code it shows you, for one organization and the scopes it asks for.

## Errors

| Code (HTTP) | Meaning | Do |
|---|---|---|
| `cloud_not_open` (403) | SimForge Cloud is not open on this host yet (beta), does not run this work yet ("3D renders aren't available yet on SimForge Cloud."), or its workers for it are down for now (`detail.temporary: true`, "3D renders are temporarily unavailable on SimForge Cloud: no worker is running them right now."); `detail.code` is `run_kind_unavailable` and `detail.kinds` its job kinds | Try again in a few minutes when `detail.temporary` is true; otherwise run the command without `--cloud` |
| `email_unverified` (403) | Runs that submit cloud work need a verified email; `detail.resendUrl` resends the link | Open the link in your email, or resend it from `detail.resendUrl` |
| `terms_acceptance_required` (403) | The Terms of Service changed and the account has not accepted them; `detail.acceptUrl` is the page that does | Open it, accept, then retry |
| `insufficient_credits` (402) | The workspace's credits do not cover the paid run; `detail.creditsUrl` is its credits page | Ask the person to buy credits, or use local/browser 2D visualization |
| `max_cost_required` (the CLI's) | `--cloud` without a cost cap; nothing was sent | Pass `--max-cost` deliberately |
| `budget_exceeded` (402) | Estimate above `--max-cost` (`detail.limit` is `max_cost`). A `--dry-run` is never refused for `--max-cost`: it answers the price with `maxCost.exceeded` | Ask the person whose budget it is; an agent never raises the cap itself |
| `insufficient_scope` (403) | A scope (`detail.required`) or role (`detail.requiredRole`) is missing, or `--workspace` names another workspace than the login's (`detail.code` `workspace_mismatch`) | Run the login the hint names (`simforge login --scope keys:admin` for API keys), sign in for that workspace's organization, or ask an admin |
| `not_found` (404) | The object does not exist or is not visible to you | Check the id and the workspace |
| `conflict` (409) | A stale version or digest, or the host's `detail.code` reason | Read the object again, then decide |

The hosted API is described by its [OpenAPI document](/docs/openapi.json).
