@amond-ai/sandbox-cloudflare
v0.2.0
Published
A Cloudflare Sandbox backend for @amond-ai/sandbox — the Durable Object @cloudflare/sandbox 1.0 leaves to the application, and a session that maps it onto the contract
Maintainers
Readme
@amond-ai/sandbox-cloudflare
A Cloudflare Sandbox backend for
@amond-ai/sandbox, built on @cloudflare/sandbox 1.0.
import { createHarnessSandboxProvider } from '@amond-ai/harness-sandbox'
import { createCloudflareProvider } from '@amond-ai/sandbox-cloudflare'
import { env } from 'cloudflare:workers'
export { HarnessSandbox } from '@amond-ai/sandbox-cloudflare'
const sandboxes = createCloudflareProvider(env.Sandbox)
// The same provider, handed to the AI SDK harness as its sandbox.
const harnessSandbox = createHarnessSandboxProvider({
sandboxes,
defaultWorkingDirectory: '/workspace',
ports: [30_000],
})env.Sandbox is the Durable Object namespace bound to HarnessSandbox in your
wrangler.jsonc.
What the package ships
@cloudflare/sandbox 1.0 no longer ships a Sandbox Durable Object or a client with a process
table: the application writes its own Durable Object and drives the container through
ctx.container. This package is that Durable Object plus the mapping layer onto the contract, so
Cloudflare is now a mapped backend like e2b and Daytona.
| Piece | What it does |
| --- | --- |
| HarnessSandbox | The Durable Object. Starts the container (images.sandbox, standard-1, Internet on, five-minute inactivity timeout), runs processes with Cloudflare's background-process pattern, serves files through Files, and forwards bridge connections into the container. |
| createCloudflareProvider(namespace) | session(id) resolves namespace.getByName(id.toLowerCase()) synchronously and maps the contract onto the object's RPC methods. |
| Port endpoint | A localhost URL tagged with SANDBOX_ID_PARAM, built by sandboxRoutedUrl from @amond-ai/harness-transport-cloudflare. The transport sends the upgrade to HarnessSandbox.fetch with the port in SANDBOX_PORT_HEADER, and the object forwards it with getTcpPort. Building the URL does no I/O. |
How the contract maps:
- Processes. Each process gets
/var/lib/processes/<id>/withpid,stdout.log,stderr.log,exit-codeandmeta.json. The command runs undersetsid, sokill()signals its whole group: SIGTERM by default, or the named signal (kill(2)sends SIGINT). An alarm keeps the container running while any process does. - Exit codes. The status is reported as recorded. A signalled command's
128 + nis not decoded intosignal, becauseexit 143records the same number.timedOutis true only whenexec's owntimeoutended the process. - Discovery.
getProcessandlistProcessesanswernulland[]from a stopped container without starting one.existsstarts it.destroynever does. - Files.
writeFilecreates missing parent directories, as 0.x did. A read defaults toutf-8; passencoding: 'base64'for bytes.
Overriding the defaults
Consumers never construct the Durable Object, so it is configured by subclassing:
import { HarnessSandbox } from '@amond-ai/sandbox-cloudflare'
export class Sandbox extends HarnessSandbox<Env> {
protected override inactivityTimeoutMs(): number {
return 30 * 60 * 1000
}
protected override async setupContainer(container: Container): Promise<void> {
// Runs for each new container and after the object restarts; must be safe to repeat.
// GIT_CREDENTIALS stands for a Fetcher binding your Worker defines; this package has none.
await container.interceptOutboundHttps('github.com', this.env.GIT_CREDENTIALS)
}
}containerOptions() returns the options passed to container.start().
Migrating from @cloudflare/sandbox 0.x
Read Cloudflare's migration guide first.
The steps below are what changes for a Worker that used this package on @cloudflare/sandbox 0.x.
Export the new class under the old name. Replace
export { Sandbox } from '@cloudflare/sandbox'withexport { HarnessSandbox as Sandbox } from '@amond-ai/sandbox-cloudflare'. Keeping the class name keeps theSandboxbinding, its storage, and theclass_name: "Sandbox"below.Change the
containersentry for that class:{ "compatibility_date": "2025-11-17", "compatibility_flags": ["nodejs_compat"], "containers": [ { "class_name": "Sandbox", "name": "my-worker-sandbox-v1", "scheduling_policy": "durable_object", "images": { "sandbox": { "dockerfile": "./Dockerfile" } } } ] }scheduling_policy: "durable_object"lets each object start its own container.- Give the container application a
nameyour account has not used. Without one, the deploy fails after the new Worker version is already live. - Remove
image,instance_typeandmax_instances; this policy rejects them. The image moves toimages.sandbox. - Keep
nodejs_compat, and use a compatibility date of2025-11-17or later. - Leave
durable_objectsandmigrationsas they are.
Replace the image base.
FROM docker.io/cloudflare/sandboxno longer applies. Start from an image with the tools the agent needs, and copy insandbox-shim, whichFilesneeds:FROM node:24-trixie-slim # git for the agent; coreutils (dd, head, wc) and util-linux (setsid) for the process scripts. RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates git coreutils util-linux \ && rm -rf /var/lib/apt/lists/* COPY --from=docker.io/cloudflare/sandbox:1.0.2 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"]procpsis not needed:killis a shell builtin. Keep thesandbox-shimtag in step with the installed@cloudflare/sandbox. Commands do not seeENVlines, so pass values throughexec'senvoption instead.Remove 0.x options.
SANDBOX_OPTIONSis gone from@amond-ai/harness-transport-cloudflare. ItsnormalizeId: trueis now the lowercasing inopenSandbox, and itssleepAfter: '5m'isHarnessSandbox's inactivity timeout. Outbound rules such asSandbox.outboundByHostmove tosetupContainer(); see Cloudflare's outbound traffic page.
Before you deploy, know what the switch does:
- It is one-way. After the deploy that moves the class to
scheduling_policy: "durable_object", 0.x code cannot start containers for it, even afterwrangler rollback. - In place or side by side. Keeping the class name moves every sandbox in one deploy. Commands running in 0.x containers end, and files in them do not carry over: a run that was mid-turn has to start again. For long-lived sandboxes, Cloudflare describes moving side by side under a new class name instead.
- 0.x support ends on 2026-12-31. Until then it receives bug and security fixes only.
What it does not supply
The contract does not express a credential path for repository access, and neither does this
package. On Cloudflare the consuming Worker supplies it out of band, by intercepting the
container's egress from a HarnessSandbox subclass (setupContainer() above); see
@amond-ai/sandbox.
Upstream
The AI SDK tracks a first-party Cloudflare provider in
vercel/ai#17638. Its bridge rule asks for a URL a
stock ws client can dial, and a Cloudflare sandbox's private port gives none, so this package
backs the bridge adapters only together with
@amond-ai/harness-transport-cloudflare.
This repository tracks the upstream provider issues in
amond-ai/harness#64.
License
Apache-2.0. See LICENSE.
