feat: add projectSetupLayer config and sandbox build command (#110)

## Summary

- Add `projectSetupLayer` config option: a bash script baked into a
cached image layer between base and agent overlay, so projects can cache
expensive system-level setup (apt packages, language runtimes, etc.)
- Add `ox sandbox build` command for explicitly building sandbox layers
with `--no-cache` support
- Add `--project` flag to `ox sandbox hash` for inspecting setup layer
hashes

## Image Stack

```
base → projectSetupLayer (optional) → agent overlay → session
```

The setup script runs as root (Docker: `docker exec --user root`, Cloud:
`sudo`), and its content is hashed with the base image hash for cache
invalidation. When either the base image or the script changes, the
layer rebuilds automatically.

## New Commands

```bash
# Build all layers through agent
ox sandbox build --agent claude

# Build just through project setup layer  
ox sandbox build --project

# Force rebuild everything
ox sandbox build --agent claude --no-cache

# Inspect hashes
ox sandbox hash --project
ox sandbox hash --project --cloud
```

## Key Changes

- **Config**: New `projectSetupLayer` string field in `OxConfig`
- **Docker**: `ensureProjectSetupLayer()` builds via run/exec/commit
pattern, streams output to terminal
- **Cloud**: `ensureProjectSetupCloudSnapshot()` builds via
volume/sandbox/snapshot pattern
- **Resource cleanup**: Classifies `oxl-`/`oxlb-` prefixed cloud
resources and `ox-sandbox:md5-*-l-*` Docker images
- **CLI**: `sandbox build` with `--agent`, `--project`, `--cloud`,
`--no-cache` flags; `sandbox hash --project`
- **Force rebuild**: `force` parameter threaded through all ensure
functions and `SandboxProvider.ensureImage()`

## Files Changed

| File | Changes |
|------|---------|
| `src/services/config.ts` | Add `projectSetupLayer` field |
| `src/services/docker.ts` | Hash/tag computation,
`ensureProjectSetupLayer`, `force` param, GHCR pull skip for setup
layers |
| `src/services/sandbox/cloudSnapshot.ts` | Cloud snapshot build,
`force` param, setup hash in agent slugs |
| `src/services/sandbox/cloudProvider.ts` | Chain setup layer into
`ensureImage()` |
| `src/services/sandbox/resources.ts` | Classify setup layer resources
in cleanup |
| `src/services/sandbox/sandboxExec.ts` | Add `stream` option for
real-time output |
| `src/services/sandbox/types.ts` | Add `force` to
`SandboxProvider.ensureImage()` |
| `src/services/sandbox/dockerProvider.ts` | Thread `force` through |
| `src/commands/sandbox.ts` | `build` subcommand, `--project` flag on
`hash`, flag validation |
| Tests | New tests for hash, slug, and resource classification |

Author: murrayju

docs/configuration.md

@@ -42,7 +42,10 @@ The wizard walks through sandbox provider, agent, model, and authentication setu
 | `cloudRegion` | `string` | `ord` | Cloud sandbox region: `ord` (Chicago) or `ams` (Amsterdam) |
 | `sandboxBaseImage` | `string` | -- | Override Docker image for sandbox containers |
 | `buildSandboxFromDockerfile` | `boolean\|string` | `false` | Build sandbox image from Dockerfile. `true` uses the built-in Dockerfile; a string value specifies a path to a custom Dockerfile. Takes precedence over `sandboxBaseImage`. |
+| `projectSetupLayer` | `string` | -- | Bash script to run on top of the base sandbox image and cache as a reusable layer. Use for system-level dependencies like apt packages, language runtimes, Docker, or browser tooling. Runs before the agent overlay and without your project repo mounted. |
 | `overlayMounts` | `string[]` | -- | Paths to isolate with Docker volume mounts in [mount mode](sandbox-providers.md#mount-mode). E.g., `["node_modules"]` |
+| `privileged` | `boolean` | `false` | Run Docker sandbox containers in privileged mode (`--privileged`). Required for Docker-in-Docker. Only applies to the Docker sandbox provider. |
+| `rootInitScript` | `string` | -- | Shell command to run as **root** inside the sandbox before `initScript`. Useful for installing system packages. E.g., `"apt-get update && apt-get install -y build-essential"` |
 | `initScript` | `string` | -- | Shell command to run inside the sandbox before starting the agent. Runs in all modes. E.g., `"npm install"` |
 
 ### Port Forwarding
@@ -141,6 +144,18 @@ API_KEY=your-key-here
 
 These variables are injected into the sandbox container at startup and are available to both the init script and the agent.
 
+## Build-Time vs Run-Time Setup
+
+Ox supports three different setup hooks for sandbox customization:
+
+- `projectSetupLayer` -- build-time, cached image layer; best for system packages and heavyweight tooling that should be reused across sessions
+- `rootInitScript` -- run-time, runs as root on every session start, resume, and shell creation
+- `initScript` -- run-time, runs as the sandbox user on every session start, resume, and shell creation
+
+Use `projectSetupLayer` for things like `apt-get install`, browser dependencies, Docker tooling, or language runtimes that do not depend on your repository contents. Because it runs before your repo is mounted and is cached as an image/snapshot layer, it avoids repeating expensive setup work on every session.
+
+Use `rootInitScript` or `initScript` for per-session setup that depends on the working directory, environment variables, checked-out code, or other state that is only available at container startup.
+
 ## Example Config
 
 ```yaml
@@ -153,6 +168,11 @@ tigerServiceId: null
 themeName: tokyonight
 overlayMounts:
   - node_modules
+projectSetupLayer: |
+  apt-get update
+  apt-get install -y ffmpeg chromium
+privileged: true
+rootInitScript: "apt-get update && apt-get install -y build-essential"
 initScript: "npm install"
 appPort: 3000
 additionalPorts:

docs/sandbox-providers.md

@@ -9,11 +9,32 @@ Agents run in local Docker containers built from purpose-built images that inclu
 ### How It Works
 
 1. **Base image** -- Ox uses a pre-built image from GHCR (`ghcr.io/timescale/ox`) based on Ubuntu 24.04 with git, ripgrep, curl, tmux, GitHub CLI, and other essentials
-2. **Agent overlay** -- On top of the base, ox builds an agent-specific overlay that installs the chosen agent CLI (Claude Code, OpenCode, or Codex)
-3. **Container creation** -- A container is created with your code (cloned from GitHub or mounted from your filesystem), credentials injected, and the agent launched
+2. **Project setup layer** -- If `projectSetupLayer` is configured, ox runs that script on top of the base image and caches the result as a reusable image/snapshot layer
+3. **Agent overlay** -- On top of the base or project setup layer, ox builds an agent-specific overlay that installs the chosen agent CLI (Claude Code, OpenCode, or Codex)
+4. **Container creation** -- A container is created with your code (cloned from GitHub or mounted from your filesystem), credentials injected, any runtime init scripts run, and the agent launched
 
 Images are cached locally. The first run pulls and builds the images, which takes a few minutes. Subsequent runs start in seconds.
 
+### Project Setup Layer
+
+Use `projectSetupLayer` when you want to install heavyweight system dependencies once and reuse them across many sessions:
+
+```yaml
+# .ox/config.yml
+projectSetupLayer: |
+  apt-get update
+  apt-get install -y ffmpeg chromium
+```
+
+This script runs as root on top of the sandbox base image and is cached as its own layer before the agent overlay is built.
+
+- It runs **without** your repository mounted, so it should only be used for system-level setup
+- It is ideal for `apt-get install`, browser/runtime dependencies, Docker tooling, and other expensive base environment changes
+- When the script changes, ox automatically rebuilds the cached layer
+- It works for both Docker and Cloud providers
+
+For one-off or repo-dependent setup, use `rootInitScript` or `initScript` instead.
+
 ### Custom Base Image
 
 Override the base image via config:
@@ -66,6 +87,15 @@ initScript: "npm install"
 
 The init script runs after the working directory is set up, in all modes (async, interactive, plan). Useful for installing dependencies, setting up databases, or any other preparation.
 
+If you need root access at runtime, use `rootInitScript`:
+
+```yaml
+# .ox/config.yml
+rootInitScript: "apt-get update && apt-get install -y build-essential"
+```
+
+`rootInitScript` runs before `initScript` on every session start, resume, and shell creation. Unlike `projectSetupLayer`, it is not cached as an image layer.
+
 ## Cloud
 
 Agents run in remote sandboxes powered by Deno Deploy. Useful for offloading work from your machine or running many tasks in parallel without local resource constraints.