spawn-agent-cloud

Spawn an agent in Cloudflare, not on your laptop.

A 7-minute public demo combining three projects into one Deploy-to-Cloudflare button:

• spawn-agent — runs a real coding-agent CLI (Claude Code / OpenCode / Codex / …) and streams it as a Vercel-AI-SDK provider over the Agent Client Protocol.
• alchemy-effect — Infrastructure-as-Effects. The whole stack (Worker, Container, Durable Objects, Artifacts repo, Worker Loader binding) is one TypeScript file.
• Cloudflare — Containers, Durable Objects, Worker Loader (dynamic isolate loading), and Artifacts (Git-compatible repos).

Click the button. 60 seconds later, you have a public URL with a 3-pane app: a code editor backed by a real Git repo, an agent terminal streaming live ACP frames from opencode running in an edge sandbox, and a preview pane that hot-reloads on every commit via Worker Loader.

The agent's "local computer" is a Cloudflare Container. The repo it edits is a Cloudflare Artifacts repo — you can git clone it from your laptop, see the agent's commits, push your own.

Deploy

🚧 Status: alpha. This repo is being built in the open. The deploy button works against the main branch; check the latest commit's message for what currently works end-to-end. See Iteration status below.

What you get

One Worker URL	https://spawn-agent-cloud.<your-subdomain>.workers.dev
Per-session sandbox	Each browser session gets its own Cloudflare Container running opencode
Per-session Git repo	Each session gets a Cloudflare Artifacts repo. Clone it from your laptop.
Hot reload	Every agent commit hot-loads via Worker Loader — /preview/<sid>/* serves the latest worker.js

┌──────────────────────────────────────────────────────────────────────┐
│ Browser (3 panes: code editor / agent terminal / live preview)       │
└──────────────────────┬─────────────────────────────────────┬─────────┘
                       │ WS: ACP frames                      │ HTTP: /preview/:id/*
                       ▼                                     ▼
              ┌────────────────────┐              ┌────────────────────┐
              │  Api Worker        │              │  Worker Loader     │
              │  (alchemy Worker)  │              │  (dynamic isolate) │
              └──────────┬─────────┘              └──────────▲─────────┘
                         │                                   │
                         ▼                                   │
              ┌────────────────────┐                         │
              │  SessionDO         │─────────────────────────┘
              │  (per session)     │
              └──────────┬─────────┘
                         │
                         ▼
              ┌────────────────────┐         ┌──────────────────────┐
              │  Sandbox Container │ ◀──────▶│ Cloudflare Artifacts │
              │   - node 22        │  git    │ (per-session repo)   │
              │   - git            │         └──────────────────────┘
              │   - opencode CLI   │
              │   - spawn-agent    │
              │   - /workspace/    │
              │   - HTTP+WS :3000  │
              └────────────────────┘

Prerequisites for deploying

• A Cloudflare account with the following enabled (some are still in beta — request access in the Cloudflare dashboard if you don't see them):
  • Workers paid plan (containers + worker_loader currently require it)
  • Containers (in dashboard sidebar)
  • Worker Loader (currently closed beta — request access)
  • Artifacts (currently beta — request access)
• An API token with: Workers:Edit, Workers:Deploy, Containers:Edit, Artifacts:Edit.
• Optional but recommended: an OPENCODE_API_KEY secret (your model provider key) — set after deploy via bun alchemy secret put OPENCODE_API_KEY or in the dashboard. Without it, opencode falls back to whatever default it can find.

If you don't have all the betas, the deploy will still mostly work — Artifacts and Worker Loader pieces will fail gracefully and the UI will show "feature requires beta access".

Develop locally

git clone https://github.com/acoyfellow/spawn-agent-cloud
cd spawn-agent-cloud
bun install
bun alchemy dev

This runs the Worker locally via wrangler dev (alchemy provides the bindings) and the container locally via Docker. You'll get a localhost URL where you can iterate.

To deploy:

bun alchemy deploy

To tear it all down:

bun alchemy destroy

Repo layout

spawn-agent-cloud/
├── alchemy.run.ts            # whole stack — Worker + DO + Container + Artifacts + Loader
├── package.json
├── tsconfig.json
├── README.md                 ← you are here
├── src/
│   ├── Api.ts                # Worker (routes / + /api/* + /preview/*)
│   ├── SessionDO.ts          # Durable Object — one per browser session
│   ├── Sandbox.ts            # Container — node + git + opencode
│   └── Repos.ts              # Artifacts namespace handle
├── assets/
│   ├── index.html            # 3-pane UI
│   ├── app.js                # vanilla JS — no build step
│   └── style.css
└── .context/
    └── ARCHITECTURE.md       # detailed design notes

Iteration status

This repo is being built in iterations against a real bun alchemy dev loop:

• Iteration 0 — design + scaffold. All files present; not yet tested with bun install.
• Iteration 1 — bun alchemy dev succeeds; Worker serves the UI; "new session" creates an Artifacts repo; WS connects.
• Iteration 2 — Container starts on first prompt; /health reachable from the DO.
• Iteration 3 — spawn-agent("opencode") running inside the container, streaming ACP frames over WS to the browser.
• Iteration 4 — Container watches /workspace, commits + pushes to Artifacts on agent edits.
• Iteration 5 — Worker Loader serves the agent's worker.js from /preview/:id/*. End-to-end loop works.
• Iteration 6 — README screencast + Deploy button verified on a fresh CF account.

See .context/ARCHITECTURE.md for design rationale, especially the "what alchemy-effect provisions in one file" section.

Why this is interesting

spawn-agent was designed for local agent CLIs — the agent runs as a subprocess on the developer's machine. We invert it: the agent's "local machine" is a Cloudflare Container. Instead of claude-code running on your laptop with access to your project, it runs at the edge with access to a per-session Artifacts repo that you can also git clone to your laptop.

The result: a remote AI pair programmer with a real Git history, a real preview environment, and zero npm install on your laptop.

License

Apache-2.0