Antioch simulation SDK

antioch-sim is Antioch's typed Python SDK and CLI. Write ordinary Python in your own project, then run it on managed cloud GPUs. Your computer needs Python 3.12; it does not need Isaac or a GPU. This guide explains customer workflows; AGENTS.md sets package rules, and the platform skill guides agents.

Projects, services, sessions, and runs

A project is a directory with one antioch.yaml. Its services are container workloads. Service names are arbitrary: sim is a starter-project convention, not a required name.

The simulator is a role determined by verified image lineage: an Antioch engine image, or an image built from one. Scenarios, suites, and Jupyter need that role. If several services use supported Antioch images, select the target in the scenario decorator. A service-only project is valid too: antioch service exec and antioch service shell default to the simulator when present, then to the only active service. Otherwise, select one with --service.

A project revision saves the manifest and exact service images. The Dockerfile installs dependencies; your project files travel separately through the manifest's sync mappings: every command that runs in a session places your mapped files there first, and new sessions and submitted runs carry a stored copy of them, a source bundle. A session is temporary compute running one project's services:

• A project can hold several sessions at once, up to your quota. A user-managed session is one you start with session new; an Antioch-managed session is one Antioch starts for scenario and suite runs. Both are yours, and session list shows them together.
• Scripts, shells, and Jupyter run in the session --session names, of either kind, or else in your only running user-managed session of the project; a command that picks the session itself prints which one it used.
• Scenario and suite runs execute on Antioch-managed sessions, two at a time per command unless --parallel says otherwise, or with --session on that session of yours, one at a time beside your own work, pinned to the images it serves. They continue without the terminal. Antioch never puts a run on a session you started unless you name it.

A scenario is a typed Python evaluation with parameters, checks, and results. A case names parameter values; a suite selects scenarios and cases. Their saved run records survive session retirement. Temporary service files do not: save results as artifacts or assets.

Mission Control provides a separate temporary development workspace. It is a client of simulation compute, not a simulation session.

Start a project

Use uv to create a project and install Antioch in its Python 3.12 virtual environment:

uv init --bare --python ">=3.12,<3.13" my-sim
uv --directory my-sim python pin 3.12
cd my-sim
uv add --compile-bytecode "antioch-sim[isaac-sim]>=0.5.0"
source .venv/bin/activate
antioch auth login
antioch init
antioch session new
antioch service exec -- python src/main.py

On Windows, activate with .venv\Scripts\Activate.ps1 in PowerShell instead of source .venv/bin/activate; on any platform, uv run antioch ... works without activating. The CLI runs on macOS, Linux and Windows; scenarios always execute in a Linux session.

The SDK resolves from PyPI. Use antioch-sim[isaac-lab]>=0.5.0 for Isaac Lab 3.0. The extra installs editor types and selects the matching starter project, not a local simulator.

For Python projects that bring their own simulator, use antioch-sim[base] and antioch init --engine base. The base image includes Antioch without Isaac Sim or Isaac Lab; scenarios use config=None.

antioch init creates the manifest, Dockerfile, source, a sync mapping, and example suites. It does not start compute. antioch session new builds the current project and starts a session, and antioch service exec runs the script there; mapped source is copied in before each command runs and local edits keep syncing while the command is attached.

The generated Dockerfile sets /workspace/project as the project directory and pins its engine image to the installed SDK version; the sync mapping delivers the files, so the image holds only the environment. The generated .dockerignore is an allowlist (* plus a !path line per file the Dockerfile copies), so synced source is not a build input: editing it keeps the build key, the image, and a running session. Package-manager upgrades and normal builds do not rewrite existing project files; to upgrade the SDK and engine image, follow Upgrade the SDK. A newer CLI can keep a supported older engine image: Antioch records its actual SDK version, and the CLI uses that returned runtime pin.

Set up agent plugins

From the activated project environment, configure the deployment's agent plugin:

antioch setup

Setup first says which agent plugins it will install or update, then configures every Codex or Claude Code client on PATH and checks your Antioch sign-in and Research connection. It reports the next step if a check fails. Use --dry-run to preview changes. Keep the environment active when you launch your agent so it can find the CLI and both MCP commands. Setup never installs or upgrades the SDK.

Define services

Antioch uses a validated Compose-style manifest, not the full Docker Compose specification. The manifest guide lists supported fields.

To bind a checkout to its intended organization, add a top-level organization_id: org_.... Use the tenant_id reported by antioch auth whoami --json. Remote CLI and SDK operations from that project refuse a different authenticated organization before submitting work, including asset uploads and reuse of a live session. Antioch never switches organizations automatically: use antioch auth switch --org org_... or provide the matching personal access token. An opaque token requires a read-only identity lookup. Omitting the field preserves the active-organization behavior. Local manifest validation and antioch auth remain available when the organizations differ.

schema_version: 6
id: warehouse-sim-0123456789abcdef
name: warehouse-sim
scenario_paths: ["src/scenarios.py"]

services:
  physics:
    build:
      context: .
      dockerfile: Dockerfile
    resources:
      gpu: rtx-pro-6000
    sync:
      - source: .
        target: /workspace/project

  autonomy:
    image: registry.example.com/robot/autonomy:release
    depends_on:
      physics:
        condition: service_started
    restart: on-failure

suites:
  smoke:
    description: Fast simulation checks
    select:
      - tags: ["smoke"]

Each service declares exactly one image or build. A build selects a context and Dockerfile for the service's dependencies; project files reach a service through its sync mappings, and a service without one runs from its image alone. An image from a private registry needs antioch auth registry login HOST first (private registries). Services may declare dependencies, health checks, resources, restart policies, named ports, and profiles. Service names are also network names within the session.

A top-level region: pins every session of the project to one region, us-central or uk, including the sessions Antioch starts for your runs; a service's resources.region is accepted as the same pin. It is a hard requirement, not a preference: a region no machine serves is refused at once, and a run waits as queued, waiting for capacity (waiting for a machine in uk) while the region has no free machine. Omit it and Antioch places each session in this order: a machine that is free now, the machine your project released in the last 15 minutes, the region nearest you by the latency the CLI measured, then the region that needs the fewest new machines. antioch session list --verbose and antioch scenario list --verbose add a REGION column.

An engine Dockerfile uses a versioned base:

FROM antioch-engine/isaac-sim-6.0.1:0.5.0

Public external FROM bases may use tags such as python:3.12-slim. Antioch freezes each base to an exact digest before computing the build key, without changing your Dockerfile. Use @sha256: to select a fixed base yourself. A new preparation can pick up a moved tag; saved revisions keep their exact images. The manifest's image field may also use a tag. Every session keeps its manifest, revision, images, and containers unchanged.

Antioch supplies its pinned Dockerfile frontend. Remove a leading # syntax=... directive: selecting another frontend is not supported and is refused locally before a build starts.

Connect named ports

antioch service ports --serve serves declared forward mappings on local loopback addresses. For a service-to-client route, set the local destination explicitly, for example:

antioch service ports --bind physics.callback=127.0.0.1:9090 --serve

The service connects to 127.0.0.1 at its declared callback port. The CLI relays those bytes to your local port 9090. TCP connections and UDP source endpoints stay separate. Each reverse registration permits 32 concurrent peers; idle UDP associations expire after 60 seconds. A blocked peer has a bounded buffer and is closed instead of blocking its siblings. Stop the command to close its listener and peers. Port forwarding alone does not keep the session active. Reverse ports require the current CLI and a fresh session with support.

Open a Viser viewer in Mission Control

Declare the existing Viser port and select it as the service's viewer:

services:
  sim:
    build: {context: ., dockerfile: Dockerfile}
    ports:
      - name: viser
        port: 8080
        protocol: tcp
        direction: client-to-service
    viewer:
      type: viser
      port: viser

Omitting viewer preserves the default Omniverse/Isaac WebRTC stream on Isaac Sim and Isaac Lab services; base compute has no implicit video viewer. To select that explicitly, set viewer: {type: omniverse} on a native-video-capable service. Omniverse uses that service's native stream routes and does not accept a port. Each service can declare its own viewer, so multiple Viser and native services can coexist. Mission Control follows the active service by default; its Viewer service picker pins a specific service or returns to automatic selection. Opening the same Viser service from multiple browsers is also supported; shared controls belong to the app.

The old x-antioch manifest extension is no longer accepted. Move its viewer directly onto the service and remove runner; select scenario targets with service= and CLI targets with --service. Retained session history stays readable, but revisions containing the retired extension cannot be rerun or adopted. Update the manifest and run again with the current CLI to freeze a new revision.

Use Viser's single-file browser client (1.1 or later; validated with 1.1.1). Your service or interactive Python process must start viser.ViserServer on that exact port. Newton's ViewerViser and custom Viser applications can use this endpoint; the console displays their own scene and controls. For example, this standalone process exposes a button that changes the scene:

import time
import viser

server = viser.ViserServer(host="0.0.0.0", port=8080)
box = server.scene.add_box("/box", dimensions=(0.2, 0.2, 0.2))
button = server.gui.add_button("Toggle box")


@button.on_click
def toggle(_event):
    box.visible = not box.visible


while True:
    time.sleep(1)

Start a session from that revision, start the viewer process, and choose Open interactive viewer in Mission Control's Sessions pane. Camera movement and authored controls stay interactive. Rerun telemetry remains separate. The viewer reconnects when its five-minute access ticket expires; server simulation continues during that reconnect. Viewer access is restricted to the session owner. The console does not automatically add pause, step, or force controls to Python.

Update a running session

A sync mapping names a project-relative source (. for the project root), an absolute target at or below /workspace/project, and optional exclude patterns on top of the built-in floor (VCS metadata, virtual environments, caches, outputs/). Anything git ignores stays local too, even a file a mapping names: .gitignore files from the project root down (never from folders above it), .git/info/exclude, and your global excludes file. Mappings only copy files; a service with no mapping runs from its image alone.

sync:
  - source: src
    target: /workspace/project/src
    exclude: ["fixtures/**"]

A source may start with ../ to reach code beside the project, such as a sim/ project folder next to the robot_src/ repository it runs. That source follows the ignore files of the repository holding it, and it must exist wherever you run the command:

# sim/antioch.yaml
sync:
  - source: scenarios
    target: /workspace/project/scenarios
  - source: ../robot_src
    target: /workspace/project/robot_src

antioch service restart

The session's machine restarts one service at a time in depends_on order: it stops the process, killing it once stop_grace_period runs out, starts it again, and waits for its fresh health check before the next. A scenario run executing on the session blocks it. A dependent restarts too when its depends_on entry opts in, after the dependency meets the condition again:

services:
  physics:
    image: registry.example.com/robot/physics:release
    healthcheck:
      test: ["CMD", "test", "-f", "/tmp/ready"]
  bridge:
    image: registry.example.com/robot/bridge:release
    depends_on:
      physics:
        condition: service_healthy
        restart: true

A service that exits or fails its health check after restarting fails the restart, which names it. Health check failures count only after its start_period, 300 s unless set, so a service that never passes fails the restart then. A service with no effective command stays idle, and restart does nothing. Restart replaces only a service's own command: it neither finds nor stops a command you started in the service with service exec or service shell, such as a ros2 launch in a service with no command, so stop that command itself. A long-running service command keeps the files it started with until you restart it.

Leaving out entrypoint and command does not make a service idle. As in Compose, the service then runs its image's own ENTRYPOINT and CMD, and an empty command alone still runs the image's entrypoint. An image built FROM ros:jazzy runs /ros_entrypoint.sh bash, which exits at once without a terminal, and a service that exits fails the session unless another service waits for it with service_completed_successfully. To keep a service idle so you can antioch service exec into it, clear both, or pass --idle SERVICE to antioch session new to do this for one session:

services:
  ros:
    build: ros
    entrypoint: []
    command: []

When a service fails because it exited while running a command its image chose, the failure names that command and this recipe.

service ps shows each service's own command under COMMAND: its entrypoint and command joined as Compose joins them, or its image's when it sets neither, the command docker ps would show. A service that idles shows —. ALSO RUNNING lists what you started beside it with service exec, service shell, jupyter or a scenario run, which service restart never touches. PHASE is the service's own command's state: running while it runs, and also for a service that idles with none.

You do not push edits yourself. service exec, service shell, and jupyter make the session's mapped files match this checkout before the command starts, sending only what changed, and keep copying local edits while the command is attached. Your checkout always wins: a synced file edited inside the session is overwritten by the next command, so download anything you want to keep with antioch service cp first. Sync deletes only files it placed, so what the session created elsewhere stays. A file the session made where your checkout has one is replaced too; a folder in the way is renamed to NAME.antioch-displaced-ID, not deleted, and the command says where it went. A changed file resends whole, so exclude a large file that changes often, or copy it once with antioch service cp, which later syncs leave alone. Sync prints what it uploads; a file of any size gets there, sent in parts when it is large. A file still being written waits for the next pass. If a run installs its saved source, an already attached command leaves it in place until you edit a local file or start another command. Commands on an Antioch-managed session sync the same way. To reach the session a run is on or ran on, pass --run RUN_ID instead of --session; the command then acts exactly as if it had named that session. service exec, service shell, service logs, service ps, the jupyter commands, and scenario run, suite run and their reruns take it:

antioch service shell --run RUN_ID

A run that never reached a session, or whose session has stopped, leaves nothing to reach, and the command says so in one line.

antioch service ps --json reports process_healthy for each service: the supervisor has no uncontained processes. It does not report that service's application health check. session_ready reports the latest aggregate session readiness, including authored health checks, and is repeated on each row. Use antioch session status --json to read the session's readiness conditions.

New sessions, release, and idle policy

After an image or dependency change, run antioch session new and release the old session. antioch session new adds a session built from the current manifest and images and starts it on this checkout's current files; the project's other sessions keep running until you release them or they go idle, and while more than one runs, commands name theirs with --session. Pass --profile or --revision there to choose what the session runs, or use it to have a session ready before the work. One quota bounds how many sessions you hold across your projects, and one bounds your organization. Antioch-managed sessions count too. At your limit, antioch session new refuses at once, saying how many of your limit are in use and naming a few sessions to release, idle ones first; --json names every session and what it is doing. Release one with antioch session release SESSION_ID: from that moment it no longer counts against your limit or your usage, while Antioch tears it down. Or wait: an Antioch-managed session stops after five idle minutes. Antioch never stops a session to make room. Build or quota failure does not change the existing sessions.

To choose a workflow, a scene, or how an entrypoint behaves without editing the manifest, start the session with environment variables. Each --env NAME=VALUE is set in every service, over the value antioch.yaml gives it:

antioch session new --env DEVELOP=motion
antioch session new --env SCENE=dtv2_2f_rpi5_stack_assembly --env LOG_LEVEL=debug

The variables freeze into the session's revision exactly as if antioch.yaml set them, so no image rebuilds: the same variables reuse the same revision, and a new value freezes a new one. antioch session status shows each service's environment, so never pass a secret this way. Names Antioch sets itself, such as ANTIOCH_* and PYTHONPATH, are refused. Runs submitted without --session start Antioch-managed sessions from antioch.yaml alone. See antioch session new --help.

antioch session list shows the project's sessions and who manages each. Use --all-projects to include your other projects. Outside a project, the command lists them all. antioch session status SESSION_ID and antioch session release SESSION_ID take any session of yours from any directory. A bare antioch session release releases your only running user-managed session of the project, without a confirmation prompt. Releasing a session that already stopped or failed succeeds and says so. A session running commands you started, such as a script, a shell or JupyterLab, is released only with --force, which stops them. A scenario run executing on a session never holds its release: the run is cancelled. Releasing an Antioch-managed session ends its run as session released, not a failure; the rest of those runs continue on other sessions. Save remote files before you release a session.

A session is in use while any of these holds, and idle otherwise:

• a command runs in it: a script, service exec, or a service shell;
• a scenario run is running on it or queued for it;
• a Jupyter kernel runs a cell, even after its client left;
• a client is connected: a port-forward connection, which includes a browser or agent using JupyterLab or a kernel, or a sync applying files.

JupyterLab and its kernels do not keep a session in use just by running: a Lab with no browser connected and no cell running is idle, and its kernels keep their variables until the session ends. Stream viewers, status reads, logs, authentication, an open console tab, a forward with no open connection, and persistent authored services do not keep it in use either. Fifteen minutes after it falls idle the session stops, with a short reconciliation delay; an Antioch-managed session stops after five. Start a session with another idle timeout, at least a minute, or with none:

antioch session new --idle-timeout 2h
antioch session new --idle-timeout never

A never session runs until you release it; --json carries idle_timeout_s, 0 for never. session status says what keeps a session in use, such as in use: 1 exec/shell command, 1 connection, or since when it has been idle and when it retires, such as idle since 12:03:04 UTC, retires 12:18:04 UTC, and names its idle timeout. session list shows the same under ACTIVITY, observed about every half minute. Save remote files before the session retires or you release it. Disconnecting a terminal does not end its process; leave the shell or stop the command when you are done with it.

Put CLI options before the service: antioch service shell --session SESSION_ID nav. Tokens after the service are the remote command, not CLI options.

If the agent cannot report what the session holds, Antioch leaves the session running without extending its idle deadline. This avoids stopping work on an incomplete observation. Sessions with older agents need a new session to use this policy. At expiry the CLI and console show an idle-expiry hold, the affected services and known reasons; compute continues accruing usage until it is retired. Upgrading a local SDK does not change an already running session's agent or containers. Save remote files before an owner-approved release. Downloaded scenario artifacts and retained results survive retirement; arbitrary container files and notebook/editor memory do not.

Preparation checks whether the declared resources fit a serving cell before uploading source, building, or copying images. This check reserves no capacity; admission checks the final revision again. Standalone builds do not need compute capacity.

Sync exclusions and build source

A mapping copies every file under its source except the built-in floor, what git ignores, and its own exclude patterns, which do not support ! negation; .dockerignore never filters a mapping. A symlink syncs as a link when it points inside its mapping; any other symlink is skipped with one warning. Deleting a local file or directory removes the copy the mapping previously placed; files the session created on its own are left alone. Commands remain usable while a path is absent, and recreating it syncs the new bytes.

Source capture for builds has different rules. It applies the platform floor (.venv, venv, .git, Python caches, and node_modules) plus .dockerignore, not .gitignore. The generated .dockerignore ignores everything, so a build sees only its configured Dockerfile (Dockerfile.sim too), its context's .dockerignore, and the paths you admit with !, such as !requirements.txt for a file the Dockerfile copies (!dir and !dir/** for a directory). The platform floor is never traversed or included, even for a Dockerfile or an explicit ! pattern. User-ignored directories are still visited so a later ! pattern can retain a descendant, and nested build contexts keep their Docker files. The selected context's .dockerignore is applied again with Docker semantics. Excluded paths do not count toward source limits. Special files (FIFOs, sockets, and device nodes) are rejected; exclude them with .dockerignore if they are not needed.

A build shows its step line with the newest five lines of its log beneath it while it runs; the window closes when the image is built. -v on session new prints every log line instead, and a redirected stream prints none unless -v asks. A failed build prints the end of its log, up to its last 100 lines, and then one line saying what failed and what to do.

Work in a session

Run commands from the project directory. Every command runs on the session --session SESSION_ID names, user- or Antioch-managed, or else on your only running user-managed session of the project. With none running, the command says to start one with antioch session new; with several, it lists each one's ID, age and services and asks for --session. No command starts a session or moves to another one on its own, and a --session naming a released session is an error. A command that picks the session itself, without --session, prints the session and service it used, with the idle deadline when it read the session from Antioch. Outside a project, a command that needs a session refuses.

antioch session new
antioch service exec -- python src/main.py --seconds 60
antioch service exec --stream python -m src.main
antioch service exec --service autonomy -- ros2 topic list
antioch session list
antioch service ps
antioch service logs --service SERVICE
antioch service shell --service SERVICE
antioch service cp SERVICE:/workspace/project/output.png ./output.png
antioch service exec --session SESSION_ID -- nvidia-smi
antioch service shell --run RUN_ID
antioch session status
antioch session release
antioch session release SESSION_ID --force

antioch session new prints a brief confirmation and the session ID when it is ready. Use antioch session status for the revision, services, resources, and readiness details.

The same commands are methods of the public client, which resolves the session the same way and takes session= wherever the CLI takes --session:

import antioch

client = antioch.Client()
process = client.service.exec("nvidia-smi", session="ses-...")
runs = client.scenario.run("falling_cube")  # Antioch starts sessions for the runs

A client prints nothing; the session and service a call picked itself arrive as notices on the sink Client(on_notice=...) names. A call that finds none, or several, of your sessions running raises SessionUnavailable, which lists them when there are several.

Terminal lists keep IDs and the main status fields together. Add --verbose to session list, scenario list, or suite list for additional metadata. IDs remain complete on narrow terminals; rows wrap when they cannot fit.

scenario list and suite list show up to 10 matching runs by default. Add --mine to show your own runs, or --limit 25 for a longer list (up to 200). With --json, both commands default to 50 runs, and next_cursor is what --cursor continues from.

session list shows your active sessions for the current project: their state, who manages them (you or Antioch), revision, what keeps them in use, and idle deadline. Activity counts runs, exec/shell commands (what service exec and service shell started), running notebook cells and connections, never a service's own command: session status names when each service's own command started on its primary row, and session status --json keeps that as runtime.services.SERVICE.primary_started_at beside processes, which counts only exec/shell commands, runs and running cells, so processes: 0 does not mean the service's own command has stopped. A service with no command has no primary entry. Add --verbose for GPU and region, or --limit for a shorter list. JSON also includes failed sessions. session status SESSION_ID shows the full record, including the invocation it serves. Cancel a scenario run with scenario cancel or suite cancel; releasing its session cancels it too.

Human session list and session status output uses the same concise readiness phrases as the console. These commands read durable session records, so Session ready does not claim that commands are idle. Use service ps for each service's live phase, its own command, what else runs in it, and its routes. JSON retains the original lifecycle states and diagnostics.

Copy files

service cp and source sync travel over the session's own connection and need nothing installed locally; only content the session does not already hold is transferred. A copy is independent of the manifest's mappings: use it to bring a result home, or to place a file that no mapping covers.

Copy preserves relative symbolic links inside the copied tree. Uploads and downloads with service cp accept only paths inside /workspace/project in the service: the session agent that copies runs with more privilege than the service's user, so it stays where that user's files live. Other paths, including /tmp, are refused. Use service exec to copy a file into the project before downloading it, or to its final service path after uploading it into the project. The command runs with the service's normal file permissions, and an uploaded file is not owned by any mapping, so later syncs leave it in place.

Execute commands and attach terminals

antioch service exec -- python src/main.py runs src/main.py in the service's configured project directory (/workspace/project in generated projects). service exec runs any command, including Python modules and helper-service tools. It streams process output, returns its exit status, and runs until the command ends or you press Ctrl-C; --timeout sets a deadline. A native script starts Isaac itself, usually through antioch.start_simulation().

Pass Antioch options before the executable, or end them with --; the command and its arguments are passed unchanged, repeated flags included. Use --service autonomy for a helper; a helper named python never changes the meaning of python main.py.

What a session runs is chosen when it starts. Services without profiles are the default set, and they all start together. Each --profile PROFILE adds the services that name that profile. If every service has a profile, select one explicitly; an empty selection reports the available profiles and never enables them all. --idle SERVICE starts that service's container without its command, so you can run it yourself in dev mode while the rest of the stack runs. --env NAME=VALUE sets a variable in every service:

antioch session new --profile debug --idle sim --env SCENE=dtv2
antioch service exec --service sim -- python -m src.main --debug

An idle service behaves as if antioch.yaml gave it entrypoint: [] and command: [], so its image's own command does not run either. Its healthcheck is dropped, and services that wait for it to start or be healthy start once its container is up. A service that waits for it to complete is refused, because an idle service never completes. Like --env, --idle freezes into the session's revision without rebuilding an image, and session status lists the idle services.

Source enters a session at startup and before every service exec command; local edits keep syncing while the command is attached. Ctrl-C during that sync stops it at once: the session keeps the files that fully landed, and the next command sends the rest. A scenario run executing on your session runs beside your commands; nothing is refused or moved to another session.

Both commands forward stdin until EOF and return when the remote process exits, even if local stdin stays open. When stdin and stdout are terminals, they allocate a terminal and forward window-size changes. Use --tty or --no-tty to override detection. Terminal output is one channel; non-terminal execution keeps stdout and stderr separate. A slow reader, such as a pager, holds the command back instead of losing its output; a reader that stalls for more than about 30 seconds can lose its stream, and [antioch] output gap then names the bytes the session could not keep. antioch service shell uses the same transport for an interactive shell. Raw commands do not create scenario or suite history. The default Bash shell loads the image's login profiles and shows the current path in cyan followed by >. NO_COLOR or a monochrome terminal gives a plain prompt; an image's own prompt hooks take precedence. Pass an explicit command, such as antioch service shell -- bash -l, to use the image's own prompt. Modern ANSI terminals use TERM=xterm-256color inside the service, without requiring vendor terminfo for Ghostty, Kitty, Alacritty, WezTerm or Foot. Basic terminal capabilities are preserved; tmux uses the portable screen equivalents. GPU and software rendering use the same PTY transport. PTYs have no write-half-close: with explicit --tty, local EOF (Ctrl-D, or Ctrl-Z then Enter on Windows) sends no synthetic Ctrl-D. Use --no-tty for a piped program that must read until EOF.

Stream and choose picture quality

Each Isaac service has one native GUI stream. Commands run headless unless you pass --stream, because rendering a stream nobody watches can halve simulation speed. --stream on service exec, service shell, scenario run, suite run or jupyter cell streams the process to Mission Control; SimulationConfig(stream=False) keeps a process headless even then. A second process in the same service cannot claim an occupied stream. Mission Control displays one selected service at a time and follows the active scenario across services.

Scenario runs use their authored SimulationConfig(timeout_s=...) unless --timeout overrides it. A native script's outer process deadline remains the CLI deadline.

Kit's default viewport renders every frame only while it is streamed, so it is paused by default. Code that paces on it, such as Replicator's rep.orchestrator.step, keeps it rendering without a stream with SimulationConfig(viewport_updates=True). It renders only on frames Kit updates; Isaac Lab's sim.step() updates Kit only with a Kit visualizer.

A streamed viewport also flies from the keyboard, because Kit's own fly mode needs a held right mouse button that a trackpad cannot give a browser. Arrows move, Shift + arrows look around, Ctrl + Up/Down or Shift + E/Q rise and descend, - and = scale the speed, and holding X or Z doubles or halves it. Code that reads the same keys, such as Isaac Lab's Se2Keyboard teleoperation, turns this off with SimulationConfig(keyboard_navigation=False).

Pick the picture quality in code before startup:

import antioch

antioch.start_simulation(antioch.SimulationConfig(renderer_quality="quality"))

renderer_quality is the one picture control. Each tier sets a stream budget, the largest picture the encoder sends, and the RTX startup settings. The browser keeps its own window shape and fits its screen pixels to the 32-pixel encoder grid, at most one grid step above them. Up to the budget the picture is pixel exact; above it the browser scales the picture up. These RTX settings can also affect sensor render products that use them:

A streamed process boots at 1920×1088, and the native livestream resizes the window to what the browser negotiates inside the budget. Headless work does not start the stream encoder and renders the main viewport at 1280×720; use extra_args native window or renderer settings to change that. Sensor camera sizes never change with the preset.

Streaming keeps the native 60 FPS default. Antioch has no FPS control. Displayed FPS measures video delivery, not physics steps or a guaranteed rate. Native quality-of-service feedback can adjust delivery. physics_dt, render_dt, and notebook idle rendering remain separate. Retired stream_fps inputs are ignored with an ANTIOCH-DEP-010 notice.

The native renderer decides which settings apply to each render product. Retired renderer inputs are listed in common.deprecations.

Explicit extra_args override preset flags; those arguments come last. After startup, normal carb.settings or SimulationApp.set_setting() calls remain yours; Antioch does not reapply the preset. The retired render_quality, viewport, and stream_resolution inputs are ignored with ANTIOCH-DEP-008, ANTIOCH-DEP-009, and ANTIOCH-DEP-013 notices. Their values are not forwarded; a fixed stream size is no longer a setting. Unknown input names still fail validation.

Process exit status

After antioch.start_simulation(), a clean exit returns 0, an uncaught exception returns 1, and KeyboardInterrupt returns 130. Use sys.exit(n) for an explicit status: a bare top-level raise SystemExit(n) in a headless script can return 0 through Isaac's fast shutdown. Replacing sys.excepthook without chaining the prior hook also replaces this error handling.

Use Jupyter

Jupyter runs in the session --session names, or else in your only running session of the project. It uses the session's simulator service and places this checkout's synced files there before the server starts. When several compatible services are active, choose one with --service on jupyter lab, jupyter cell, and jupyter stop, for example antioch jupyter lab --service nav. The Jupyter MCP's jupyter_connect accepts the same service selector, and session with a session ID when you have more than one running. Each service's notebook server and credentials remain independent; stopping one leaves the others running.

antioch session new
antioch jupyter lab
antioch jupyter cell "1 + 1"
antioch jupyter cell --stream "import antioch; antioch.start_simulation()"
antioch jupyter stop

Lab uses the service's reserved jupyter route. Cells execute on its live kernel through Jupyter's REST and WebSocket APIs; a kernel starts if needed. Use cell --kernel KERNEL_ID when Lab has several kernels. Without an explicit ID, the CLI uses the sole kernel and refuses an ambiguous selection. JupyterLab owns kernel management. Restart replaces only the kernel process, not its simulation container or session. Failed new server startup stops that server; an existing server is left running. A kernel outlives the command that started it and keeps its variables until the session ends; it keeps the session in use only while it runs a cell or a client is connected (idle policy). jupyter stop stops the server and its kernels at once. Kernels start Isaac headless. A cell's --stream travels in its metadata and applies only during that cell's execution. Use it on the cell that starts Isaac, not an earlier cell. It does not reconfigure a simulator that is already running, and later cells keep the stream the simulator started with. Older kernels still accept ordinary cells but refuse --stream and --no-stream before running the cell; start a new session.

jupyter cell --json writes a successful result to stdout. A failed cell exits 1 and writes one error object to stderr. Its error.details.cell_result keeps the kernel ID, execution count, stdout, stderr, display result, and exception details that Jupyter returned. Connection and timeout failures do not invent a cell result. The CLI does not retry the cell. The result's ordered outputs retain rich MIME data, including PNG images, display updates, and clear events. Output is capped at 8 MiB; outputs_truncated reports omitted messages while the CLI still waits for the cell's final result. Plain terminal output shows text and names image-only output; use --json to receive image data.

The kernel renders between cells and during cooperative await calls. It does not advance physics or require a World wrapper. Long main-thread loops must yield or call native Isaac updates. Python cannot render concurrently with a blocking native call on that same thread. Interrupt or restart the kernel to recover; a restart must not require a session reset.

jupyter lab prints and opens a private file:// launch URL. With --no-open, open that exact URL in a browser on the same computer, with access to the same filesystem. The file signs in to the verified loopback Lab server without printing its token. Keep the command running: its local tunnel and launch file close when the command ends. Ctrl-C ends only that connection: the server and its kernels keep serving other commands until the session ends. A browser on a different computer cannot use this local file or loopback address directly.

Use agent tools

The paired plugin's agentic-simulation skill teaches the interactive loop. antioch-jupyter-mcp connects to this project's existing session, selects a kernel, executes arbitrary Python, returns ordered text and images, and controls the selected kernel. While connected it keeps the project's synced files applied, so a cell can reload a module edited locally. It does not allocate compute or inject simulator code. The CLI owns project files, session creation, dispatch, and recorded evaluations.

After starting simulation once, ordinary notebook code can move the inspection camera and display a fresh frame:

from IPython.display import display
from antioch.lib import navigation, viewport

navigation.look_at(eye=(3, 3, 2), target=(0, 0, 0))
display(await viewport.observe_async())

Capture advances rendering, not physics; metadata reports unavailable frames. Inspect the pixels and measured state before claiming success. Interrupt requests a stop, not confirmed completion. Restart loses Python state: restore it from saved source, never replay uncertain side effects. Disconnect closes only local transport; idle transport also closes after 60 seconds. A kernel lasts until the session ends; kernel shutdown and GPU session release remain separate explicit actions.

Evaluate scenarios and suites

Keep Isaac imports inside functions. Scenario discovery runs locally without a simulator. The scenario guide and shipped examples cover authoring.

A scenario can select its execution container with @antioch.scenario(service="fluoro", ...). Omitting service selects the only active service derived from a supported Antioch image. With several eligible services, name the target explicitly; leave services without profiles to start them together. Each child of a suite runs in its selected container on the session the submission resolved. Reruns retain those targets.

Live Rerun telemetry follows the active scenario container. Every scenario in a session serves it while it records, with or without --stream, so the console can show a run live. The telemetry port belongs to the latest scenario: a process whose scenario has finished hands it over, and a scenario that starts while another process is still recording or serving Rerun itself warns and keeps only its saved recording. Authored viewer ports remain attached to their services. Native Isaac/WebRTC video follows the selected service when it provides a stream; selecting another container does not silently change rendering settings.

Submit and follow managed runs

antioch scenario collect
antioch scenario collect falling_cube --json
antioch scenario run falling_cube --set drop_height=4.5
antioch scenario run cube_bounce --set drop_height=1,2 --set restitution=0.5
antioch scenario run cube_bounce --all-cases
antioch suite collect
antioch scenario run 'cube_*' --tags smoke,physics
antioch suite run smoke
antioch suite run smoke --detach
antioch scenario list --invocation-id INVOCATION_ID --follow
antioch scenario show SCENARIO_RUN_ID
antioch scenario show SCENARIO_RUN_ID --json
antioch scenario download SCENARIO_RUN_ID
antioch scenario download --invocation-id INVOCATION_ID
antioch scenario rerun SCENARIO_RUN_ID
antioch scenario cancel SCENARIO_RUN_ID
antioch scenario cancel --invocation-id INVOCATION_ID

One selection language chooses runs everywhere: the options of scenario run and scenario collect, a suite's select: entries in antioch.yaml, and Python keywords spell the same nine fields. Names, --paths, --tags and --exclude-tags choose scenarios; --cases, --all-cases and --rows choose which rows of each scenario run; --set overrides parameters on every row. A name with * or ? matches like a shell glob, and a glob that matches nothing is refused like an unknown name. The plural options take comma lists and repeat: --tags smoke,physics is --tags smoke --tags physics.

A scenario runs once with its declared defaults, even when it declares cases. --cases CASE_ID runs declared cases, --all-cases runs every declared case, and --rows @FILE (a JSON or YAML list of mappings, or inline JSON) runs exact parameter rows. --set PARAM=VALUE overrides one parameter on every selected run; several values for one parameter, as a comma list or a repeated key, are alternatives crossed into a grid with the last axis varying fastest, so --set drop_height=1,2 --set restitution=0.5 is two runs and --set drop_height=1 --set drop_height=2 spells the same axis. A quoted value keeps its commas: --set 'label="a,b"' is one value. In YAML and Python a list of values is the same axis (set: {drop_height: [1, 2]}). Values resolve from the scenario defaults, then the case or row, then --set. Every option applies across every selected scenario, so antioch scenario run --tags smoke --set seed=7 seeds each smoke scenario. A tag declared only on cases selects nothing until --cases or --all-cases asks for cases. The CLI names the run count before it submits, refuses a selection larger than one submission may carry, and drops a run a later selection repeats. scenario collect with any of these options previews the exact runs; antioch scenario run --help lists them all.

scenario collect alone shows the catalog: every discovered scenario with its parameters and cases. Collection validates every scenario under the selected paths, and --json emits the runs and the definitions. The earlier --scenario NAME spelling still works, and a bare path given to scenario collect in place of a name still works with an ANTIOCH-DEP-018 notice.

A selection of several runs is submitted as one batch that shares an invocation ID; there is no suite behind it. antioch scenario list --invocation-id ID --follow watches the whole batch from any terminal, and antioch scenario cancel --invocation-id ID cancels its unfinished runs while finished ones keep their outcome. A named suite stays what its author declared: suite run never narrows or expands it.

scenario show summarizes the verdict, duration, checks, artifacts, and any failure or wait reason, and previews the first scalar results as name = value; in terminals, parameters appear as a count. Use --json for the complete saved record, including all parameters, results, check details, errors, and startup logs. A run's duration is from its start to its completion, including saving its results, wherever it is shown. scenario download puts a run's artifacts under outputs/SCENARIO_RUN_ID/; --invocation-id ID downloads every run of a batch, one folder per run. A file that already holds an artifact's exact bytes is kept, so running a download again needs no --force. A run waits for completion and exits with the run's verdict by default; combine it with --json for complete records as JSON events. Add --verbose to stream process output while waiting, or --detach (-d) to return right after admission.

Every scenario and suite run is submitted to Antioch; nothing runs in your terminal. By default Antioch builds a fresh revision from the current manifest and runs them on sessions it starts for you, leaving your sessions alone:

• Runs queue oldest first.
• One scenario run or suite run runs at most 2 of its scenarios at once. --parallel 4 runs up to 4, and your session limit still caps it (antioch auth whoami shows it). A command at its cap does not hold back your other commands.
• A run takes an idle Antioch-managed session of the same project and revision. Otherwise Antioch starts one if your session limit allows. Otherwise the run waits.
• Antioch never stops a session to make room. An Antioch-managed session stops after five idle minutes.

With --session SESSION_ID the runs queue on that session of yours instead and execute there one at a time beside your own work, which keeps running. Those runs pin the revision the session serves, so nothing is built or prepared for them. Each run carries the files it was submitted with, its source bundle, and the session applies them when the run starts, so an edit followed by a run works whether or not the image copies the source. A queued run applies its own submitted code when it starts, so edits synced to that session in between are overwritten until the next command syncs them again. The bundle reaches every mapped service, but only the scenario's restart_services restart: another running service whose files differ from the ones it started with keeps running its earlier code. The run's verdict and scenario show name it and the antioch service restart command that restarts it on that session; adding it to the scenario's restart_services restarts it before every run, with its restart: true dependents. A run waits for every other service to be ready before it starts, and fails, naming the service, if one is failing its health check. A restart that fails fails the run by naming the service. Image or dependency changes still need a new session. An Antioch-managed session can be named the same way. Submission stores the source bundle and starts any builds, then submits the runs; a failed build fails them with its cause. The command waits for the verdicts unless --detach returns once the runs are submitted, printing the command that follows them. --json with a follow streams one JSON object per state change, and --json --detach prints the submitted runs; interrupting a follow detaches from the runs. Mission Control submits without following and watches the returned IDs. scenario rerun and suite rerun take the same --session, --parallel, and --detach: a rerun keeps its origin's revision, so it runs on an Antioch-managed session, or on the session of yours you name when that session serves the same revision; either way it runs its saved files and needs no checkout. Suites also have show and cancel commands.

--queue-timeout 30m bounds how long a run waits for a machine or a session, counted from when Antioch accepts it once this command has saved and uploaded the project; a build still running then counts toward it. Once a session is starting for the run, or the run is queued behind another on a session that is up, the bound no longer applies. A run still waiting for capacity at its deadline fails with one queue timeout line: how long it waited, what it waited for, and a longer --queue-timeout to run it again with. Without this option, the deadline is one hour after admission; an explicit one may be up to 24 hours. While it waits, a run shows queued, queued, waiting for capacity when no machine is free, or queued, waiting for your session limit, 4 of 4 in use when your session limit is full. --timeout 900 separately limits each scenario's execution to 900 seconds; if omitted, it uses the scenario's configured value or 900 seconds. Both take seconds or a duration such as 90s, 30m or 2h, as does service exec --timeout.

Scenario and suite commands show progress and verdicts while waiting for completion. Add --verbose to include captured process output, including Isaac startup logs. --stream controls the viewer stream; it does not control terminal logs. Direct commands (antioch service exec) still stream their process output by default.

Call scenarios from session code

A scenario called directly records only inside a session: in a command started with antioch service exec, or in a shell or notebook on the session. The run is saved like any other, with its results, telemetry, and artifacts, and it runs beside your process instead of waiting behind the session's queued runs.

import antioch

with antioch.Scenario("inspection", capture=False) as run:
    run.raise_if_cancelled()  # An explicit cooperative checkpoint, not a worker
    run.check("inspected", True)

A decorated scenario's Python callable omits the injected run argument and returns run.results; calling it records the same way. A function with simulation config still requires a simulator that you have already started. A context in a notebook cell or REPL saves its source as <kernel> and cannot be rerun from history; execute the cell again instead.

Outside a session, a direct call stops with one line that names antioch scenario run NAME and antioch service exec. Use Scenario(..., control=None) for deliberate offline execution; a missing session never selects offline mode for you. Cancelling a run records the intent: your code stops cooperatively at run.raise_if_cancelled() or when the context closes, and Antioch closes the run shortly after if it does not. If your process exits or the session ends first, the run closes with the results it had saved; Antioch never signals your process.

Capture viewport images and telemetry

For an authored viewport image, call antioch.capture_viewport() between physics steps on the main thread, outside physics, render, and Kit-update callbacks. Headless and streamed processes use the same native viewport. Set its camera or resolution with ordinary Isaac APIs, then capture. The function waits for a new frame before pixel read-back and drives render-only updates for up to ten seconds. It returns RGB pixels, or None if no viewport or completed frame is available. It never returns an earlier call's cached image or advances physics. Asset loading and scene lighting remain native Isaac behavior. Callback contexts are unsupported and are not automatically detected. Automatic recording is asynchronous: it uses authored render updates and never renders from a physics callback. Code that disables rendering must render explicitly when it needs images.

The scenario-design skill owns capture and telemetry guidance. Native renderer readiness and material settling are separate from a completed capture: Kit being app-ready does not mean its viewport has rendered a frame. Before the first capture, call ViewportManager.wait_for_viewport() (or await ViewportManager.wait_for_viewport_async() in a notebook) and check the returned readiness flag. Choose max_frames for renderer startup; this setup wait is separate from capture's ten-second read-back deadline.

Log the returned RGB array with antioch.Logger("camera").image("front", rgb). The first frame, downsampled to max_width, sets that entity's canvas for the current recording. Later frames keep their aspect ratio and fit inside it; black borders fill unused space. They are not cropped, stretched, or upscaled. max_width still limits content resolution and jpeg_quality applies to each frame. Another entity or a new recording chooses its own canvas. This keeps live and saved Rerun playback compatible when the source viewport resizes.

Recover recordings

If artifact upload or terminal acknowledgement fails, managed scenarios keep their default recording and runner output in an owner-private directory under the project and report its path. Recover that directory with service cp before the session stops. The retained files are not durable artifacts. Explicit recording paths and offline runs keep their chosen paths. A local file alone is not a durable artifact.

Follow output and cancel runs

In a terminal, each step of a command's work, such as a service build or storing the project source, shows a spinner while it runs and stays behind as a checkmark line naming what it did and how long it took. Redirected output and TERM=dumb use plain phase changes instead of animation; FORCE_COLOR never adds terminal controls to a pipe. NO_COLOR disables color without disabling progress (in PowerShell, $env:NO_COLOR = '1'). With --json, progress is a stream of newline-delimited JSON objects with no human messages mixed in.

Help stacks option descriptions in narrow terminals. With --verbose, CLI messages appear on separate stderr lines so they do not run into process output. Redirected stdout, native exec output, and JSON remain unchanged.

Ctrl-C while following a run stops the local progress display and leaves the run active; cancel it with scenario cancel or suite cancel, and pick the watch back up with --follow on scenario show, scenario list --invocation-id, or suite show. Remote cancellation and cleanup are not confirmed until the saved result says they are complete. During submission, an interruption stops the client; if the runs may already have been submitted, the CLI prints the command that shows them. A remote build that has started can continue after the client exits.

Rerun saved work

A rerun gets a new ID and reuses the original revision, service images, scenario, case, service, tags and parameters. It does not rebuild or resolve moving tags. It runs the saved source bundle and never reads your current files, on an Antioch-managed session or on one you name with --session that serves the original revision, so it needs no checkout. A runtime below the supported minimum is refused before allocation; its saved history remains readable. Exact inputs do not guarantee the same outcome or timing: scheduling, simulator behavior, and external asset availability can differ.

Same images and inputs, different values: --set, --timeout and --stream/--no-stream change a rerun's inputs and everything else stays as recorded.

antioch scenario rerun SCENARIO_RUN_ID --set drop_height=1,2 --timeout 600
antioch suite rerun SUITE_RUN_ID --set seed=7 --stream

--set spells exactly what it spells on scenario run: a comma list or a repeated key names alternatives crossed into a grid, one rerun per point under one invocation ID, so following, --json and antioch scenario list --invocation-id ID cover them all; a quoted value keeps its commas and --set key= is the empty string. A key must be a parameter the run saved, and its value takes the saved value's type: an int accepts only integers, a float accepts integers too, a bool takes true or false. An unknown key or a value of another type is refused before anything is submitted, and the grid is bounded like scenario run. Bounds and allowed values are checked before submission too when the checkout is exactly the code the run pinned; otherwise the pinned code checks them when the rerun starts. On a suite, an override reaches every member that has the parameter and a key no member has is refused. In Python, client.scenario.rerun(id, set={"drop_height": [1, 2]}, timeout=600, stream=True) takes typed values; a list is the same axis.

Run in CI with a personal access token

For an unattended workflow, open Settings > Personal access tokens, create a token with a finite expiry, and copy its secret once. Save it as a GitHub Actions repository secret named ANTIOCH_TOKEN, then pass it to the step that runs Antioch:

- name: Run simulation suite
  env:
    ANTIOCH_TOKEN: ${{ secrets.ANTIOCH_TOKEN }}
  run: antioch suite run smoke

CI needs no browser login and must not create or copy auth.json. The CLI reads ANTIOCH_TOKEN directly and does not persist it in the local credential store.

Assets

Assets are named file versions from your organization or Antioch's shared library. Pin their versions for repeatable evaluations.

antioch asset list
antioch asset show ASSET
antioch asset pull ASSET --version ASSET_VERSION --output ./asset.usdz
antioch asset push ./asset.usdz --name ASSET --version ASSET_VERSION
antioch asset verify ASSET --version ASSET_VERSION

Python offers antioch.fetch_asset, antioch.load_asset, and antioch.save_asset.

Build failures

A failed build prints the end of its build log above its error line. The JSON error's message is that one line, and its details carry the log as log_tail beside the operation_id and service. Reading the log does not retry the build. If the retained log is unavailable, the failure still names the service and cause. JSON retryable carries the build operation's verdict.

Retired inputs

A retired command or flag does no work: it exits 2 with one line naming its replacement. antioch run FILE points at antioch service exec -- python FILE, antioch project at the console, antioch project registry at antioch auth registry, antioch session use at --session ID, antioch service sync and watch at exec and shell, which sync on their own, and --background at a plain run, which already goes to Antioch-managed sessions. The older --no-follow still means --detach, and --path, --tag, --exclude-tag and --case still mean their plural flags.

Other retired inputs are ignored or read as their replacement with a coded deprecation notice. They do not restore old behavior. Remove them when updating a project:

CLI notices use stderr; with --json, each is a JSON object under notice with type, code, message, and location. Command stdout is unchanged. Python callers receive common.deprecations.AntiochDeprecationWarning, a visible FutureWarning with a structured notice attribute. Unknown inputs still fail validation. These notices do not bypass SDK or runtime version checks.

An older CLI is not refused for its age. If a route or response is incompatible, the error names the deployed SDK version and links to Upgrade the SDK.

Command help and scripts

Use antioch --help or a command's --help for the current option list. Most non-interactive commands support --json: data goes to stdout, diagnostics to stderr. Single repeatable mutations use changed: false for an already-complete action. Setup instead reports each plugin component and health check; a no-op setup still exits 0.

Set ANTIOCH_TRACE=1 to see where a command's time went: as it ends, it prints one line on stderr with its API and session-edge request counts and times, its source sync plan and apply, its command connect, and the total.

API errors use api_protocol_error, api_response_error, and api_response_unreadable as their structured categories. Scripts that matched the previous category names must use these names instead.

The full customer guide is in the Antioch docs.