You need Git, uv, Python 3.11, Node.js 22.19 or newer with npm (install) and a model API key. ORA installs its Python dependencies from uv.lock and the agent core's Pi packages from ora-pi/package-lock.json; this example downloads no model or simulator assets and uses no GPU.
git clone -b preview/v0.1 https://github.com/fast-rua/ORA.git && cd ORA
uv sync --all-extras --locked
npm ci --prefix ora-pi --prefer-offline --no-audit --no-fund
uv run --locked ora doctor
The repository must be clean: launches bind the exact source commit. Keep local configuration in shell variables or an ignored .env file; ORA does not automatically source that file.
Model API
For the default OpenAI endpoint, set ORA_API_KEY or OPENAI_API_KEY in your shell. The default model is gpt-4.1-mini, which accepts image inputs and tool calls.
For another OpenAI-compatible API, set these non-secret values and supply its key as ORA_API_KEY:
export ORA_BASE_URL=https://your-model-server.example/v1
export ORA_MODEL=your-served-model-id
export ORA_PROVIDER=openai_compatible
A local HTTP server is accepted only on loopback. Remote endpoints require HTTPS. For a private certificate authority, set SSL_CERT_FILE to a trust bundle containing that CA. Do not disable certificate verification.
For Anthropic Messages, set ORA_API_KEY or ANTHROPIC_API_KEY, plus:
export ORA_PROVIDER=anthropic_messages
export ORA_BASE_URL=https://api.anthropic.com
export ORA_MODEL=your-available-model-id
To use a registered provider profile instead of these variables, name it. The profile brings its endpoint, model and key variable; the key comes from your shell or from ora providers key PROFILE (model APIs):
uv run --locked ora providers # the profiles and where each key comes from
uv run --locked ora run --env synthetic --provider-profile deepseek_flash_openai_low_16k_v1
Preflight then probes that provider before the episode, and the profile's own output limit applies.
ORA_REASONING_EFFORT optionally selects the provider's reasoning setting. A text-only endpoint can use ORA_SUPPORTS_IMAGES=0 for Synthetic; the robot benchmarks need the observation capabilities their selected surface declares. Keys are read from the environment and never stored in RunSpecs.
Run
uv run --locked ora run --env synthetic
The model reads a robot manual and moves a Synthetic end effector once. The normal resolver, preflight, resource lease, supervisor, evaluator and seal are used, on the Pi agent core. Running this command explicitly starts the bounded demonstration; it does not require a separate confirmation prompt.
The episode has a 120-second budget, at most six model calls, and at most 2,048 output tokens per call. Actual latency and input-token use depend on your provider and the tool calls it chooses. The command prints the episode directory and call count. It exits successfully only after a completed episode has been sealed.
Look under outputs/quickstart/runs/<run-id>/ for plan.json, result.json, seal.json, canonical events and archived provider evidence. official_success: null is expected: Synthetic tests infrastructure and has no benchmark success predicate.
uv run --locked ora-viewer --open-browser
The viewer discovers the saved run. To replay the episode in the terminal,
with the model's words and each tool call, run ./scripts/ora watch RUN_ID
with the printed run ID (terminal UI). Choose a robot environment after this example works.
To steer the agent yourself, uv run --locked ora interactive runs a longer
Synthetic episode in Pi's terminal UI (interactive sessions),
and uv run --locked ora play --env synthetic starts free play:
no task, your instructions one at a time. Both offer the provider profiles
from ora providers, or --provider env for the variables above.
Synthetic reserves 1 GiB of free workspace and 0.25 GiB of scratch by default; explicit host storage settings take precedence. No simulator disk reserve is required.
Troubleshooting
| Symptom | Check |
|---|---|
| Missing key / 401 | Export the key expected by the chosen provider. ora doctor reports presence only; it does not authenticate. |
| 429 or provider unavailable | Check the provider's capacity and billing. The run remains bounded; inspect its supervisor.log. |
| Source is dirty | Commit intentional source changes; keep credentials and generated files ignored. |
| Context overflow | Use a model with the declared window or reduce the task/context in a separate RunSpec. This quickstart declares 32,768 tokens. |
| Episode appears stalled | Inspect the printed run directory and ora status; ora stop <run-id> stops that exact run. |
| No GPU, EGL or simulator | None is needed here. For robot episodes, run ora doctor --env <environment> and follow that environment's installation page. |
Without a key, run the same CLI against a deterministic local HTTP model, as CI does; it spends no API credits:
uv run --locked python -m examples.quickstart_smoke --keep outputs/smoke
--keep DIR keeps the run in the workspace DIR and prints its run ID and the ./scripts/ora watch command that replays it; without --keep the run is removed afterwards (CI). Run it with uv run from the checkout: a Python without ORA's environment stops at once and says so. This is separate from acceptance against a real model API.