Skip to content

Deploy a Sandbox application

Last updated View as MarkdownAgent setup

Sandbox runs on Containers. For deploy commands, Workers Builds, and rollout flags, refer to Deploy Containers and Rollouts.

To put exposePort() on a custom domain, refer to Configure preview URLs on a custom domain.

Keep the package and image aligned

The Worker depends on @cloudflare/sandbox (or @cloudflare/sandbox@next). The container image must come from the same release line (Dockerfile and base image tags from the template or docs for that version).

When you bump the npm package:

  1. Update the Dockerfile or image reference for the same line.

  2. Run wrangler deploy so the new image is published.

  3. If the Worker and image must cut over together, deploy with an immediate rollout:

    npx wrangler deploy --containers-rollout=immediate

    Use this for stable to @next cutovers and other breaking package/image pairs. Refer to Migrate and Rollouts.

Do not mix a stable package with a @next image, or the reverse.

Deploy from your machine

  1. Start Docker if image is a Dockerfile path. Registry image references do not need Docker at deploy time.

  2. From the project root:

    npx wrangler deploy

  3. Confirm the Worker URL responds, then exercise a sandbox route.

The first deploy can take several minutes while the image provisions.

Workers Builds

For production, use wrangler deploy so the package and image can update together.

Non-production Workers Builds defaults to wrangler versions upload, which does not publish a new image. Preview URLs are not generated for these Workers (they implement Durable Objects). Test with wrangler dev, or with a staging Worker or environment that runs wrangler deploy.

More detail: Before production.

Was this helpful?