# Ori — quickstart

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

## Prerequisites

- 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`).
- The ori kit: clone this repository (only `kits/ori/` is needed).

## Quick Start

```
sbx run -d claude . \
  --template k33g/ori:0.0.3 \
  --kit docker.io/k33g/ori-kit:latest \
  --name hello-world \
  -p 5555:8888/tcp
```
Then open **http://localhost:5555** — the panel connects to a Claude Code session already running in the sandbox, no login needed.

Or you can use **ori-desktop**

```bash
cd ori-desktop
wails build
xattr -cr build/bin/ori-desktop.app
```
Then **double-click** on the application


## Create the sandbox

From the directory where the kit lives, pointing at the project you want the agent to work on:

```bash
sbx run -d claude ~/path/to/your/project \
  --template k33g/ori:0.0.3 \
  --kit ./kits/ori \
  --name ori \
  -p 8888:8888/tcp
```

Then open **http://localhost:8888** — the panel connects to a Claude Code session already running in the sandbox, no login needed.

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

Without `-p`, the kit still publishes an ephemeral port; the command output prints it:

```
  Published web: localhost:54321 -> 8888/tcp
```

## Everyday commands

| Action | Command |
| --- | --- |
| Use another host port (e.g. http://localhost:5555) | `-p 5555:8888/tcp` at creation, or `sbx ports ori --publish 5555:8888/tcp` |
| Change the internal port | `--kit-arg ori.port=9000` (then `-p 9000:9000`) |
| Publish / unpublish a port later | `sbx ports ori --publish 8888:8888/tcp` / `--unpublish 8888:8888/tcp` |
| Follow the server log | `sbx exec ori tail -f /home/agent/.ori.log` |
| Inspect why the kit's startup ran or failed | `sbx exec ori cat /var/log/sbx-kit-startup.log` |
| Open a shell in the sandbox | `sbx exec -it ori bash` |
| Attach the terminal Claude session (starts a stopped sandbox) | `sbx attach ori` |
| Restart a stopped sandbox without attaching | `sbx run -d --name ori` |
| Stop / remove | `sbx stop ori` · `sbx rm ori` |
| 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) |
| 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 &'` |

## Building the image yourself

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

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)

---