forked from bots-garden/ori
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 1 | # Ori — quickstart |
| 2 | ||
| 🛟 Updated. | 3 | Launch a Docker sandbox running [Ori](README.md): Claude Code plus its web UI (chat panel, file tree, Monaco editor, terminal), in your browser or with **ori-desktop**. |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 4 | |
| 5 | ## Prerequisites | |
| 6 | ||
| 7 | - Docker Desktop with the `sbx` CLI, and your Anthropic credentials configured for sandboxes (`sbx secret set anthropic …` or an OAuth login — whatever you already use for `sbx run claude`). | |
| 8 | - The ori kit: clone this repository (only `kits/ori/` is needed). | |
| 9 | ||
| 🛟 Updated. | 10 | ## Quick Start |
| 11 | ||
| 12 | ``` | |
| 13 | sbx run -d claude . \ | |
| 14 | --template k33g/ori:0.0.3 \ | |
| 15 | --kit docker.io/k33g/ori-kit:latest \ | |
| 16 | --name hello-world \ | |
| 17 | -p 5555:8888/tcp | |
| 18 | ``` | |
| 19 | Then open **http://localhost:5555** — the panel connects to a Claude Code session already running in the sandbox, no login needed. | |
| 20 | ||
| 21 | Or you can use **ori-desktop** | |
| 22 | ||
| 23 | ```bash | |
| 24 | cd ori-desktop | |
| 25 | wails build | |
| 26 | xattr -cr build/bin/ori-desktop.app | |
| 27 | ``` | |
| 28 | Then **double-click** on the application | |
| 29 | ||
| 30 | ||
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 31 | ## Create the sandbox |
| 32 | ||
| 33 | From the directory where the kit lives, pointing at the project you want the agent to work on: | |
| 34 | ||
| 35 | ```bash | |
| 36 | sbx run -d claude ~/path/to/your/project \ | |
| 🛟 Updated. | 37 | --template k33g/ori:0.0.3 \ |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 38 | --kit ./kits/ori \ |
| 39 | --name ori \ | |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 40 | -p 8888:8888/tcp |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 41 | ``` |
| 42 | ||
| 43 | Then open **http://localhost:8888** — the panel connects to a Claude Code session already running in the sandbox, no login needed. | |
| 44 | ||
| 45 | > **Why `sbx run -d` and not `sbx create`?** sbx stops a sandbox 30 seconds after the last CLI session on it closes — browser traffic does not count. `sbx create` holds such a session only while it runs, so a sandbox created that way goes `stopped` half a minute after the prompt returns. `-d` (`--detached`) marks the sandbox as detached at creation, which exempts it from that auto-stop for good; it then runs until you `sbx stop` or `sbx rm` it. The flag only exists on `sbx run`, and the mode cannot be changed afterwards: a sandbox created with `sbx create` must be removed and recreated. | |
| 46 | ||
| 47 | Without `-p`, the kit still publishes an ephemeral port; the command output prints it: | |
| 48 | ||
| 49 | ``` | |
| 50 | Published web: localhost:54321 -> 8888/tcp | |
| 51 | ``` | |
| 52 | ||
| 53 | ## Everyday commands | |
| 54 | ||
| 55 | | Action | Command | | |
| 56 | | --- | --- | | |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 57 | | Use another host port (e.g. http://localhost:5555) | `-p 5555:8888/tcp` at creation, or `sbx ports ori --publish 5555:8888/tcp` | |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 58 | | Change the internal port | `--kit-arg ori.port=9000` (then `-p 9000:9000`) | |
| 59 | | Publish / unpublish a port later | `sbx ports ori --publish 8888:8888/tcp` / `--unpublish 8888:8888/tcp` | | |
| 60 | | Follow the server log | `sbx exec ori tail -f /home/agent/.ori.log` | | |
| 61 | | Inspect why the kit's startup ran or failed | `sbx exec ori cat /var/log/sbx-kit-startup.log` | | |
| 62 | | Open a shell in the sandbox | `sbx exec -it ori bash` | | |
| 63 | | Attach the terminal Claude session (starts a stopped sandbox) | `sbx attach ori` | | |
| 64 | | Restart a stopped sandbox without attaching | `sbx run -d --name ori` | | |
| 65 | | Stop / remove | `sbx stop ori` · `sbx rm ori` | | |
| 🛟 Updated. | 66 | | Start (or restart) the sandbox and open ori-desktop in one go | `osascript scripts/launch-ori.applescript` — or a double-clickable app, see [scripts/README.md](scripts/README.md) | |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 67 | | Demo without Claude usage | `sbx exec ori sh -c 'pkill -x ori; nohup ori --addr :8888 --agent-cmd ori-mock-agent --cwd /home/agent/workspace >> /home/agent/.ori.log 2>&1 &'` | |
| 68 | ||
| 69 | ## Building the image yourself | |
| 70 | ||
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 71 | Only needed if you maintain the template: `./template/build.sh` builds and pushes `k33g/ori:0.0.2` + `:latest` (multi-arch). For a never-pushed local image: `make template && docker save k33g/ori -o /tmp/ori.tar && sbx template load /tmp/ori.tar`. |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 72 | |
| 73 | Full guide: [docs/en/how-to/run-in-a-sandbox.md](docs/en/how-to/run-in-a-sandbox.md) · [docs/fr/how-to/run-in-a-sandbox.md](docs/fr/how-to/run-in-a-sandbox.md) | |
| 74 | ||
| 🛟 Updated. | 75 | --- |
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 76 | |
| ✨ Switch the ACP adapter to @agentclientprotocol/claude-agent-acp (template 0.0.2) | 77 | |
| 78 | ||
| 79 |