Antioch simulation SDK

antioch-sim is the typed Python SDK and command-line interface for running Isaac simulations on warm Antioch GPU machines. Write ordinary Python on your computer. The remote simulation image supplies Isaac, so no local simulator or GPU is required.

The public wheel contains the antioch API, the CLI, and the supported Isaac typing surfaces. It requires Python 3.12. The CLI and SDK run on Windows, macOS, and Linux.

Quick start

Install uv if it is not already available.

In an empty directory, create a Python 3.12 project and choose one engine:

uv init --bare --python ">=3.12,<3.13"
uv python pin 3.12
uv add --compile-bytecode "antioch-sim[isaac-sim]"

Activate the environment with source .venv/bin/activate on macOS or Linux, .venv\Scripts\Activate.ps1 in Windows PowerShell, or .venv\Scripts\activate.bat in Windows Command Prompt. Then run:

antioch auth login
antioch init
antioch run src/main.py

The login command prints a short code and a URL to open in a browser. The run command allocates or reuses a GPU machine, starts the generated Isaac Sim 6.0.1 example, relays its output, and prints a Mission Control link for its stream.

Use antioch-sim[isaac-lab] instead to create an Isaac Lab 3.0 Beta 2 project. Choose exactly one engine extra per project. In an existing Python project, skip uv init and uv python pin.

Install the SDK

The engine extra selects the image and examples that antioch init writes. The wheel already contains every supported typing surface. uv.lock pins the SDK and its third-party dependencies for repeatable installs. Isaac itself is not a Python dependency and is not installed on your computer.

antioch init creates local files only. It does not allocate a machine, register a remote project, or replace existing source. If a package manager does not save the extra in pyproject.toml, select the engine explicitly:

uv run antioch init --engine isaac-sim-6.0.1

Activate .venv if you want to omit uv run:

source .venv/bin/activate
antioch --help

On Windows, use the PowerShell or Command Prompt activation command from the quick start. Mission Control already includes the authenticated CLI and example projects, so its hosted environment does not need a local SDK installation.

Update a project

Refresh the SDK version in the lock file and reinstall the environment:

uv lock --upgrade-package antioch-sim
uv sync --compile-bytecode
uv run antioch --version

A generated project writes services.sim.image without a version tag:

services:
  sim:
    image: antioch-engine/isaac-sim-6.0.1

An image without a tag always runs the SDK release installed on your computer, so updating the package updates cloud runs with it. Only a project that pinned an explicit :<sdk-version> tag, or that builds from a Dockerfile, needs its image or FROM line updated by hand. Do not run antioch init again over an existing project.

Remove the SDK

uv remove antioch-sim

This removes the dependency from the Python project. It does not delete source, antioch.yaml, recorded scenarios, or remote assets. Run antioch auth logout before removal if you also want to remove the local login.

Complete commands in your shell

Antioch provides command completion for Bash, Zsh, and Fish. Add the line for your shell to its startup file:

# ~/.bashrc
eval "$(_ANTIOCH_COMPLETE=bash_source antioch)"
# ~/.zshrc
eval "$(_ANTIOCH_COMPLETE=zsh_source antioch)"
# ~/.config/fish/completions/antioch.fish
_ANTIOCH_COMPLETE=fish_source antioch | source

Completion resolves the one command being typed, so it stays as fast as the CLI itself.

Sign in

Sign in with antioch auth login. The CLI prints a short code and confirmation URL that you can open in any browser, so the flow also works over SSH. Signing in again replaces the active session. antioch auth whoami displays the active user and organization, while antioch auth switch selects another available organization. The CLI stores the login securely in .config/antioch under your home directory and shares it across projects. antioch auth logout removes the local login and machine access from this computer.

Your first script

antioch init creates local files only; it does not register a remote project, allocate a machine, or replace existing source. It creates a src-layout project with a visible example simulation, repeatable scenarios, and smoke and sweep suites. For Isaac Sim, generated src/main.py rains colored cubes onto a ground plane; for Isaac Lab it drives a cartpole. Both step physics and render for 30 seconds by default. Run the local file on a remote machine with:

antioch run src/main.py

The generated simulation keeps the Isaac viewport responsive long enough to watch the motion. Streaming is on by default; pass --no-stream for a headless run. antioch.boot() consumes that process-scoped declaration wherever it is called in the program. Before Isaac starts, the command prints a Mission Control link for each machine so you can watch its livestream. The target remains ordinary Python: it can use native Isaac APIs, parse arguments, and control when Isaac starts. Arguments after -- reach the script unchanged; stdout, stderr, and the exit code remain the process's own.

run starts one finite process on one machine; --machine pins which one. Ctrl-C signals that exact process gracefully first, and a second Ctrl-C force-kills only it. Native programs can tune render fidelity directly:

import antioch

antioch.boot(render_quality="quality", viewport=(1920, 1080))

render_quality picks a DLSS fidelity preset from "performance" through "ultra"; viewport sets the main non-streamed render target. Leave either unset to keep its default. Streaming stays a launch concern: it is on by default, while --no-stream opts out; the runtime chooses a safe initial encoder target, and the connected browser takes over dynamic sizing. Simulation code does not configure transport policy.

Antioch does not override Isaac or Kit logging by default, so output matches the selected engine's native behavior. Set a level only when you deliberately want to change that behavior:

antioch.boot(log_level="error")  # or "fatal" / "warning" / "verbose"

For decorated scenarios, antioch scenario run keeps its concise live board while antioch scenario run --verbose relays the informational process output.

Your first scenario

A scenario turns a script into a named, repeatable simulation: decorate a function with @antioch.scenario and Antioch can collect it, set its parameters, run it across many machines, and save its source hash, parameters, results, and telemetry. antioch scenario run collects every scenario under the manifest's explicit scenario_paths, or the sim build-context discovery scope when that field is omitted, and runs the selection on one project machine by default. Pass --machines N or repeat --machine to fan out explicitly:

When scenario_paths is omitted, the sim build context is scanned recursively. The default boundary skips hidden directories, virtualenvs (directories with pyvenv.cfg), node_modules, common cache/build directories, and paths matched by the context's .gitignore or .dockerignore. Use scenario_paths when a project needs a narrower or different source scope.

antioch scenario run                        # every scenario in the project
antioch scenario run --scenario falling_cube --set drop_height=4
antioch scenario run --scenario falling_cube --case resting
antioch scenario run --scenario falling_cube -t smoke
antioch scenario run --scenario falling_cube --scenario cartpole_balance
antioch scenario run -t physics --exclude-tag slow
antioch scenario run -t physics -t nightly      # repeat -t to require every tag
antioch scenario run --path src/physics     # discover somewhere other than the manifest
antioch suite run nightly        # named suite from antioch.yaml
antioch scenario run                        # livestream by default
antioch scenario run --no-stream            # headless run

The CLI prints the console URL to watch each machine on before it dispatches, because the window worth watching is the run itself. The stream server accepts a viewer after the engine starts streaming. Use --no-stream for a headless run.

A scenario receives its run as the first argument. Use that run to save results and artifacts, and to report the outcome. Annotating it is what makes the handle discoverable in an editor; the SDK supplies that one name when it reads your signature, so a module with from __future__ import annotations can leave ScenarioRun behind if TYPE_CHECKING: rather than importing it at runtime.

import antioch

logger = antioch.Logger("cube")


@antioch.scenario(tags=["physics"], sim=antioch.BootProfile(physics_dt=1 / 240), cases=[antioch.case({"drop_height": 0.0}, id="resting", tags=["edge"])])
def falling_cube(run: antioch.ScenarioRun, drop_height: float = 2.0) -> None:
    world = antioch.world()
    ...
    logger.scalar("height", z)  # -> entity path "cube/height"
    run.add_result("final_z", z)
    run.add_artifact(output / "trace.csv")
    run.check("came to rest", z < 0.4, detail=f"rested at {z:.3f} m")

sim= declares what the scenario needs to be correct — physics and render steps, render fidelity, Isaac log severity, the PhysX/Newton backend, and native Kit arguments. How you watch a run (streaming is default; --no-stream and --verbose stay on the CLI). --verbose changes whether process bytes are relayed live; it never changes which bytes Isaac emits.

For a supported frame from the active viewport, aim Kit's USD camera with set_camera_view(...), step the world, and call antioch.capture_viewport(). It returns an RGB-compatible array or None when no active viewport exists. The legacy isaacsim.sensors.camera.Camera also works, and Antioch does not restrict it. Newton is opt-in with antioch.BootProfile(physics_engine="newton") and is not available on Isaac Lab images.

Omit sim to use the default Kit profile. Pass sim=None when the scenario does not need a simulator at all; the runner still records its result and telemetry, but it does not boot Kit. Use --no-stream for these runs because there is no simulator viewport to stream.

A Logger is a channel prefix and nothing else, created once at module scope like logging.getLogger — it captures no run, so the same instance serves every run the process executes. Its text always reaches the terminal and additionally reaches the recording whenever a run is active, so a helper shared between a scenario and a standalone script logs correctly in both. Results belong to the run, not the logger. antioch.current_scenario_run() reaches the run from an imported helper that cannot take it as an argument.

run.check(criterion, passed, detail=...) is how a scenario says what its task was and whether it was done. Every check is recorded and measured — a failing one does not stop the body — and a run that fails any check finishes FAILED, so the outcome is the task's outcome rather than a proxy for whether the process survived. Reach for assert or run.fail only where the run genuinely cannot continue.

The ScenarioRun handed to a decorated scenario is the whole authoring surface: it saves what that scenario produced and cannot start, stop, or finalize unrelated processes. Raw antioch run, direct exec, and notebook processes do not save structured results; author a scenario when results must be retained and reviewed.

Durable outputs for long runs

Plain antioch run output and files under /workspace/output are machine-local scratch. They are not a durable process record and disappear when the machine is released. For training or dataset generation, make the work a scenario and register each checkpoint with the existing scenario artifact seam:

from pathlib import Path

import antioch


@antioch.scenario(tags=["training"])
def train(run: antioch.ScenarioRun, steps: int = 10_000) -> None:
    """Train a model and retain checkpoints as scenario artifacts."""

    output = Path("/workspace/output/checkpoints")
    output.mkdir(parents=True, exist_ok=True)
    for step in range(steps):
        # Run one training step and write a complete checkpoint atomically.
        if step % 100 == 0:
            checkpoint = output / f"step-{step:06d}.ckpt"
            checkpoint.write_bytes(b"checkpoint bytes")
            run.add_artifact(checkpoint, name=f"checkpoints/{checkpoint.name}")

Run and retrieve it with antioch scenario run --scenario train, then antioch scenario download SCENARIO_RUN_ID. Each successful run.add_artifact(...) upload is retained in the scenario run even if the machine is later killed or reaped. A direct antioch services cp sim:/workspace/output/FILE ./FILE is an immediate copy for a plain run; it does not replace scenario artifact registration.

Scalars you log land in the scenario run's Rerun recording. Managed scenarios and native ScenarioSession runs also sample Kit's existing active viewport every 0.5 seconds of simulation time, logging JPEG frames to /antioch/viewport at up to 640 pixels wide and capped at 600 frames. An authored camera can keep using /viewport; the platform read-back has its own path so the two writers never interleave. Capture does not create or frame a camera; set the active viewport camera in simulation code when composition matters. A run that never steps a simulator simply has no platform viewport entity. Use @antioch.scenario(capture=False) or ScenarioSession(..., capture=False) to opt out; batch suites can disable the default globally with ANTIOCH_TELEMETRY_CAPTURE=0.

The recording is finalized with an automatic Rerun blueprint: /antioch/viewport is shown in a spatial view, each logged scalar gets a time-series view, and three-dimensional entities get a spatial view. To choose the layout yourself, call the one canonical setter while the run is active; it suppresses the automatic layout and is stored in the downloaded RRD as well as the live viewer:

import rerun.blueprint as rrb


@antioch.scenario()
def falling_cube(run: antioch.ScenarioRun) -> None:
    run.set_blueprint(rrb.Blueprint(rrb.TimeSeriesView(origin="/cube/height")))
    ...

To inspect the installed 0.36.0 reader's blueprint store in a downloaded RRD, use rerun.experimental.RrdReader("run.rrd").blueprints(); the same reader's stream(store=...) exposes the logged entities and their time columns.

The webapp renders that recording on the scenario-run detail page, where results, telemetry, logs, and artifacts remain grouped under the authored run.

Every reusable parameter variation is an addressable case, and antioch.case(...) is its only spelling. One declaration can be a singleton, a Cartesian grid, or correlated combinations; all three expand locally into the same flat case catalog:

@antioch.scenario(
    cases=[
        antioch.case(id="default", tags=["smoke"]),
        antioch.case({"drop_height": 0.0}, id="resting", tags=["edge"]),
        antioch.case({"capture_batches": 100}, grid={"seed": range(50), "friction": [0.3, 0.8]}, id="seed-{seed}-mu-{friction}", tags=["production"]),
        antioch.case(combinations=[{"mass": 1.0, "speed": 2.0}, {"mass": 4.0, "speed": 0.5}], id="mass-{mass}-speed-{speed}"),
    ],
)
def falling_cube(...): ...

The positional mapping holds one case's values, or values shared beneath a grid/combinations expansion. Grid axes follow scenario-signature order and authored value order. An omitted id derives from the explicit values; an id on any case is a format template over resolved parameters, and one without braces is unchanged. A scenario with no cases= contributes one implicit default run. Once it declares cases, it runs exactly those cases—add antioch.case(id="default") when defaults should remain in the catalog. Select one or more with repeated --case, a family with -t edge, and see the expansion with antioch scenario collect --json.

Suites are immutable unions of exact selector clauses. Clauses are ORed; fields inside one clause are ANDed; values in paths, scenarios, and cases are exact alternatives. Required and excluded tags read the union of scenario and case tags:

suites:
  acceptance:
    description: "Warehouse acceptance"
    select:
      - paths: ["scenarios/safety"]
        tags: ["smoke"]
        exclude_tags: ["slow"]
      - scenarios: ["falling_cube"]
        cases: ["resting", "extreme"]

Overlapping clauses produce one scenario run at the first matching position, and each clause must match at least one case so a typo cannot silently shrink a suite.

antioch scenario collect inspects authored definitions entirely locally, and antioch suite collect expands every declared suite to the exact scenario files and cases it would run. scenario list, show, logs, delete, and suggest use the scenario surface; suite run, list, summary, show, and cancel use the distinct suite surface. If a deployment includes runs from an earlier Antioch version, the same commands include those runs and identify them as legacy. Use Settings in the webapp to show or hide legacy data for the account. Each run shows only the actions that it supports, such as deletion, rerun, or output retrieval. Scenario decorators can override catalog names and descriptions, carry a Rerun blueprint, opt out of default viewport capture with capture=False, and declare validated case catalogs. Prefer run.set_blueprint(...) when a layout depends on what the scenario actually logged. Scalar parameters support descriptions and inclusive numeric bounds through antioch.param; Literal[...] annotations become closed CLI choices. A plain scenario selection expands every declared case. --case selects one or more declared cases by id; repeat the option to select several. --set with an exact scenario creates one ad-hoc run from its defaults. The two modes cannot be combined. Named suites remain immutable.

The history commands keep the webapp's full operational query surface while adding script-oriented filters. Both scenario and suite histories filter by project, member, phase, outcome, time, and interactive or queued dispatch; scenario history additionally filters exact scenario and invocation ids, suite membership, tags, params, and results. Repeat --phase or --outcome on scenario list to select a union of display states. Every list cursor pins that exact query, so continuation commands pass only --cursor and --limit.

antioch scenario show SCENARIO_RUN_ID prints results and every named output. Retrieve one output or the complete set directly from object storage with:

antioch scenario download SCENARIO_RUN_ID --artifact telemetry
antioch scenario download SCENARIO_RUN_ID --artifact metrics/probe.csv -o output/
antioch scenario download SCENARIO_RUN_ID -o output/  # every artifact

Legacy outputs use the same command even when the older stack recorded no size or digest. A legacy suite invocation id is only unique inside its suite, so open it with antioch suite show SUITE_RUN_ID --suite NAME.

Queued runs

--queue builds or resolves the selected Docker-backed services on the submitter's assigned machine, adds the current project files to the simulation image, and saves the exact service images in your organization's private registry. antioch suite run NAME --queue stores one suite run plus all of its scenario children, while antioch scenario run --queue stores standalone scenario runs. Queued fan-out draws on the same per-user machine quota as interactive work, and Antioch distributes children fairly across eligible warm machines:

antioch suite run nightly --queue
antioch suite show SUITE_RUN_ID --follow
antioch suite cancel SUITE_RUN_ID
antioch suite rerun SUITE_RUN_ID
antioch scenario run --tag smoke --queue
antioch scenario cancel SCENARIO_RUN_ID
antioch scenario rerun SCENARIO_RUN_ID

Queued runs save their exact service images, project files, and inputs before Antioch distributes them. For a single-machine interactive run, Antioch captures the files in the running sim container and then attempts to save the exact images and files the run used. When that capture and publish succeeds, scenario rerun and suite rerun create fresh queued runs with the same images, files, parameters, and cases. They do not change the original run. The scenario rerun always creates one fresh run. Its --json output from antioch scenario rerun SCENARIO_RUN_ID --json is one JSON object, matching the single-run read and suite rerun surfaces. Multi-machine interactive runs are not currently rerunnable. Repeat the original command or use --queue when the result must be rerunnable. Antioch explains when an older run or a failed source capture or publish leaves the environment unavailable.

--follow reports the state it finds on connect and then every change, so a suite waiting on capacity says so instead of going quiet. There is no estimated finish time, because the fleet cannot honestly predict one. A followed suite is a stream rather than a document, so --follow --json emits line-delimited frames: one state frame per observed state and a final completed frame carrying the suite-run view. Without --follow, --json remains the single indented document it has always been.

Every finite history command supports --json. Every paged response — each list and suite summary — uses the same {"items": [...], "next_cursor": "..."} shape; pass next_cursor back with --cursor and do not repeat filters, because the opaque token carries the original query. Every *_at field in JSON is a Unix timestamp in microseconds; humanized clock labels stay in human tables. Repeatable filters are unions, while repeating a scalar option is a usage error. JSON failures are written to stderr as one error object with a stable type, exit code, HTTP status when the server answered, and retryable. Interactive terminals keep raw stdout/stderr or print destination paths, and their help names that exception. Finite file transfers accept --json and return a manifest with the destination, byte count, checksum, and replacement fact. Scenario and suite history commands return documented, stable JSON fields. The JSON includes run identity, suite and project links, how the run started, authored inputs, lifecycle state, outcomes, timings, results, logs, artifacts, and capability flags. It omits internal tenant, queue, machine-assignment, process, retry, and version-tracking fields. See the Antioch agent plugin CLI reference for the shared contract; use each command's --help for its current flags and payload.

Versioned assets

Assets are immutable named file revisions shared across the active organization. antioch assets push, list, show, pull, and repair expose the asset library in the CLI. Authenticated Python tools can use the same signed direct-storage path:

from antioch import load_asset, save_asset

asset = save_asset("robots/commissioning-arm", version="v1", source="robot.usda", description="Validated commissioning geometry")
prim = load_asset(asset.name, prim_path="/World/CommissioningArm", version="v1")

Saves always land in the current organization's store. Loads resolve against one asset library — organization assets, Antioch's shared assets, and the legacy stack, with a current asset shadowing a legacy one of the same name. Antioch transfers asset bytes directly to object storage, and the client verifies the stored size and SHA-256 before publishing the local destination atomically. A legacy revision has neither, because the legacy stack recorded neither, so its bytes are checked against the provider's declared length alone.

Choosing an engine

A project selects its engine with the services.sim.image value: antioch-engine/<engine>. For example, antioch-engine/isaac-sim-6.0.1 runs Isaac Sim 6.0.1 with the SDK release installed on your computer — local and cloud always run the same code. Add a :<sdk-version> tag only to hold the cloud on one exact release. antioch init detects the locally installed engine option and writes the image to antioch.yaml. Add a Dockerfile only for custom dependencies, and start it from the same image with an explicit tag. Antioch saves the exact resulting image for queued runs and reruns.

The public antioch-sim wheel includes the supported engine typing surfaces. The declared extra selects the initial scaffold and is locked in uv.lock:

dependencies = ["antioch-sim[isaac-lab]"]

Antioch's own building blocks state which engines they support, because the engines genuinely differ: some are Isaac Lab APIs with no Isaac Sim equivalent, and some need a minimum release. Using one outside its support says so directly rather than failing somewhere deep inside Isaac:

wrap_task_env requires Isaac Lab 3.0+ but this image runs Isaac Sim 6.0.1
('isaac-sim-6.0.1')

Support only widens: a component that works on an engine keeps working on later releases of it, and new engines are added without changing your code.

Base image inventory

The published engine image is the base for a project Dockerfile. The isaac-sim-6.0.1 core starts from Ubuntu 24.04 and includes the Isaac Sim 6.0.1 runtime, Python 3 with pip, venv, and development headers, uv, git, and git-lfs. It also includes the runtime graphics and audio libraries that Kit needs: Vulkan and vulkan-tools, GL/EGL/GLES/GLVND, X11, and audio support. The Isaac Sim layer carries the in-process ROS 2 Jazzy Python stack. The isaac-lab-3.0 layer adds Isaac Lab 3.0.0b2.post1 and its pinned framework extras.

This is a runtime inventory, not a promise of a general build workstation. The base does not include gcc/g++ or build-essential, the FFmpeg command line tool, graphics development headers, the full ROS 2 command-line and message-build toolchain, or project-specific system packages. Install those in the project Dockerfile when the project needs them. Verify an image that you changed with antioch services exec sim command -v TOOL before dispatch.

The FROM antioch-engine/<engine>:<sdk-version> line creates the first Docker image layer. Changing it rebuilds the engine and every project layer. A changed apt-get or uv instruction rebuilds that instruction and the layers after it; a changed source COPY rebuilds only the later project layers. Keep slow, stable system dependencies before source copies. Watch sync updates source without rebuilding, while a queued or saved run freezes the final image by digest.

Configure project services

antioch.yaml owns the complete project stack: one required services.sim entry and supporting services in that same mapping; a top-level sim is not valid. schema_version is optional and defaults to the latest schema, and streaming is a runtime choice rather than a manifest stream key. The services.sim.image value selects the engine; without a tag it runs the installed SDK release. Add build only when a Dockerfile is needed for custom dependencies, and use the same image with an explicit :<sdk-version> tag in its FROM line. Declare dependencies, environment, health checks, watch rules, and authenticated ports on those service blocks. Docker runs underneath Antioch through the Engine API. The CLI supplies GPU access, init, restart policy no, and the output bind; host networking and IPC default to host mode, with explicit supported network_mode and ipc values available as opt-outs. See the Compose file reference for the kept field vocabulary.

Start a foreground development session with antioch services up --watch. It builds, health-gates, watches, and keeps declared ports reachable at localhost while the stack is up. Ctrl-C ends the watch session but leaves containers and declared ports running; use antioch services down to stop everything. A bare antioch services up builds, health-gates the stack, opens its declared ports, then returns. Before a script, scenario, or suite starts, Antioch syncs the latest project files once. A running watcher keeps the project services current for ordinary run, scenario, and suite dispatch; all share one stack even when that watcher is live. Whenever Antioch recreates a container, it reapplies the declared sync rules, so services up, services restart, an image change, and run --restart never leave /workspace/project empty while waiting for a watch session. services ps, services logs, and services down resolve the existing project and never allocate a machine. Development watch rules and port connections are not included when a scenario or suite enters the queue. The queued run instead uses its saved service images, project files, and inputs.

Private image: services use the local Docker config for an interactive pull. For queued work, the submitter pulls with that credential, saves the exact image in your organization's private registry, and records it with the run. Workers and reruns need no third-party registry login. The saved sim image also includes the submitted project files at /workspace/project, because queued children run with no watch session to publish source.

Local runs, Jupyter, and machines

antioch run FILE is the local-first Python workflow. It prepares the healthy sim service when needed and starts one remote process with faithful output and exit status. antioch run executes your file inside the running sim container, next to whatever command: the service declares. A decorated scenario or suite saves results, telemetry, and artifacts. Use antioch services exec sim python for a raw diagnostic, antioch services ssh for a human shell, and antioch services cp sim:/workspace/output/result.png ./result.png for an explicit container transfer; all three resolve an existing assignment rather than allocating one. antioch services exec SERVICE CMD relays piped stdin to the selected service; use antioch services ssh for an interactive shell. Use antioch machine ssh for the VM shell. Docker runs underneath, so antioch machine ssh followed by raw docker ps, docker logs, or docker exec is supported for host-level diagnosis. The shell has no process identity, so work started there is not tracked or timed.

services cp follows Docker cp destination rules. A destination ending in / is a directory, and the source basename is placed under it; for example, antioch services cp ./payload sim:/workspace/output/ writes /workspace/output/payload/.... Without a trailing slash, the destination path receives the source contents, so ./payload copied to sim:/workspace/output/payload writes directly under that path. The service directory named by a trailing-slash destination must already exist.

antioch machine status prints the direct machine URL and, when available, the stream address. It also names Mission Control workspace when a workspace is holding the assignment. antioch machine list shows the same holder in its HOLDER column. This is an assignment hold, not a running-process count: the hosted Lab's cell-aware idle policy is deliberate, and its machine stays held until the workspace assignment is released. For captured stack output, use a focused service view such as:

antioch scenario show SCENARIO_RUN_ID --logs --service sim

antioch jupyter is the interactive surface, for people and for agents alike. One kernel-only Jupyter server runs in the project's sim container and every subcommand reaches it through one SSH forward, so a notebook and a coding agent drive the same warm Isaac. jupyter lab runs JupyterLab locally in gateway mode — notebooks, the editor, and Lab's terminal stay on your laptop while kernels and kernelspecs come from the machine. jupyter cell [CODE] runs one cell and exits, with --json for a structured result and a non-zero status when the cell fails. jupyter start, jupyter kernels, jupyter show, jupyter stop, jupyter stream, and jupyter unstream open a kernel and print its identity, list the machine's kernels, inspect one, end one, declare the one-per-machine livestream, and release that livestream. Declare a livestream before calling antioch.boot(); stopping that exact kernel releases its livestream. Repeating the same stream claim is idempotent. Sharing is explicit both ways: a command that finds several kernels refuses to guess, so a session that wants its own opens it with start and passes --kernel from then on.

Kernels outlive the command that made them, so the next cell lands on an Isaac that is already booted; an unattended idle kernel is culled and the machine then idles out normally. Restart replaces only that kernel and preserves the local notebook.

The machine lifecycle surface is list, status, checkout, release, and ssh. Container connections are under antioch services: services ssh opens /workspace/project in sim by default and services cp is the explicit transfer path. Use the machine lifecycle commands to choose or return assignments; they do not replace the service stack.

A project may hold several machines at once, and antioch machine checkout MACHINE says which of them single-machine commands use — the same idea as a checked-out git branch, and machine list marks it with *. Commands resolve an explicit --machine first, then the checked-out machine, then the project's sole assignment; holding several with none checked out is the one case they refuse to guess at. antioch machine checkout --none clears the choice, and releasing a machine clears it too.

Your local files remain the copy you edit throughout the watch session. Write temporary checkpoints, frames, and debug files to $ANTIOCH_OUTPUT_DIR (/workspace/output), which is outside the synced project files and disappears when the ephemeral VM is recycled. Retrieve a plain-run file before release with antioch services cp sim:/workspace/output/FILE ./FILE; that copy is not a durable record. Use the scenario artifact path above when output must survive machine loss. See antioch --help for the public command contract and the generated project for small authoring examples.

Troubleshooting

• antioch is not found: use uv run antioch from the project, or activate .venv with the activation command for your operating system from the quick start.
• Authentication is required or expired: run uv run antioch auth login again. Use uv run antioch auth whoami to check the active user and organization.
• The project cannot select an engine: declare exactly one supported extra in pyproject.toml, then run uv sync. For a new project, you can also pass antioch init --engine isaac-sim-6.0.1 explicitly.
• The remote image version does not match the SDK: remove the explicit :<sdk-version> tag from services.sim.image so cloud runs follow the installed SDK, or update the pinned tag and any matching Dockerfile FROM line to the version in the project lock.
• A stream is not ready immediately: wait for the engine to start streaming. Use --no-stream for a headless run.

The CLI prints value-specific errors and recovery commands. Use uv run antioch scenario run --help for one example of the current command options.