forked from bots-garden/ori
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 1 | # How to run Ori in a Docker sandbox |
| 2 | ||
| 3 | This guide shows how to package Ori as a Docker Sandboxes template and run it with `sbx`, so the whole stack — Claude Code included — lives in an isolated sandbox you reach from your browser. It assumes Docker and the `sbx` CLI on the host. | |
| 4 | ||
| 5 | ## Steps | |
| 6 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 7 | 1. Get the template image — it is published on Docker Hub as `k33g/ori:0.0.2`. To (re)build and push it yourself, from the repository root: |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 8 | |
| 9 | ```bash | |
| 10 | ./template/build.sh | |
| 11 | ``` | |
| 12 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 13 | The script runs a multi-arch `docker buildx build --push`: the SPA and the Go binaries are built in intermediate stages, then layered with the `claude-agent-acp` adapter on top of the official `docker/sandbox-templates:claude-code` image. For a local-only image use `make template` instead. |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 14 | |
| 15 | 2. Create the sandbox from your project directory, with the template and the ori kit, in detached mode: | |
| 16 | ||
| 17 | ```bash | |
| 18 | sbx run -d claude ~/path/to/your/project \ | |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 19 | --template k33g/ori:0.0.2 \ |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 20 | --kit /path/to/ori/kits/ori |
| 21 | ``` | |
| 22 | ||
| 23 | `-d` (`--detached`) matters: sbx stops a sandbox 30 seconds after the last CLI session on it closes, and browser traffic on a published port is not a session. `sbx create` holds a session only while it runs, so a sandbox created with it goes `stopped` half a minute later. A detached sandbox is exempt from this auto-stop until you `sbx stop` or `sbx rm` it. The flag exists only on `sbx run`, and the mode is fixed at creation. | |
| 24 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 25 | To pin a host port, add `-p 5555:8888/tcp`. Keep the `/tcp` suffix: without a protocol sbx binds IPv4 only (`tcp4`), and a browser that resolves `localhost` to `::1` gets "site can't be reached" while the server is up. Avoid ports Chrome refuses outright, such as 6665–6669. |
| 26 | ||
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 27 | The kit's startup command launches the ori server on port 8888 at every container start; the claude agent kit injects the Anthropic credentials through the sandbox proxy, so nothing needs a login inside. |
| 28 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 29 | 3. Open the UI: the kit declares port 8888, so the command output prints the ephemeral address it published — `Published web: localhost:<port> -> 8888/tcp`. Browse there, or pin a fixed port with `-p 8888:8888/tcp` at creation (or later with `sbx ports <sandbox-name> --publish 8888:8888/tcp`). |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 30 | |
| 31 | ## Variants | |
| 32 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 33 | - The listen port is a kit argument (default 8888): add `--kit-arg ori.port=9000` to change it, and publish that port yourself with `-p 9000:9000` — the port the kit declares for auto-publishing is fixed at 8888. |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 34 | - If the image was never pushed to Docker Hub, hand it to the sandbox runtime's own image store first: `docker save k33g/ori -o /tmp/ori.tar && sbx template load /tmp/ori.tar`. |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 35 | - Standalone, without sbx: `docker run --rm -p 8888:8888/tcp k33g/ori` (provide `ANTHROPIC_API_KEY`, or use the demo agent below). |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 36 | - Credential-free demo: inside the sandbox, `pkill -x ori` then relaunch with `--agent-cmd ori-mock-agent`. |
| 37 | - The server log inside the sandbox is `/home/agent/.ori.log`. | |
| 38 | - A stopped sandbox restarts with `sbx run -d --name <sandbox-name>` (or `sbx attach`); the kit relaunches the server on every start. | |
| 39 | - If a sandbox stops on its own anyway, check the daemon log (`sbx daemon status` prints its path) for `auto-stop` lines: they mean the sandbox was not created detached. | |
| 40 | ||
| 41 | ## See also | |
| 42 | ||
| 43 | - Kit details and template contents: [`kits/ori/README.md`](../../../kits/ori/README.md) | |
| 44 | - Flags of the server the kit starts: [reference: the ori command](../reference/cli.md) |