Quickstart

Goal

Run Cloudbox locally or deploy it, then hand your agent a clean Linux box with receipts and artifacts.

1. Run or deploy

Use pnpm for install and workspace commands. Bun is required because several repo scripts invoke Bun, Wrangler, and Alchemy internally.

git clone https://github.com/acoyfellow/cloudbox
cd cloudbox
pnpm install
pnpm run dev

Open the URL the script prints and go to /demo.

To deploy your own Cloudbox, use the verified GitHub Actions path with the required production secrets. The Deploy to Cloudflare button is the public funnel and should be treated as experimental until your account configuration is confirmed.

Once deployed, you can POST /api/runs from any agent — Cloudbox itself runs nothing on your behalf.

2. Bring your agent

Cloudbox is agent-agnostic. Anything that can POST JSON can drive it. The simplest path:

curl -X POST https://YOUR-CLOUDBOX.workers.dev/api/runs \
  -H "authorization: Bearer $CLOUDBOX_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "repo": "https://github.com/you/app",
    "commands": ["pnpm install --ignore-scripts"],
    "verify": ["pnpm run build", "pnpm test"],
    "artifact": "HANDOFF.md"
  }'

Drop this prompt into your agent:

Copy prompt

You have access to Cloudbox at https://YOUR-CLOUDBOX.workers.dev.

Use Cloudbox when repo work needs proof:
- POST /api/runs with the repo, commands, verify commands, and requested artifact
- inspect receipts, runnerReceipts, and the returned diff to confirm the work
- use live=true when a human or agent needs follow-up exec/read/write/dev preview
- return the Cloudbox response, artifact path, and verification result

3. Manual walkthrough

Get from clone to a working local demo in under seven minutes.

The local loop uses pnpm, Bun ≥ 1.3, and Node ≥ 22. No secrets needed for the demo path. Cloudflare bindings (CLOUDBOX_RUNNER, CLOUDBOX_DESKTOP_RUNNER, CLOUDBOX_COMPUTER, R2, D1) come online when you pnpm run dev:worker or deploy.

Inside the runner container, pnpm is the default package manager and the image ships with git, node, bun, and pnpm preinstalled. Recipe examples lean on pnpm; pick whatever your repo uses.

Run the demo

Click Run in Cloudbox.

The demo performs the same lifecycle your agents should use:

1. clone a public repo
2. boot the Cloudflare Container runner
3. run explicit commands
4. run verification
5. return one artifact plus work and runner receipts

The UI should show runner readiness, proof timeline, work receipts, and the returned artifact.

Verify the repo

pnpm run check

This builds the docs/app, typechecks, and runs tests.

Optional: drive the workspace protocol

Typed workspaces are the secondary evaluation surface. Materialize a spec by posting your own ComputerSpec JSON:

curl -s -X POST http://localhost:8799/api/computers \
  -H 'content-type: application/json' \
  -d @spec.json

The response includes { id, baseUrl }. Then use the workspace protocol:

curl -s "http://localhost:8799/api/c/$ID/list"
curl -s "http://localhost:8799/api/c/$ID/read?path=README.md"
curl -s -X POST "http://localhost:8799/api/c/$ID/ask" \
  -H 'content-type: application/json' \
  -d '{"who":"skeptic","message":"What am I overclaiming?"}'
curl -s -X POST "http://localhost:8799/api/c/$ID/write" \
  -H 'content-type: application/json' \
  -d '{"path":"artifacts/launch-note.md","content":"ready"}'
curl -s -X POST "http://localhost:8799/api/c/$ID/submit" \
  -H 'content-type: application/json' \
  -d '{"objective":"launch-readiness","decision":"share"}'
curl -s "http://localhost:8799/api/c/$ID/grade"

Stop condition

The quickstart is healthy when a fresh clone can:

pnpm install
pnpm run check
pnpm run dev

…and /demo produces a visible repo-run receipt trail plus an artifact.