How It Works
The Cloudflare Sandbox SDK enables developers to create isolated execution environments for untrusted code directly on Cloudflare’s edge network using Workers. Each sandbox operates within its own container, ensuring that processes, file systems, and network services remain segregated from the host or other sandboxes.
The SDK integrates with Workers to provide a programmable interface for executing commands, managing files, and exposing services. Developers interact with the sandbox through a TypeScript API, which allows for fine-grained control over container lifecycle, resource allocation, and network exposure. For example, a Worker can instantiate a sandbox, execute Python or JavaScript code, read or write files, and even expose internal services via temporary public URLs.
When a sandbox is created, it initializes a Docker-based container on Cloudflare’s edge network. These labels are applied during container startup and persist until the next restart.
For network exposure, the SDK provides a feature called quick tunnels, which generates public .trycloudflare.com URLs for services running inside the sandbox. These URLs are created dynamically using cloudflared, a Cloudflare tool that establishes a persistent QUIC connection to the edge. The SDK caches tunnel records in Durable Object storage, ensuring that repeated requests for the same port return the same URL until the container restarts.
This is particularly useful for interactive development environments or CI/CD pipelines where reproducibility is critical.
Each sandbox runs in a dedicated container with restricted permissions, and file system operations are scoped to a workspace directory. Command execution is isolated, with output streamed back to the caller.
Use Cases
The Cloudflare Sandbox SDK is designed for applications requiring secure, isolated code execution at the edge. One primary use case is AI code execution, where untrusted user-provided code—such as Python scripts or JavaScript snippets—must run without risking the host environment. For instance, an AI agent hosted on Workers can use the SDK to execute user commands in a sandbox, returning results while keeping the agent’s core logic isolated.
Interactive development environments benefit from the SDK’s file system and process control capabilities.
Data analysis platforms can leverage the SDK to process sensitive or untrusted datasets without exposing the underlying infrastructure. The edge-native execution ensures low latency for global users, while isolation prevents data leakage or contamination.
CI/CD systems can integrate the SDK to run build steps or tests in isolated containers.
Another use case is exposing internal services temporarily for testing or collaboration. Quick tunnels allow developers to share a service running in a sandbox via a .trycloudflare.com URL without requiring DNS configuration or Cloudflare account access. This is useful for ad-hoc debugging sessions, demo environments, or internal tooling that needs to be accessible to specific stakeholders.
This enables secure, multi-user environments where each session operates in isolation.
Key Features & Capabilities
- Secure Isolation: Each sandbox runs in a dedicated container with its own file system, process space, and network namespace. Containers are ephemeral by default, and resource usage is constrained to prevent abuse.
- Edge-Native Execution: Sandboxes execute on Cloudflare’s global network, ensuring low latency for users worldwide. The proximity to end users reduces the need for data transfer to centralized servers, improving performance for interactive workloads.
- Command and File System Management: The SDK provides APIs for executing arbitrary commands with streaming output, reading and writing files, and managing directories.
- Service Exposure via Quick Tunnels: Developers can expose services running inside a sandbox to the public internet using .trycloudflare.com URLs. These tunnels are created dynamically and persist until the container restarts. The SDK caches tunnel records to avoid redundant cloudflared processes, and URLs support WebSockets and text/event-stream responses for real-time applications.
- This is useful for CI/CD pipelines or collaborative development environments where reproducibility is key.
- This feature is particularly valuable for long-running processes or environments where consistency is critical.
- Labels can be applied to containers for observability, such as tracking tenant IDs or workload types. These labels are updated during container startup and do not affect running instances until the next restart.
- API-Driven Development: The SDK is built for TypeScript and integrates seamlessly with Workers. Developers use the getSandbox function to instantiate a sandbox, passing options like labels or sleep timers. Example APIs include exec for command execution, readFile/writeFile for file operations, and tunnels.get for service exposure.
- Beta Status and Active Development: The SDK is currently in beta, with APIs subject to change before reaching version 1.0. Contributions from the community are welcome, with guidelines provided in the repository’s CONTRIBUTING.md file.
The SDK’s design prioritizes security, performance, and flexibility, making it suitable for a wide range of edge-computing workloads where isolation and low latency are critical.