cocoonbox

A persistent cloud computer per user, with a resident agent that any model can drive and a native macOS client to watch it, talk to it, and take over. Local coding agents use the same box through MCP.

Each box is a Linux desktop (Ubuntu 24.04, XFCE) in a cocoon microVM, claimed from sandbox warm pools, hibernated when idle and woken in about a second. Model calls go through gateway (gw).

CocoonBox.app / cocoonbox CLI / local agents (MCP)
        │  gRPC over HTTP/2, MCP Streamable HTTP
        ▼
cocoonbox-api ── control plane: users, boxes, sharing, Connect, vault, state layer
        │        edge: ownership check, per-box credential, frame-by-frame proxy
        │  claims, wake, hibernate, port relay
        ▼
sandboxd (cocoonstack/sandbox) ──► cocoon microVM: the box
                                     ├─ cocoonbox-agent serve: agent loop, gRPC Agents/Session/State, /mcp
                                     ├─ shuttle serve (loomhand/shuttle): the desk, computer verbs,
                                     │    gui_plan, script_run, and as its children cua-driver (loomhand/cua)
                                     │    and cocoonbox-agent toolhost-service: shell, files, CDP browser
                                     └─ Xorg + XFCE desktop ── RFB ──► the app (loomhand/swift-rfb)
model calls ──► gw (cocoonstack/gateway)

Documentation: loomhand.github.io/cocoonbox (design, contracts, layering, measurements), source in docs/.

Layout

Build and test

make help            # every target
make api             # api: fmt check, lint, test, build
make agent           # agent: fmt check, clippy -D warnings, test (CB_NO_BROWSER=1 skips the Chrome tests)
make macos           # macOS app: build and the swift-testing suite (macOS only)
make image           # syntax-check the shell scripts, test cut.sh's dry run and the package replay
make gate            # clean gate over the tracked files and the dependencies; every proto field is read and written

CI runs make agent on Linux and macOS, and clippy, the build and the lib tests on Windows. Linux-gated behaviour is verified on Linux; on macOS run the gates in the pinned toolchain image, with the protoc, rsync, tmux and Node the build, the offload tests and the toolhost test need:

docker run --rm -v "$PWD":/w -w /w/agent -e CB_NO_BROWSER=1 rust:1.98.0 \
  sh -c 'apt-get update -qq && apt-get install -y -qq protobuf-compiler rsync tmux nodejs >/dev/null &&
    cargo fmt --check && cargo clippy --all-targets --locked -- -D warnings && NODE_BIN=$(command -v node) cargo test --locked'

The root Package.swift exports CocoonBoxKit and CocoonBoxTerminal for packages that build on them: .package(url: "https://github.com/loomhand/cocoonbox.git", from: "<version>"). Component details are in agent/README.md, api/README.md and macos/README.md.

Run

• api: api/deploy/api.yaml.example lists the main keys and api/config/config.go all of them; api/deploy/cocoonbox-api.service runs it under systemd behind a reverse proxy (deploy/host/Caddyfile.cocoonbox).
• sandboxd instance and host: deploy/cbsbx/ writes the instance config and units; deploy/host/ holds the host bridge, gw config, the state-store client (cb-s3), apt cache and backups.
• image: image/cut.sh cuts a desktop template from the previous one on the sandboxd host and imports it; versions, pins and publishing are in docs/image.md.
• app: CB_ENDPOINT=https://<api host> macos/scripts/bundle.sh builds macos/dist/CocoonBox.app.

Documentation

• Design
• Contracts
• Boundaries
• Box image
• Android box
• Measurements and lessons

Related projects

License

AGPL-3.0