Open Agent API

Command-line reference

oaa is the command line of Open Agent API. This page lists every command, grouped by what you want to do, with one line on what it does and one example. Run oaa (or oaa --help) for the same list in your language. From a source checkout write npm run oaa -- instead of oaa.

  • Language. Output follows the system locale; set OAA_LOCALE=zh or OAA_LOCALE=en to pin it.
  • Errors. A failed command prints error_code: message on stderr (plus a Next: line when the error catalog has advice) and exits with 1. Error codes are listed in protocol.md.
  • Where the gateway and the key come from. Commands that talk to a running gateway take --url URL and --token-file FILE; when they are omitted the environment variables OAA_GATEWAY_URL and OAA_TOKEN_FILE are used, and the address defaults to http://127.0.0.1:8787. connect, status, approvals, approve, deny and verify can also find them in a local data directory (--dir, default .oaa): the address comes from its config.json and the key is the owner admin key written by oaa init. Pass --token-file to use a different key.
  • Keys are never printed. Commands that create keys write them to a private file (mode 0600).

Contents

  1. Start and look after a local gateway
  2. Connect an agent you have installed
  3. Approvals from the terminal
  4. Webhooks
  5. Verify an agent yourself
  6. Keys and the calling identity
  7. Write and publish agents
  8. Call agents and read results
  9. Worker nodes
  10. MCP and integrations
  11. Share a gateway

Start and look after a local gateway

CommandWhat it doesExample
oaa quickstart [--dir .oaa] [--port 8787]Initializes the data directory, starts a gateway in the background, publishes the offline sample agent agent/sample, creates a caller key and makes the first call; safe to repeat.oaa quickstart --port 18787
oaa init [--dir .oaa]Creates the data directory with config.json and the admin key file admin.token; installed agent CLIs are recorded as disabled.oaa init --dir ./gateway-data
oaa serve [--config .oaa/config.json] [--dir DIR] [--detach] [--tool-config FILE]...Runs the gateway (in the background with --detach, which writes server.pid); --tool-config adds prepared MCP tool bindings to the local worker.oaa serve --detach
oaa stop [--config .oaa/config.json]Stops the gateway that oaa serve --detach started, after checking that /health reports that process.oaa stop
oaa status [--dir .oaa] [--url URL] [--token-file FILE] [--json]One read-only answer to "how is my gateway doing": address, version, process ID, uptime, data directory and database size, published agents and whether each can run now (with the reason when not), agents found on this machine but not connected, running, queued and awaiting-approval tasks, recent failed tasks with their error codes, the number of keys, and the security profile from the local configuration (with a warning line when the gateway looks reachable from outside while the profile is still local, the same check as the security_exposure field of oaa doctor). Exits with 1 when the gateway is not running.oaa status
oaa doctor [--config .oaa/config.json] [--write]Reports which agent CLIs and ACP agents are installed, what the configuration holds and the database size (with a warning above retention.warnDatabaseMb, default 1024 MB); nothing is executed. --write records newly found ACP agents as disabled adapters.oaa doctor --write
oaa prune [--older-than 30d] [--dry-run] [--vacuum] [--config .oaa/config.json]Deletes finished runs older than the given age (30d, 12h, 45m, 90s; default 30d) with their events, artifacts and unreferenced uploads; with the gateway stopped it also sweeps old session workspaces. --dry-run only counts. With a gateway running it goes through POST /v1/maintenance/prune (admin key); --vacuum needs the gateway stopped. Never touches queued, running, waiting or interrupted runs. See stability.md.oaa prune --older-than 30d --dry-run

status only reads. A key that may not read some part (for example the key list needs the admin key) still gets the rest, with a note naming the missing part. --json prints the same facts as JSON.

Connect an agent you have installed

CommandWhat it doesExample
oaa connect NAME [--dir .oaa]Detects codex, claude, agy or an ACP agent (preset or adapter name), enables it on the running gateway, publishes it as agent/NAME, makes sure the caller key can call it and prints a curl to try. It does not call the agent.oaa connect codex
oaa connect [--dir .oaa]With no target: lists the external agents found on this machine and every model preset, with the command to type next.oaa connect
oaa connect PRESET [--model M] [--key-env NAME | --key-file FILE] [--base-url URL] [--agent agent/assistant] [--name NAME] [--definition FILE.oaa] [--test] [--dir .oaa]Gives the built-in agent a model: probes a local service (loopback only), writes the provider into the configuration (key reference only; same entry skipped, different entry refused), restarts the gateway only if this data directory started it, publishes agent/assistant, checks the caller key and prints a curl. Never calls a model; --test sends one minimal request, only for loopback endpoints. Presets and keys: models.md.oaa connect deepseek --key-file ~/.config/deepseek.key
oaa models [--dir .oaa] [--check] [--json]Lists configured model providers: protocol, endpoint, whether the key reference resolves, whether the endpoint answers (loopback automatically, hosted only with --check, which requests the model list only) and which agents use each.oaa models --check
oaa publish-native --id ID --engine ENGINE [--models default] [--approvals ask|auto] --url URL --token-file FILEPublishes a built-in engine (codex, claude, antigravity, dsh) or an enabled adapter (adapter/NAME) as an agent. --approvals auto approves the agent's permission requests by policy instead of waiting for you.oaa publish-native --id agent/codex --engine codex --url http://127.0.0.1:8787 --token-file .oaa/admin.token
oaa expose ENGINE|definition.oaa [--models default] [--approvals ask|auto] [--id ID] [--dir DIR] [--detach] --url URL --token-file FILERuns an agent CLI on this machine as a worker node of a (possibly remote) gateway and publishes it there.oaa expose codex --detach --url https://gw.example.com --token-file admin.token

Approvals from the terminal

On a server without the console, a task that needs your decision waits as "awaiting approval". These commands use the same API as the console (GET /v1/runs, GET /v1/runs/{id}/actions, POST /v1/runs/{id}/actions/{action}).

CommandWhat it doesExample
oaa approvals [--watch] [--json] [--dir .oaa]Lists every pending approval: run ID, agent, action ID, when it expires and a one-line summary of the requested operation. With --watch it keeps polling (every 2 seconds) and prints each new pending item once; Ctrl+C ends it. With --json it prints JSON (one object per line when watching).oaa approvals --watch
oaa approve RESPONSE_ID [--action ACTION_ID] [--all] [--yes] [--dir .oaa]Approves the pending item(s) of a run.oaa approve resp_0123 --action approval_4567
oaa deny RESPONSE_ID [--action ACTION_ID] [--all] [--reason TEXT] [--dir .oaa]Denies them. The run then fails with permission_denied. --reason is stored with the approval record; it is not sent to the agent.oaa deny resp_0123 --reason "not on production"

Behavior:

  • The operation is printed first. Before anything is decided, approve and deny print what is being decided (kind, run and the full bounded detail of the request).
  • Several pending items. A run can hold more than one. Without --action or --all on such a run nothing is decided and the command fails with approval_ambiguous, listing the items. --action ID decides one item, --all decides every item of the run. A run with no pending item fails with approval_not_found.
  • Interactive or not. In a terminal, approve asks [y/N] after printing the operation (--yes skips the question; deny never asks; answering no decides nothing and fails with approval_declined). When stdin or stderr is not a terminal (pipes, scripts, cron) nothing is asked and the command decides at once; the result is the exit code (0 when every item was decided, 1 otherwise). --json prints the per-item results.
  • Calls to your own tools are not approvals. A run waiting for a tool result from the caller (client_tool) is neither listed nor decidable here; the caller returns the result (see harness.md).
  • Permissions are the API's. Deciding needs a key with the approve scope (the admin key has it) and access to the agent. A caller key made with oaa key create --approve can decide the runs it may see; a key without the scope is refused up front with a message that says how to fix it, and nothing is sent. A stale item (already decided or expired) is reported as failed for that item.

Webhooks

Run events (completed, failed, waiting for approval and so on) can be pushed to an HTTPS endpoint of yours, signed and retried; see webhooks.md. These commands need the owner admin key and find the gateway and the key like approvals does (--dir, --url, --token-file). All take --json.

CommandWhat it doesExample
oaa webhook add URL [--event EVENT]... [--agent AGENT]... [--include-output] [--out SECRET_FILE]Adds an endpoint. --event (repeatable) picks events from run.requires_action, run.completed, run.failed, run.cancelled, run.incomplete, run.interrupted (default: all); --agent limits it to agents; --include-output adds the final output (at most 32 KiB) to run events. Prints the signing secret once, or with --out writes it to a new file with mode 0600 and does not print it.oaa webhook add https://hooks.example.com/oaa --event run.completed --out webhook.secret
oaa webhook listLists endpoints with their events, agents, state (ok, failing, disabled), queued deliveries, consecutive failures and the latest delivery.oaa webhook list
oaa webhook remove IDDeletes an endpoint and its queued deliveries.oaa webhook remove wh_0123
oaa webhook test IDQueues a webhook.test event, waits up to 15 seconds for the first attempt and prints it; exits with 1 when it failed.oaa webhook test wh_0123
oaa webhook deliveries ID [--limit 20]Recent deliveries, newest first: event, status, HTTP status, duration, attempts and the last error.oaa webhook deliveries wh_0123

Enabling, disabling, changing filters, rotating the secret and redelivering go through the API (PATCH /v1/webhooks/{id}, POST /v1/webhooks/{id}/rotate-secret, POST /v1/webhooks/{id}/deliveries/{delivery}/redeliver).

Verify an agent yourself

CommandWhat it doesExample
oaa verify AGENT [--model default] [--scenarios LIST] [--out DIR] [--executable PATH] [--timeout-ms 300000] [--dir .oaa] [--json]Prints the plan: which scenarios, how many real agent calls, and what happens on your machine. Runs nothing.oaa verify codex
oaa verify AGENT ... --confirm-live-costRuns the scenarios and writes report.json and report.md to --out (default oaa-verify-AGENT-TIME in the current directory; it must not exist yet).oaa verify codex --confirm-live-cost

AGENT is what oaa connect takes (codex, claude, agy, an ACP preset or adapter name), or the published id agent/NAME. The program is found through the local configuration, then PATH; --executable overrides it for a built-in engine.

What it runs. An isolated gateway inside the command process (127.0.0.1, random port, data and the agent's working directories in a temporary directory that is deleted at the end). Your own gateway, data directory and keys are not read or changed. The scenarios (use --scenarios chat,approvals or S1,S6 to choose; default is all, and the free cleanup check always runs):

KeyIdAgent callsWhat it checks
chatS11OpenAI Chat Completions, non-streaming.
chat-streamS21The same with stream: true: how deltas arrive, the final frame.
responsesS32OpenAI Responses and previous_response_id continuation.
claude-messagesS42Claude Messages, plain and streaming.
geminiS51Gemini generateContent.
approvalsS62A task that needs approval: approved then continues; denied then fails with permission_denied.
cancelS71A background task is cancelled; its child processes must exit.
client-toolsS81The agent calls a tool the caller provides and continues with the result.
concurrencyS93Three tasks at once do not mix up answers.
errorsS110Wrong key, no access and malformed bodies on three wire formats.
cleanupS120No child process or key left behind.
usageS130Whether the earlier responses reported token usage (derived, no call).

Each scenario is judged pass, FAIL, unsupported (the engine does not offer the capability, as documented) or skipped. Nothing is retried, a failed scenario never stops the others, and every scenario has a hard timeout (--timeout-ms). Ctrl+C ends the run cleanly: the running task is cancelled, the agent processes are stopped, the remaining scenarios are marked skipped and a partial report is still written (exit code 130). Exit code: 0 when nothing failed, 1 when a scenario or the setup failed.

Real calls cost something. Every scenario sends real prompts to the agent, using the agent's own sign-in and quota, with your permissions on this machine; the approvals scenario has it create a file in the temporary directory. Without --confirm-live-cost nothing is started. Before the scenarios the agent is started once without a prompt (the ACP initialize handshake, or --version) to read its self-reported name and version; this calls no model.

The reports contain the gateway version, the agent's name and self-reported version, the operating system and architecture, Node.js version, each scenario's result, time and failure reason, and the differences from adapters.md. They are scrubbed before they are written: keys and tokens, your user name, host name, home and other local paths, e-mail and LAN addresses are removed. Read report.md once before posting it; the Agent verification report issue template asks for it.

The same scenarios back examples/live-agents-acceptance.ts (the script that produced the Antigravity evidence in evidence.md), which keeps its own command line.

Keys and the calling identity

CommandWhat it doesExample
oaa key create --name NAME [--agent AGENT]... [--approve] [--out FILE] --url URL --token-file ADMIN_TOKENCreates a caller key (scopes invoke, read, files; plus approve with --approve) for the given agents (default all) and writes it to a private file.oaa key create --name ci --agent agent/codex --approve --token-file .oaa/admin.token
oaa me --url URL --token-file FILE (alias whoami)Shows who the key is: owner, scopes, granted agents, quota and live usage.oaa me --token-file .oaa/keys/ci.key

Write and publish agents

CommandWhat it doesExample
oaa check definition.oaaChecks an .oaa source and prints diagnostics and workflow plans; exits with 1 when invalid.oaa check examples/research.oaa
oaa fmt definition.oaa [--out FILE]Prints the formatted source (or writes a new file); comments are not kept.oaa fmt a.oaa --out formatted.oaa
oaa decompile definition.json [--out FILE]Turns a definition JSON into .oaa source.oaa decompile agent.json --out agent.oaa
oaa build definition.oaa|definition.json [--skill DIR]... [--tool-binding FILE]... --out bundle.jsonBuilds a reviewable bundle file without contacting a gateway.oaa build a.oaa --skill ./skills/research --out bundle.json
oaa publish definition.oaa|definition.json [--skill DIR]... [--tool-binding FILE]... --url URL --token-file FILEBuilds and publishes in one step.oaa publish examples/research.oaa --token-file .oaa/admin.token
oaa publish-bundle BUNDLE.json --url URL --token-file FILEPublishes a bundle you reviewed, with nothing added.oaa publish-bundle bundle.json --token-file .oaa/admin.token

Call agents and read results

CommandWhat it doesExample
oaa agents [--offset 0] [--limit 20] [--revision REVISION]Pages through the catalog of published agents.oaa agents --limit 5
oaa agent AGENT [--section overview|routes|tools|skills] [--offset N] [--limit N] [--agent-version DIGEST]Shows one agent.oaa agent agent/codex --section routes
oaa agent AGENT [--agent-version DIGEST] --out NEW_FILEDownloads the agent's full public metadata (the file must not exist).oaa agent agent/codex --out codex.json
oaa catalog [--cursor CURSOR] [--limit 32] [--timeout-ms 20000]Long-polls the catalog change feed.oaa catalog --limit 10
oaa preview AGENT [--model auto] [--agent-version DIGEST] [--file-id ID]... [--previous-response-id ID]Shows how a call would be routed, without running it.oaa preview agent/codex
oaa invoke AGENT --input TASK [--model auto] [--agent-version DIGEST] [--file-id ID]... [--previous-response-id ID] [--idempotency-key KEY]Starts a background task and prints its run ID.oaa invoke agent/sample --input "hello"
oaa get RESPONSE_IDPrints the run's state.oaa get resp_0123
oaa wait RESPONSE_ID [--timeout-ms 20000]Waits for the run to change state (up to the timeout).oaa wait resp_0123
oaa output RESPONSE_ID [--cursor CURSOR] [--max-bytes 8000]Reads the run's output a page at a time.oaa output resp_0123
oaa artifacts RESPONSE_ID [--offset 0] [--limit 10]Lists the files the run produced.oaa artifacts resp_0123
oaa cancel RESPONSE_IDCancels a run.oaa cancel resp_0123
oaa resume RESPONSE_IDResumes an interrupted run.oaa resume resp_0123
oaa upload SELECTED_FILE [--allowed-node NODE]...Uploads one file you chose and prints its file ID.oaa upload report.pdf
oaa download FILE_ID --out NEW_FILEDownloads a file; an existing file is never overwritten.oaa download file_0123 --out result.txt

Worker nodes

CommandWhat it doesExample
oaa node join --config worker.json [--tool-config FILE]...Runs this machine as a worker node that connects to a gateway.oaa node join --config worker.json
oaa nodesLists node registrations.oaa nodes
oaa node drain|resume|revoke NODE_ID [--reason TEXT]Stops sending new work to a node, resumes it, or revokes it.oaa node drain laptop --reason maintenance
oaa node history NODE_ID [--cursor EVENT_ID] [--limit 50]Shows a node's audit history.oaa node history laptop

MCP and integrations

CommandWhat it doesExample
oaa mcp --url URL --token-file FILEServes the gateway to an MCP client over stdio.oaa mcp --token-file .oaa/admin.token
oaa mcp inspect --config worker.json --server NAME [--tool NAME] [--cursor CURSOR]Lists the tools of an MCP server configured on a worker.oaa mcp inspect --config worker.json --server files
oaa mcp prepare --config worker.json --server NAME --tool NAME --capability private/name --out NEW_DIRECTORY [--name N] [--version V] [--effect E] [--approval A] [--export-result] [--optional]Prepares a reviewable capability binding for one MCP tool.oaa mcp prepare --config worker.json --server files --tool read --capability private/read --out ./prepared
oaa integration --out FILE --token-file FILE [--url URL]Writes an MCP client configuration (mcpServers) that starts oaa mcp; nothing is installed.oaa integration --out mcp.json --token-file .oaa/admin.token

oaa mcp-relay is started by ACP agents from their session configuration; it is not for people.

Share a gateway

CommandWhat it doesExample
oaa tunnel [URL|none] [--public-url URL] [--detach] --url URL --token-file FILERegisters the public base URL of the gateway; without one it opens an HTTPS tunnel with cloudflared if installed. none clears the setting.oaa tunnel --public-url https://agents.example.com --token-file .oaa/admin.token
On this page