Simulation

Describe an experiment once in a small YAML file, then run it headless on Isaac Sim, Isaac Lab or plain Python — as a tracked run. Caasi resolves the right interpreter, wires the environment, detaches the process and hands you back a run id.

The experiment YAML

The single input format shared by sim run, train, benchmark start and dataset generate. By convention these live in the project's experiments/ directory.

# experiments/wave.yaml
name: wave                  # optional; default = file stem ("wave")
backend: sim                # sim | lab | python  (default: sim)
script: scripts/wave.py     # REQUIRED; relative paths resolve against this YAML's directory
headless: true              # default: true
args: ["--steps", "10000"]  # optional; passed to the script
env:                        # optional; extra environment variables
  MY_ASSET_ROOT: /data/assets
python: null                # optional; explicit interpreter, overrides backend defaults
cwd: null                   # optional; working directory (default: the YAML's directory)

Key	Type	Default	Notes
`script`	path	—	Required. Missing → `Error: 'script' is required in <path>`.
`backend`	`sim` \| `lab` \| `python`	`sim`	Anything else → error listing the valid backends.
`name`	str	file stem	Used for the run name / run id.
`headless`	bool	`true`	Recorded in the run manifest; `train`/`benchmark` append `--headless` to the script args when true.
`args`	list	`[]`	Must be a YAML list.
`env`	mapping	`{}`	Merged into the process environment (yours wins over Caasi's defaults).
`python`	str	auto	Explicit interpreter; skips backend launcher resolution.
`cwd`	path	YAML's directory	Working directory of the process.

How the launch command is built

Backend	Command	Requires
`python`	`<experiment.python or the CLI's python> script args…`	nothing
`sim`	`<registered python>` or `<ISAACSIM_PATH>/python.sh script args…`	registered `tools.isaacsim` (or env/`python:` fallback)
`lab`	`<registered python>`, else `<ISAACLAB_PATH>/isaaclab.sh -p script args…`, else `python3`	registered `tools.isaaclab` for the launcher path

Caasi also sets CAASI_EXPERIMENT=<abs config path> and, for sim/lab backends, ISAACSIM_PATH/ISAACLAB_PATH in the child environment — unless your env: block already defines them.

Without a registered install

If the backend needs a tool Caasi cannot resolve you get a clear error instead of a broken launch: Error: Backend 'sim' needs a registered isaacsim install. Register one with 'caasi config set tools.isaacsim...' or use backend 'python'. (exit 1)

caasi sim run

caasi sim run CONFIG_PATH [--name NAME] [--dry-run] [-- SCRIPT_ARGS…]

Parameter	Kind	Type	Default	Description
`CONFIG_PATH`	argument	path	required	The experiment YAML.
`--name`	option	str	experiment name	Override the run name (and thus the run id).
`--dry-run`	option	flag	off	Print command, cwd and env without starting anything.
trailing args	pass-through			Anything Caasi doesn't recognize is appended verbatim to the script's argv (after the YAML's `args`).

Example — dry run first

shellcaasi sim run experiments/wave.yaml --dry-run
Dry run — nothing was started:
  command: /opt/isaac-sim-6.0/python.sh /home/you/demo/scripts/wave.py --steps 10000
  cwd: /home/you/demo/experiments
  env: ISAACSIM_PATH=/opt/isaac-sim-6.0
  env: MY_ASSET_ROOT=/data/assets

Example — launch and follow

shellcaasi sim run experiments/wave.yaml -- --seed 7
Run 20260905-142301-wave started in the background.
  Follow it with: caasi logs 20260905-142301-wave -f
caasi run status latest --json | jq '.status'
"running"

The run is created with backend: sim (or whatever the YAML says), kind: experiment, and extra: {experiment, headless} in the manifest.

JSON

sim run has no local --json; use the global flag — caasi --json sim run exp.yaml prints the full run record. And remember: the command's exit code reflects the launch, not the simulation. Check the outcome later with caasi run status.

Status, checks and lifecycle

caasi sim status

caasi sim status [--json]

Two things at a glance: is an Isaac Sim install resolvable, and which sim-backend runs are currently active (running/paused)?

shellcaasi sim status
✓ Isaac Sim 6.0 → /opt/isaac-sim-6.0
     Active Simulation Runs
  ID                     Name  Status   PID
  20260905-142301-wave   wave  running  48213
caasi sim status --json | jq '.backend'
{ "tool": "isaacsim", "version": "6.0", "path": "/opt/isaac-sim-6.0", "python": null }

Always exits 0 — an unregistered backend is reported (✗ Isaac Sim is not registered (caasi config set tools.isaacsim...)) but is not an error. JSON: {"backend": {…}, "active_runs": [run records]}.

caasi sim check

caasi sim check [--verbose]

Pre-flight check before a big launch: runs the doctor engine for the four sections that matter for simulation — isaac, nvidia, hardware, storage — and prints each check with hints for problems (or all, with --verbose).

shellcaasi sim check
✓ Isaac Sim — 6.0 at /opt/isaac-sim-6.0
✓ nvidia-smi — 550.107.02
✓ GPU 0 — NVIDIA GeForce RTX 4090 (24564 MiB)
✓ RAM — 62.7 GiB
✓ Disk (runs) — 412.9 GiB free
caasi sim check && caasi sim run experiments/wave.yaml

Exit 1 if any check fails (warnings don't fail), else 0 — made for && chains.

caasi sim stop / pause / resume

caasi sim stop   QUERY
caasi sim pause  QUERY
caasi sim resume QUERY

Simulation-flavored shortcuts for the identical run lifecycle commands (same QUERY semantics — latest, id prefix or name — same signals, same messages, same exit codes). Convenience, nothing more:

shellcaasi sim pause latest
Run 20260905-142301-wave paused.
caasi sim resume latest && caasi sim stop latest
Run 20260905-142301-wave resumed.
Run 20260905-142301-wave stopped.

caasi lab

caasi lab status

caasi lab status [--json]

Isaac Lab detection plus the two integration points Caasi cares about: the isaaclab.sh launcher and whether a ros2 CLI is on PATH for the ROS bridge.

shellcaasi lab status
✓ Isaac Lab 2.0 at /opt/IsaacLab
  Launcher: /opt/IsaacLab/isaaclab.sh
  Python: /opt/IsaacLab/_isaac_sim/python.sh
caasi lab status --json
{
  "status": "ok",
  "detail": "Isaac Lab 2.0 at /opt/IsaacLab",
  "version": "2.0",
  "path": "/opt/IsaacLab",
  "python": "/opt/IsaacLab/_isaac_sim/python.sh",
  "launcher": "/opt/IsaacLab/isaaclab.sh",
  "ros2_bridge": true
}

Detection order: registry → ISAACLAB_PATH → ~/isaaclab, ~/IsaacLab, ~/workspace/* → pip metadata. When nothing is found the status is fail with an install hint — but the exit code is still 0 (this is a report, not a gate; use caasi setup or doctor for gating).

Running Isaac Lab experiments

There is no separate “lab run” — use sim run with backend: lab:

experiments/ant.yamlname: ant-train
backend: lab
script: scripts/train_ant.py
headless: true

shellcaasi sim run experiments/ant.yaml --dry-run
Dry run — nothing was started:
  command: /opt/IsaacLab/isaaclab.sh -p /opt/IsaacLab/scripts/train_ant.py
  cwd: /home/you/demo/experiments
Note: experiment backend is 'lab', not 'sim'.

(The yellow note reminds you that sim run launched a lab-backend experiment; the run is tracked with backend: lab and appears in caasi run list like everything else.)

Previous← Projects NextTraining →

Caasi CLI 0.1.0 — these pages live in docs/ and need no build step. Source: github.com/a6y3ap/caasi.