forked from bots-garden/ori
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 1 | # Reference: the ori command |
| 2 | ||
| 3 | > Neutral, exhaustive description of the `ori` server binary and its flags. | |
| 4 | ||
| 5 | ## Synopsis | |
| 6 | ||
| 7 | ```bash | |
| 8 | ori [--addr ADDR] [--cwd DIR] [--agent-cmd COMMAND] | |
| 9 | ``` | |
| 10 | ||
| 11 | At startup, `ori` spawns the agent command, performs the ACP handshake (`initialize`, then `session/new`), then serves the web application and its WebSocket endpoint. If the agent cannot be started or the handshake fails, `ori` exits with a non-zero status and an error on stderr. | |
| 12 | ||
| 13 | ## Flags | |
| 14 | ||
| 15 | | Flag | Type | Default | Description | | |
| 16 | | --- | --- | --- | --- | | |
| 17 | | `--addr` | string | `:8888` | TCP address the HTTP server listens on. The empty host binds all interfaces. | | |
| 18 | | `--cwd` | string | current directory | Working directory handed to the agent session. Must exist and be a directory; resolved to an absolute path. | | |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 19 | | `--agent-cmd` | string | `npx -y @agentclientprotocol/claude-agent-acp` | Command spawning the ACP agent, split on whitespace (first field: executable; the rest: arguments). | |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 20 | |
| 21 | ## HTTP endpoints | |
| 22 | ||
| 23 | | Route | Description | | |
| 24 | | --- | --- | | |
| 25 | | `GET /healthz` | Returns `{"status":"ok"}` with status 200. | | |
| 26 | | `GET /ws` | WebSocket endpoint of the panel; see the [WebSocket protocol reference](websocket-protocol.md). | | |
| 27 | | `GET /*` | The embedded single-page application; unknown paths fall back to `index.html`. Returns 503 if the binary was built without a UI build. | | |
| 28 | ||
| 29 | ## Example | |
| 30 | ||
| 31 | ```bash | |
| 32 | ./bin/ori --addr :9000 --cwd /work/my-project --agent-cmd "bin/ori-mock-agent" | |
| 33 | ``` | |
| 34 | ||
| 35 | ## Errors | |
| 36 | ||
| 37 | | Error | Cause | | |
| 38 | | --- | --- | | |
| 39 | | `--agent-cmd must not be empty` | The flag was set to blanks. | | |
| 40 | | `--cwd: … no such file or directory` | The working directory does not exist. | | |
| 41 | | `--cwd: … is not a directory` | The path exists but is a plain file. | | |
| 42 | | `start agent "…": …` | The agent executable could not be started. | | |
| 43 | | `initialize: …` / `new session: …` | The ACP handshake with the agent failed. | | |
| 44 | ||
| 45 | ## Companion binary: ori-mock-agent | |
| 46 | ||
| 47 | ```bash | |
| 48 | ori-mock-agent [--delay DURATION] | |
| 49 | ``` | |
| 50 | ||
| 51 | | Flag | Type | Default | Description | | |
| 52 | | --- | --- | --- | --- | | |
| 53 | | `--delay` | duration | `300ms` | Pause between streamed updates. `0s` disables pacing. | | |
| 54 | ||
| 55 | `ori-mock-agent` speaks ACP on stdio and plays one deterministic scenario per prompt: a thought, a two-entry plan, a read tool call, one permission request, and — if granted — an edit tool call with a diff and a final message. |