Skip to main content
Superserve runs cloud coding agents, long-running agents, CI workers, background jobs, evals, and RL environments in isolated VMs. If you run these on Cloudflare today, most code moves call by call.

How Superserve compares

Ready to switch

Pick how you want to migrate. Do it yourself step by step, or give the prompt to a coding agent and let it change your code.
Before you start
  • Get a Superserve API key. Sign in to the console, or sign up for free (no card required). Open API Keys and click Create Key. See Get an API key.
1

Install the SDK and set your API key

Install the Superserve SDK and set SUPERSERVE_API_KEY in your environment and CI secrets.
The TypeScript SDK also runs in a Cloudflare Worker with the nodejs_compat flag. There, store the key with npx wrangler secret put SUPERSERVE_API_KEY.
2

Map the API

The main changes: Superserve is an API that you call from any backend, so you need no Durable Object or container configuration. A Dockerfile becomes a template, every sandbox gets an id that you keep, and an idle sandbox pauses with its memory and disk. The Cloudflare columns show Sandbox SDK 0.12 calls on the sandbox stub and 1.0 calls on this.ctx.container.
To turn your Dockerfile into a template, see Create a template.
3

Update your code

Replace the sandbox stub or Durable Object with Sandbox, add a name, and change paths under /workspace to /home/user.
4

Move existing sandboxes with the migration script

A Cloudflare sandbox is reachable only through your Worker. First add a temporary export route to the Worker. The route archives /workspace in one sandbox and streams the archive back. Protect it with a MIGRATION_TOKEN secret. The route refuses all requests until the secret is set.
Then run the script with the sandbox IDs that your app passes to getSandbox() or getByName(). The script copies each archive into /home/user in a new Superserve sandbox. It does not change or delete your Cloudflare sandboxes. If a copy fails, the script deletes the new Superserve sandbox. Set CLOUDFLARE_EXPORT_URL to the full URL of the route, and set MIGRATION_TOKEN and SUPERSERVE_API_KEY.
For example, run npx tsx migrate-from-cloudflare.ts user-123 user-456. Run the script while the sandboxes are awake. A Cloudflare sandbox that went to sleep starts again with an empty disk, so restore its backup first.Each upload and extract can take up to 10 minutes. For large directories or slow connections, raise TIMEOUT_MS / TIMEOUT_SECONDS.The script copies files. Start your services in the new sandbox, then take a Superserve snapshot to save memory, processes and disk together.
5

Verify and cut over

Run your test suite against Superserve. Check the sandbox list in the console. When the results match, send production traffic to Superserve.
6

Uninstall Cloudflare Sandbox

After the cutover, remove the export route and the MIGRATION_TOKEN secret. Then remove the Sandbox SDK package. To delete the sandbox class, remove its containers and durable_objects entries from your Wrangler configuration and add a deleted_classes migration.

Known differences