Docs menu

// Guides

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.

View as Markdown

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.

Prices#

What you runPrice
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). 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.

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. 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://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: you approve it on simforge.ai with a code it shows you, for one organization and the scopes it asks for.

Errors#

Code (HTTP)MeaningDo
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 kindsTry 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 linkOpen 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 doesOpen it, accept, then retry
insufficient_credits (402)The workspace's credits do not cover the paid run; detail.creditsUrl is its credits pageAsk the person to buy credits, or use local/browser 2D visualization
max_cost_required (the CLI's)--cloud without a cost cap; nothing was sentPass --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.exceededAsk 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 youCheck the id and the workspace
conflict (409)A stale version or digest, or the host's detail.code reasonRead the object again, then decide

The hosted API is described by its OpenAPI document.