How to run Ori in a Docker sandbox

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# 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.2`. 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-agent-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.2 \
     --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.

   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.

   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/tcp` 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 yourself with `-p 9000:9000` — the port the kit declares for auto-publishing is fixed at 8888.
- 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/tcp 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)