# How to run Ori in a Docker sandbox

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.

## Steps

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:

   ```bash
   ./template/build.sh
   ```

   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.

2. Create the sandbox from your project directory, with the template and the ori kit, in detached mode:

   ```bash
   sbx run -d claude ~/path/to/your/project \
     --template k33g/ori:0.0.0 \
     --kit /path/to/ori/kits/ori
   ```

   `-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.

   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.

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`).

## Variants

- The listen port is a kit argument (default 8888): add `--kit-arg ori.port=9000` to change it (and publish that port instead).
- 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`.
- Standalone, without sbx: `docker run --rm -p 8888:8888 k33g/ori` (provide `ANTHROPIC_API_KEY`, or use the demo agent below).
- Credential-free demo: inside the sandbox, `pkill -x ori` then relaunch with `--agent-cmd ori-mock-agent`.
- The server log inside the sandbox is `/home/agent/.ori.log`.
- A stopped sandbox restarts with `sbx run -d --name <sandbox-name>` (or `sbx attach`); the kit relaunches the server on every start.
- 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.

## See also

- Kit details and template contents: [`kits/ori/README.md`](../../../kits/ori/README.md)
- Flags of the server the kit starts: [reference: the ori command](../reference/cli.md)