RoboTrace

Quickstart

The shortest path from pip install to a replayable episode in the RoboTrace portal. About 5 minutes, plus however long it takes your robot or sim to produce one run.

Want to see what an episode looks like first? When your /portal/episodes list is empty, the page ships with a clickable Sample run at the top - open it to explore the player, the reproducibility section, and the artifact panel before you pip install. The sample is read-only and the same row everyone with an account sees.

You'll need:

  • Python 3.10+ (CPython; PyPy isn't tested)
  • A RoboTrace API key - see step 2
  • An episode to log: a video file, sensor blob, or just metadata if you want to test the contract first

1. Install the SDK

pip install robotrace-dev

The current release ships the core client, the ros2 adapter, and OpenTelemetry trace correlation behind the [otel] extra. LeRobot, MuJoCo, Isaac Sim, and Gymnasium adapters land in 0.2.

Distribution name vs. import name. The PyPI distribution name is robotrace-dev (matches our robotrace.dev domain). The import name stays robotrace (no hyphen, no -dev suffix). Same pattern as pip install python-dateutil → import dateutil.

If you want to pin for reproducibility in CI or requirements.txt, use pip install robotrace-dev==0.1.0a6 (or whichever exact version you've validated against).

2. Get an API key

RoboTrace is invite-only during the pilot. Once you're approved off the waitlist, sign in to the portal and head to Portal → API keys to mint your first key. The full key is shown once at creation - we only store its SHA-256 hash, so if you lose it, we can't recover it; you mint a fresh one and revoke the old.

The key looks like rt_<id>_<secret> (for example rt_8a4f01c2b3_kPcD…). Treat it like any production secret: keep it in CI / .env, never in source control. Or skip the copy-paste and use robotrace login - it opens a browser, you click Authorize, and credentials land in ~/.robotrace/credentials automatically.

3. Configure the SDK

Two env vars wire the SDK to the right deployment:

export ROBOTRACE_API_KEY=rt_…
export ROBOTRACE_BASE_URL=https://app.robotrace.dev
# or http://localhost:3000 if you're running the stack locally

If you can't use env vars, pass them directly to rt.init(...):

import robotrace as rt
 
rt.init(
    api_key="rt_…",
    base_url="https://app.robotrace.dev",
)

4. Log your first episode

The one-shot path - log_episode(...) opens a run, uploads the artifacts you pass, and finalizes the run with the status you set:

import robotrace as rt
 
rt.log_episode(
    name="pick_and_place v3 morning warmup",
    source="real",                              # "real" | "sim" | "replay"
    robot="halcyon-bimanual-01",
 
    # Reproducibility - these are load-bearing. Future you re-rolling
    # this episode against a new policy depends on them.
    policy_version="pap-v3.2.1",
    env_version="halcyon-cell-rev4",
    git_sha="abc1234",
    seed=8124,
 
    # Local file paths. The SDK streams them straight to object
    # storage via signed PUT URLs - bytes never touch our origin.
    video="/tmp/run.mp4",
    sensors="/tmp/sensors.bin",
    actions="/tmp/actions.parquet",
 
    # Run details
    duration_s=47.2,
    fps=30,
    metadata={"task": "pick_and_place", "scene": "tabletop"},
)

The call returns when the episode row is finalized. Every reproducibility field shows up on the episode detail page - that's the contract that makes evals work later.

No files yet? Test the contract first

You can call log_episode(...) without any artifact paths to verify the metadata roundtrip end-to-end. The episode appears in the portal with bytes_total: 0 and a "no artifacts" placeholder on the detail page:

rt.log_episode(
    name="contract smoke",
    source="sim",
    policy_version="quickstart-v0",
)

5. See it in the portal

The episode lands in /portal/episodes immediately. Open it to see the reproducibility fields, artifact sizes, the inline frame-accurate video player, and the SDK-supplied metadata. From the row's 3-dot menu you can archive or delete the run later.

If the SDK printed a [robotrace] → line in your terminal, that URL goes straight to the new episode's detail page - Cmd-click in modern terminals.

What's next

  • log_episode reference - every argument, every default, the rules around the "sacred" signature.
  • start_episode for streaming control - when you want explicit lifecycle (context manager auto-finalize, per-artifact upload, custom failure handling).
  • Errors - the typed exception hierarchy and what to do with each type.
  • Ingest API - the HTTP endpoints under the SDK. Useful if your training stack isn't Python.