Get started

First episode

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.

Source: docs/quickstart.md