Get started

Model APIs

ORA's agent core, Pi, calls a model directly through OpenAI-compatible Chat Completions or Anthropic Messages. There is no managed coding-agent session between ORA and the endpoint.

First episode

The quickstart API section contains the complete setup for OpenAI, self-hosted compatible endpoints, and Anthropic.

Variable Purpose
ORA_API_KEY Credential; falls back to the protocol's usual API-key variable
ORA_PROVIDER openai_compatible or anthropic_messages
ORA_BASE_URL Endpoint URL
ORA_MODEL Model identifier served by that endpoint
ORA_REASONING_EFFORT Optional reasoning setting supported by the endpoint
ORA_SUPPORTS_IMAGES Set to 0 for a text-only Synthetic endpoint

Credentials do not belong in RunSpecs or Git.

Keys, configured once in the terminal

A provider profile names the variable that holds its key (DEEPSEEK_LOW_API_KEY for the shared default). Enter it once; ORA keeps it for you and tests it with the same probe every launch runs:

./scripts/ora providers key DEEPSEEK_LOW_API_KEY      # asked without echo, then tested
./scripts/ora providers                               # every profile and where its key comes from
./scripts/ora providers test deepseek_flash_openai_low_16k_v1

ora interactive and ora play ask the same way: a profile marked needs VARIABLE in the provider list asks for its key when you choose it, stores it and shows the probe's result before the run starts. Pi's /login and /logout, available in every run's terminal, use the same store.

The store is pi-auth.json in the ORA config directory ($ORA_CONFIG_HOME, else $XDG_CONFIG_HOME/ora, else ~/.config/ora), mode 0600, outside the repository and every run. An environment variable still comes first, so CI and scripts keep exporting keys (export DEEPSEEK_LOW_API_KEY=sk-...), and ora run lets the checkout's .env win over a stored key too. A plan and its evidence record the profile id and endpoint, never a key. Sealing refuses a run that holds a file named like a credential (credential, api-key, auth.json), except in a code-mode run's sandboxed workspace, whose file names the model chooses; it does not scan file contents, so keep keys out of anything the agent writes. ./scripts/ora providers key VARIABLE --remove deletes a stored key (as /logout does).

Robot episodes

Robot recipes select a provider profile when composing a RunSpec. Inspect registered profiles without contacting a service:

uv run --locked ora providers

The shared default is deepseek_flash_openai_low_16k_v1; the standalone Synthetic quickstart has its own explicit default. A robot endpoint needs the image, tool-call, and continuation capabilities declared by its surface. Registration and doctor discovery do not establish those capabilities; live preflight checks them.

ora run takes --provider-profile ID to run a task with another registered profile; it checks that profile's key and endpoint instead of DeepSeek's. On Synthetic, ora run --env synthetic --provider-profile ID uses the profile instead of the ORA_* variables. Two open-weight models released on 2026-10-15 are registered through OpenRouter (set OPENROUTER_API_KEY):

Profile Model Settings (from the model card)
muse_spark_open_openrouter_high_16k_v1 Meta Muse Spark Open reasoning effort high; temperature 1.0, top_p 1.0
nemotron_35_super_vl_openrouter_thinking_16k_v1 NVIDIA Nemotron 3.5 Super VL thinking on; temperature 0.6, top_p 0.95; routed to Together, whose endpoint accepts a forced tool choice
export OPENROUTER_API_KEY=sk-or-...
./scripts/ora run --env libero --task libero_goal/0 \
    --provider-profile muse_spark_open_openrouter_high_16k_v1 --confirm-launch

Measured on the robot-episode sweep

ORA's open-model sweep runs 130 robot episodes per model with the default policy composition and budgets, one attempt per episode: 80 LIBERO-Pro episodes (the four suites, original and object-swapped variants, tasks 0-9, initial state 1) and 50 RoboTwin tasks (one seed each, demo_randomized). Measured on ORA commit bf2d107d (2026-10-22), both models self-hosted with the settings of their model cards:

Model Settings Success LIBERO-Pro /80 RoboTwin /50 Reasoning tokens / episode Model-call latency p50 Self-declared give-ups
Qwen3.8-Flash-Next thinking on; temperature 1.0, top_p 0.95, top_k 20 108 (83%) 70 38 121k 23 s 20
DeepSeek-V4.1-Flash-1017 reasoning effort low 97 (75%) 65 32 79k 11 s 32

Flash-Next succeeds on 16 episodes where DeepSeek fails and DeepSeek on 5 where Flash-Next fails (exact McNemar p = 0.027). Each task has a single attempt and seed, so per-task differences are within run-to-run noise; read the comparison in aggregate only. Latency depends on the serving stack.

A profile may carry request_options, a closed set of request fields added to every call: temperature, top_p, top_k, chat_template_kwargs (vLLM and SGLang chat-template switches such as enable_thinking or reasoning_effort), OpenRouter's reasoning and provider objects, and vLLM's return_token_ids (true only: every stream then carries the prompt and sampled token ids, which ora export-sft --view wire exports). The agent core sends them (the Pi core's TypeScript provider), and so does free play (ora play) on every request to the profile's model, including after /model switches back to it; a model of another provider gets none. To serve a model yourself, add it with ora providers add and its --request-options (self-hosted endpoints), or copy a profile into your own catalog, point it at your endpoint and pass --provider-catalog to the spec builders.

Read configuration and host setup before a robot launch.

Self-hosted endpoints

Add your own OpenAI-compatible or Anthropic endpoint as a profile of yours (kept in providers.yaml beside the key store, never in Git), from the provider list's + add an endpoint or the command line:

./scripts/ora providers add cluster-deepseek --protocol openai_compatible \
    --endpoint http://127.0.0.1:30000/v1 --model deepseek-v4 --images
./scripts/ora interactive --provider cluster-deepseek
./scripts/ora providers remove cluster-deepseek

It asks for the key (stored as ORA_<ID>_API_KEY, or --key-env NAME) and runs the probe. Use the model ID exposed by the service. Plain HTTP is allowed only on loopback; remote services need HTTPS, so reach a cluster server through a local port forward (ssh -L 30000:node:30000 ...). Set SSL_CERT_FILE to the trust bundle for a private certificate authority.

Give the profile what the model card asks for. --context-window N is the context window the server serves, in tokens (vLLM's --max-model-len, at most the model's own); without it the profile records 131072, which cuts a 262k model short. --max-output N is the output budget (8192 by default). A thinking model usually needs its sampling and chat-template switch on every request: pass them as --request-options JSON (OpenAI-compatible endpoints only), with the same closed fields and checks as a catalog profile's request_options above. A slow self-hosted model that takes long to its first token needs a longer --recovery-window SECONDS (30..1800; 180 by default): how long each attempt may wait for its first token before it is retried, and how long failures before any content are retried before the call ends. A reply that keeps streaming has no total limit (provider recovery):

# NVIDIA Nemotron 3.5 Super VL on vLLM: thinking on, the card's sampling
./scripts/ora providers add nemotron-local --protocol openai_compatible \
    --endpoint http://127.0.0.1:30000/v1 --model nemotron-3.5-super-vl --images \
    --context-window 262144 --max-output 16384 --recovery-window 900 \
    --request-options '{"temperature":0.6,"top_p":0.95,"chat_template_kwargs":{"enable_thinking":true}}'

# Meta Muse Spark Open: reasoning effort through the chat template, served with a 262k window
./scripts/ora providers add muse-local --protocol openai_compatible \
    --endpoint http://127.0.0.1:30001/v1 --model muse-spark-open --images \
    --context-window 262144 --max-output 16384 \
    --request-options '{"temperature":1.0,"top_p":1.0,"chat_template_kwargs":{"reasoning_effort":"high"}}'

add prints the context window, output budget, request options and recovery window it recorded, and ./scripts/ora providers lists the context window and any request options and recovery window of every profile (--json shows the whole profile). A refused value (invalid JSON, a field outside the closed set, a temperature outside 0..2, a window outside 30..1800 s) stores nothing. Every plan built from the profile carries them: ora run --provider-profile ID, ora interactive --provider ID and ora play --provider ID (free play's provider does not send request options yet; see above). To change a value, add the profile again under the same id.

See troubleshooting for 401, 429, TLS, and capability failures.

Source: docs/getting-started/model-apis.md