Goal

Get Cloudbox into your Cloudflare account, then hand your agent a clean Linux box with receipts and artifacts.

1. Deploy your own

Cloudbox is built to be your Cloudbox. The button forks the repo into your account and runs alchemy.run.ts, which provisions the Worker, the CloudboxRunner Durable Object + cloudbox-runner Cloudflare Container, the workspace DO namespace, R2, and D1. The one-click flow is the public funnel; the GitHub Actions deploy path is the verified one for this repo today.

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
- for richer flows, materialize a workspace via /api/computers and drive /api/c/:id/*
- return the Cloudbox response, artifact path, and final grade

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_COMPUTER, R2, D1) come online when you bun 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.

Clone and install

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

Run the app

bun run dev

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

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.

Drive the protocol yourself

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 receipt trail plus a nonzero grade.