Oko
Oko/Docs

Command reference

oko agent run

Runs one prompt through a coding harness behind the local Brama proxy with the routed overlay, printing its events as they arrive. ID is a harness id from the catalogue `oko agent harnesses` lists — the same id Transcript Lake and Tama use. The harnesses Brama can route are Claude Code (`claude`), Codex (`codex`), Kimi Code (`kimi`), Qwen Code (`qwen`), OpenCode (`opencode`), Goose (`goose`) and aider (`aider`); every other harness in the catalogue is refused with the sentence saying why. Claude Code and Codex stream JSON lines in their non-interactive modes, Kimi Code speaks the Agent Client Protocol, and the others print text, one event per line.

Invocation#

Command
oko agent run --harness ID PROMPT [--route-url URL] [--cwd DIR] [--json]

Inputs and options#

  • --harness names the harness and the prompt follows; --route-url overrides the router origin Stado resolves; --cwd the working directory; --json prints the events as JSON lines.
  • The catalogue's launch refusal is checked before router discovery and authentication, so unavailable Brama access cannot obscure an unsupported harness.
  • For source qualification, select installed harnesses with OKO_TEST_HARNESSES and run `cargo test --manifest-path rust/Cargo.toml --test agent-routing -- --ignored --nocapture` when execution is permitted. The journey requires real Brama access, verifies persisted receipt contents and an unsupported-route refusal, and prints its retained evidence directory. Each invocation records its command before launch, its PID after launch, and writes raw .stdout and .stderr files while the process runs. Its JSON report distinguishes starting, running, exited and spawn/wait failure; an interrupted running record is not a pass. Completed output alone does not prove live diagnostic delivery or native desktop behavior.

Output and state effect#

  • Starts an authenticated local proxy, launches the harness with the overlay environment the catalogue declares for it (its own documented variables pointed at the proxy, an isolated home under ~/.oko where the harness needs one, and a configuration file written there for Codex, Kimi Code and OpenCode), and prints what it says.
  • Nothing waits in silence: standard error carries `czekam: <harness>; gdzie: <directory>; rodzaj: proces` before the harness starts and `koniec czekania` or `blad czekania` when it ends, every line the harness writes on its own standard error as it arrives (prefixed `<harness>: `), and one `czekam: POST|GET <Brama address>; gdzie: Brama; rodzaj: siec` pair per request the proxy sends, whose `blad czekania` names the status Brama refused with or why it could not be reached. A run that stands still therefore shows which request or process it stands on and since when; standard output, and `--json`, carry only the harness's events.

Refusals and safe exits#

  • `oko agent takes run or harnesses; got <verb>` with the usage line, `oko agent run requires --harness <text>`, `unknown harness <name>; the harnesses are <every catalogue id>` and `oko agent run requires PROMPT` with the usage line, all before anything starts (exit 2); `agent launch blocked: <reason>` for a harness the catalogue declares unroutable, for example `agent launch blocked: Gemini CLI speaks the Gemini API, which the local Brama proxy does not relay (it relays chat completions, Anthropic Messages and OpenAI Responses).`; `agent launch blocked: the harness catalogue declares no non-interactive run for <harness>`; `agent launch blocked: Stado router URL must use HTTPS or loopback HTTP`; `agent launch blocked: failed to start authenticated Stado proxy: <detail>`; `agent launch blocked: the current directory cannot be read: <error>`; `agent launch blocked: <detail>` from the overlay; `Failed to launch <harness>: <error>`; a harness that exits non-zero is refused with its own complaint.

CLI reference#