Configure environments and runtimes

This guide covers three kinds of setup: where the CLI sends its requests, which GPU a job runs on, and what Python packages a job can import.

Where the CLI sends requests

Commands that talk to Simulo, such as run, jobs, logs, result, policy, export, outputs, recordings, view, cancel and asset, find the platform in this order:

1. SIMULO_API_URL, an explicit URL. It always wins.
2. SIMULO_ENV, a named Simulo environment preset. The default preset is prod. An unknown value is refused with the list of supported values.
3. Your saved login: the platform you last signed in to with simulo login, recorded in ~/.simulo/credentials.
4. The Simulo cloud, when nothing else is set.

For most people, simulo login is all the setup there is. After it, every command goes to the platform you signed in to, with no variables set.

If you set SIMULO_ENV or SIMULO_API_URL, set it once for the whole shell with export, so simulo login and later commands agree on the target.

When simulo run submits to the cloud

simulo run submits to the Simulo cloud when you are signed in, or when SIMULO_API_URL or SIMULO_ENV is set. Otherwise it writes a local package and does not run it:

Submitted job 'train' -> package written to /home/you/cartpole_demo/.simulo/packages/sha256-<digest>
This wrote a local package only. Log in to submit to the Simulo cloud instead:
    simulo login

SIMULO_SUBMIT=local forces this local package mode even when you are signed in. --from needs the cloud, so the CLI refuses it in local mode.

Accounts and organizations

simulo whoami

Email:         you@example.com
Organization:  <organization name>
Slug:          <organization slug>

simulo whoami checks your session with Simulo and prints who you are signed in as and your active organization. --offline reads only the saved login, without contacting Simulo. If you’re not signed in, it says Not logged in. Run: simulo login.

If you belong to more than one organization, switch the active one by its slug:

simulo org use <organization slug>

Jobs, policies and assets you create belong to the active organization.

To keep a second signed-in session, for example for another account, point SIMULO_CREDENTIALS_FILE at a different file before simulo login and before every command that should use that session.

Use a token without logging in

SIMULO_API_TOKEN=<bearer-token> simulo jobs

SIMULO_API_TOKEN sends a bearer token you got some other way, such as in a script. A saved simulo login session takes precedence when both exist.

Caution

The CLI refuses to send a token over plain http:// to anything except localhost or 127.0.0.1. Use https:// for every other SIMULO_API_URL.

Pick a GPU tier

A job names the GPU tier it runs on with system=:

@app.job(type="train", system=simulo.SystemType.TIER_1, timeout=10 * 60)

simulo systems lists the tiers. It reads the catalog built into the client, so it works offline:

TIER            GPU MODEL  VRAM   VCPU  MEMORY  MAX PARALLEL ENVS  STATUS
Tier 1 (tier1)  T4         16 GB  4     16 GB   16                 available
Tier 2 (tier2)  A10G       24 GB  4     16 GB   not yet measured   available
Tier 3 (tier3)  L4         24 GB  4     16 GB   not yet measured   not yet available
Tier 4 (tier4)  L40S       48 GB  4     32 GB   not yet measured   not yet available

The tier picks the GPU model; it doesn’t change priority, and naming one doesn’t move your job up the queue. See System types for what each tier means and what happens when you name one the platform doesn’t have machines for yet.

Add Python packages to a job

Every job runs in a Simulo runtime that already includes the simulator, PyTorch, NumPy and the rest of the training stack. When your task needs a public PyPI package the runtime doesn’t have, add it to the app’s runtime in task.py:

import simulo

runtime = simulo.Runtime.from_registry("simulo/gpu-rl:2026.06").pip_install("shapely")
app = simulo.App("cartpole_demo", runtime=runtime)

simulo/gpu-rl:2026.06 is the current default runtime. Then import the package inside the job body, where it runs on the GPU machine:

@app.job(type="train", system=simulo.SystemType.TIER_1, timeout=10 * 60)
def train(num_envs: int = 16, max_iterations: int = 2) -> dict:
    import shapely

    print(f"shapely {shapely.__version__}")
    ...

Nothing installs on your machine. Simulo installs the packages on top of the runtime before the job starts. The first job with a given set of packages waits for that install, and later jobs with the same set reuse it.

• pip_install accepts PyPI names with optional extras and versions, such as "wandb==0.17.0". URLs, Git references and local paths are refused.
• Packages the runtime provides, such as torch and numpy, can’t be replaced. The submit fails if you list one.
• .env({"NAME": "value"}) on the same runtime sets environment variables for the job.

See Runtimes for how runtimes work.