←back to tutorials

How to Bring Your Own Sandbox with Cloudflare Sandbox Skills

Learn how to deploy your own Cloudflare Sandbox bridge, connect it to ChatBotKit with the Cloudflare Sandbox skills, and give your agent access to your own isolated execution environment.

Cloudflare Sandbox gives you an HTTP API for creating isolated containers, running commands, reading and writing files, and managing warm pools. ChatBotKit now exposes that API through Cloudflare Sandbox abilities, which means you can bring your own deployed sandbox bridge instead of relying on a built-in execution environment.

In this tutorial you will learn how to:

  • Deploy your own Cloudflare Sandbox bridge Worker
  • Create the Cloudflare secret ChatBotKit expects
  • Add the Cloudflare Sandbox skills to a blueprint
  • Instruct your bot to use your bridge URL correctly
  • Test sandbox lifecycle, command execution, and file operations

Prerequisites

  • A ChatBotKit account
  • A Cloudflare account with Workers enabled
  • Node.js installed locally
  • Docker running locally for Cloudflare Sandbox builds
  • Basic familiarity with the Blueprint Designer

Estimated time: 20 to 30 minutes

How the Integration Works

Cloudflare's sandbox bridge is a Worker that exposes the Sandbox SDK over HTTP. ChatBotKit's Cloudflare Sandbox catalogue maps that HTTP API into abilities such as:

  • cloudflare/sandbox/create
  • cloudflare/sandbox/command/create
  • cloudflare/sandbox/file/fetch
  • cloudflare/sandbox/file/update
  • cloudflare/sandbox/mount/create
  • cloudflare/sandbox/delete
  • pack/cloudflare/sandbox

The model does not talk to Cloudflare directly. Instead, it calls the ChatBotKit ability, the ability sends an authenticated HTTP request to your deployed bridge URL, and the bridge talks to the underlying sandbox containers.

This means you control:

  • The Cloudflare account that runs the containers
  • The bridge URL the agent is allowed to use
  • The Docker image and tooling inside the sandbox
  • The API key used to authenticate bridge requests

Learning Objectives

By the end of this tutorial you will have:

  1. A deployed Cloudflare Sandbox bridge Worker
  2. A cloudflare[key] shared secret in ChatBotKit
  3. A blueprint with the Cloudflare Sandbox pack installed
  4. A bot that can create, use, and destroy your own Cloudflare sandboxes

Step 1: Deploy the Cloudflare Sandbox Bridge

Cloudflare provides a reference bridge Worker that exposes the Sandbox SDK as an HTTP API.

Create and deploy it with the current Cloudflare template:

What this does:

  1. Creates a bridge Worker project
  2. Logs you into Cloudflare
  3. Stores a random SANDBOX_API_KEY secret in the Worker
  4. Deploys the Worker and its container image

After deployment, note two values:

  • Your bridge base URL, for example https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev
  • The SANDBOX_API_KEY value you generated

Verify the Worker is reachable:

Expected response:

Note: Cloudflare Sandbox builds container images during deployment, so Docker must be running locally when you deploy.

Step 2: Test the Bridge Outside ChatBotKit

Before wiring the bridge into your agent, confirm the API is working end to end.

Export your values:

Create a sandbox, run a command, and destroy it:

If this works, ChatBotKit will be able to use the same bridge.

Step 3: Create the Cloudflare Secret in ChatBotKit

The Cloudflare Sandbox abilities use the cloudflare[key] secret.

  1. Open ChatBotKit
  2. Go to your blueprint or secret management area
  3. Create a new secret using Cloudflare Sandbox Bridge API Key
  4. Paste the same value you stored in the Worker's SANDBOX_API_KEY
  5. Save it as a shared secret

Use a shared secret here because the API key belongs to your Cloudflare deployment, not to each end user separately.

Step 4: Create a Blueprint and Add the Cloudflare Sandbox Skills

Now create the agent that will use your bridge.

  1. Create a new blueprint
  2. Open the Blueprint Designer
  3. Start with a blank bot and skillset
  4. Search for Install Cloudflare Sandbox Tools
  5. Add the pack/cloudflare/sandbox ability to the skillset
  6. Associate the cloudflare[key] secret when prompted

This pack installs the core bridge abilities for:

  • Sandbox creation and deletion
  • Session management
  • Command execution
  • File reads and writes
  • Bucket mounts
  • OpenAPI inspection
  • Warm pool controls
  • Health checks

If you want a narrower starting point, you can use the read-only variant instead:

  • pack/cloudflare/sandbox[read-only]

Step 5: Tell the Bot Which Bridge URL to Use

The Cloudflare Sandbox abilities require a baseUrl parameter. In practice, for a bring-your-own-sandbox setup you almost always want the bot to use one fixed bridge URL.

The simplest approach is to put that rule in the bot's backstory.

Use a backstory like this:

That gives the model a fixed execution target and reduces the chance of incorrect or inconsistent baseUrl values.

Step 6: Add Operational Guidance

Because sandbox lifecycle is explicit, your bot should know how to behave.

Add guidance like this to the backstory or system notes:

This is important because the bridge does not hide lifecycle management. The agent needs to treat sandbox creation and cleanup as part of the workflow.

Step 7: Test the Blueprint

Open the chat for your blueprint and try a simple task.

Example prompts:

  • "Create a Cloudflare sandbox, write a Python script that prints the current working directory, run it, then delete the sandbox."
  • "Create a sandbox, write a file called hello.txt, read it back, and clean up."
  • "Create a sandbox and run python3 --version and node --version."

What you should see in the trace of actions:

  1. cloudflare/sandbox/create
  2. cloudflare/sandbox/command/create or file abilities
  3. Optional cloudflare/sandbox/running/fetch
  4. cloudflare/sandbox/delete

Step 8: Try a More Complete Workflow

Once the basic path works, test a multi-step task that proves the sandbox is reusable.

Example prompt:

This exercises the full path:

  1. Create sandbox
  2. Write file
  3. Execute command
  4. Return result
  5. Destroy sandbox

Example Architecture

The resulting setup looks like this:

This separation is useful because ChatBotKit handles reasoning and orchestration, while Cloudflare handles containerized execution in your own infrastructure boundary.

Troubleshooting

The bot says it cannot authenticate to the bridge

  • Verify the blueprint uses the cloudflare[key] secret, not a generic bearer secret
  • Confirm the stored secret value matches the Worker's SANDBOX_API_KEY
  • Make sure the bridge URL is correct and does not include a trailing slash in places where you want the base origin only

The health check works but command execution fails

  • Confirm the Worker deployed successfully with its container image
  • Wait a few minutes after first deployment for the container to provision
  • Check Cloudflare logs for bridge or container startup errors

The bot creates multiple sandboxes unnecessarily

  • Tighten the backstory so it explicitly says to reuse the current sandboxId during a task
  • Remind the bot to destroy the sandbox only after the task is complete

File operations fail

  • Use paths under /workspace
  • When writing through the ability, provide the file path relative to the workspace as instructed by the template
  • Test the same file path manually against the bridge with curl if needed

The sandbox is too minimal for your workload

  • Customize the bridge Dockerfile to install the runtimes, CLIs, or system packages your agent needs
  • Redeploy the Worker after updating the image

Next Steps

cloudflaresandboxskillsabilitiesblueprintagentic