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 | ||
| 7 | 1. Get the template image — it is published on Docker Hub as `k33g/ori:0.0.0`. To (re)build and push it yourself, from the repository root: | |
| 8 | ||
| 9 | ```bash | |
| 10 | ./template/build.sh | |
| 11 | ``` | |
| 12 | ||
| 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-code-acp` adapter on top of the official `docker/sandbox-templates:claude-code` image. For a local-only image use `make template` instead. | |
| 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 \ | |
| 19 | --template k33g/ori:0.0.0 \ | |
| 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 | ||
| 25 | 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. | |
| 26 | ||
| 27 | 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` at creation (or later with `sbx ports <sandbox-name> --publish 8888:8888/tcp`). | |
| 28 | ||
| 29 | ## Variants | |
| 30 | ||
| 31 | - The listen port is a kit argument (default 8888): add `--kit-arg ori.port=9000` to change it (and publish that port instead). | |
| 32 | - 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`. | |
| 33 | - Standalone, without sbx: `docker run --rm -p 8888:8888 k33g/ori` (provide `ANTHROPIC_API_KEY`, or use the demo agent below). | |
| 34 | - Credential-free demo: inside the sandbox, `pkill -x ori` then relaunch with `--agent-cmd ori-mock-agent`. | |
| 35 | - The server log inside the sandbox is `/home/agent/.ori.log`. | |
| 36 | - A stopped sandbox restarts with `sbx run -d --name <sandbox-name>` (or `sbx attach`); the kit relaunches the server on every start. | |
| 37 | - 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. | |
| 38 | ||
| 39 | ## See also | |
| 40 | ||
| 41 | - Kit details and template contents: [`kits/ori/README.md`](../../../kits/ori/README.md) | |
| 42 | - Flags of the server the kit starts: [reference: the ori command](../reference/cli.md) |