RoboTrace
Sign in

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.

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

The current release (0.1.0a0) ships only the core client — the ros2 and lerobot adapters land in a follow-up minor.

2. Get an API key

RoboTrace is invite-only during the pilot. Once you're approved off the waitlist, the team mints a key for you in Admin → Clients → <your client> → API access. 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.

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",
)

Useful when the deployment hasn't wired Cloudflare R2 yet — see Object storage for what changes when it does.

5. See it in the portal

The episode lands in /admin/episodes immediately. Open it to see the reproducibility fields, artifact sizes, signed URLs (when R2 is configured), and the SDK-supplied metadata.

The client portal (/app/episodes) where you can see your own episodes without admin access ships in Phase 3 — for now your contact on the RoboTrace team can confirm runs landed correctly.

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.