skills.rest
cloudflare
cloudflareOFFICIAL
Explore all skills by this author →
WebsiteGitHub

sandbox-bridge

Drive a live Cloudflare Sandbox deployment over HTTP to execute commands, manage files, and test SDK behavior.

1.1k|114|Updated Jun 22, 2025
Search Tags:#code execution#cloudflare#workers#Testing#SSE#HTTP API#Sandbox
One-click install
npx skills add https://github.com/cloudflare/sandbox-sdk --skill sandbox-bridge
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sandbox-bridge
Source: https://github.com/cloudflare/sandbox-sdk/tree/main/.agents/skills/sandbox-bridge
Command: npx skills add https://github.com/cloudflare/sandbox-sdk --skill sandbox-bridge

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Validating SDK changes or reproducing issues against a real Cloudflare Sandbox container normally requires deploying your own worker or running wrangler dev locally. This Skill lets you exercise a hosted Sandbox deployment directly over HTTP using injected credentials, with no local Docker build or deployment step.

Core Features & Use Cases

  • Remote Sandbox Lifecycle: Create, use, and destroy isolated sandbox containers via the bridge API, identified by opaque IDs.
  • Command Execution via SSE: Run shell commands with streamed stdout/stderr as Server-Sent Events, with optional timeouts and working directories.
  • File and Session Management: Read and write files under /workspace, and create named sessions that persist working directory and environment variables across commands.
  • Use Case: Reproduce a user-reported bug by creating a sandbox, writing a failing script to /workspace, executing it in a session, and inspecting the streamed output — all without touching your local environment. It is also the only way to test FUSE-based bucket mounts, which wrangler dev cannot replicate.

Quick Start

Use the sandbox-bridge skill to create a sandbox on the bridge worker, run a test command inside it, and then destroy the sandbox.

Frequently Asked Questions about sandbox-bridge

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I execute a command in a Cloudflare Sandbox over HTTP?▼

Create a sandbox with POST /v1/sandbox to get an ID, then POST to /v1/sandbox/{id}/exec with an argv array such as ["sh","-lc","your command"]. Output streams back as Server-Sent Events with base64-encoded stdout and stderr chunks followed by an exit event.

How do I test Cloudflare Sandbox SDK changes without wrangler dev?▼

Use the sandbox bridge worker when the host injects SANDBOX_WORKER_URL and SANDBOX_API_KEY. It exposes the full @cloudflare/sandbox SDK over HTTP, so you can drive a real container with curl. Note the bridge runs the currently deployed SDK version, not your working tree.

When should I use the sandbox bridge instead of wrangler dev?▼

Use the bridge for quick behavioral checks against a real container and for FUSE-based bucket mounts, which wrangler dev cannot replicate. Use wrangler dev when iterating on the container image, worker code, or unreleased SDK changes that do not need FUSE.

How do I persist environment variables across sandbox commands?▼

Create a session with POST /v1/sandbox/{id}/session, optionally passing cwd and env. Then send the returned ID in the Session-Id header on exec and file requests; working directory and exported variables persist across commands in that session.

Why does the sandbox bridge return 401 unauthorized?▼

A 401 means the Authorization header is missing or the token is invalid. Every request needs Authorization: Bearer $SANDBOX_API_KEY, passed via the header rather than a query string. If SANDBOX_API_KEY is unset in your shell, the bridge is not available for that session.

Related Skills

Explore More Software Engineering Skills→
SignmanalSignmanal
1

cloudflare-temporary-deploy

Deploy Cloudflare Workers to live workers.dev endpoints without an account.

Community
Intermediate
openaiopenai
5.3k

sandbox-sdk

Build sandboxed code execution environments on Cloudflare Workers using the Sandbox SDK.

Official
Intermediate
dallaydallay

wrangler

Automate Wrangler CLI workflows for Cloudflare Workers deployments.

Official
Intermediate
verkyyiverkyyi
6

schedule-host-job

Schedule one-off or recurring container commands on the host via atd.

Community
Advanced