# sandbox-workers

> Deploy isolated JavaScript, Python, Perl, and Ruby runtimes to Cloudflare Workers and call them through Service Bindings.

## Docs

- [Overview](/docs): Run a code interpreter on your own Cloudflare account in stateless or stateful mode, in the shape of the Sandbox SDK 1.0 preview.
- [Deploy a runtime Worker](/docs/deploy): Create a runtime Worker in your account from an isolated source template, or initialize one with the CLI.

## Stateless mode

- [Stateless mode](/docs/stateless): Call a runtime Worker's Service Binding directly with the free runCode function — no sandbox, no code context, no files.
- [Get started with stateless mode](/docs/stateless/get-started): Deploy a runtime Worker and call it directly with the free runCode function — no sandbox, no code context, no files.
- [Execute code](/docs/stateless/execute-code): Run code in stateless mode with the free runCode function and handle results and errors.

## Stateful mode

- [Stateful mode](/docs/stateful): Host a Sandbox Durable Object in your own Worker for code contexts, a shared workspace, and state that persists between calls.
- [Get started with stateful mode](/docs/stateful/get-started): Deploy a runtime Worker, host a Sandbox Durable Object in your own Worker, and run your first code context.
- [Use code contexts](/docs/stateful/code-contexts): Keep state between executions with a durable, stateful REPL bound to a runtime Worker.
- [Manage files](/docs/stateful/manage-files): Read, write, and organize files under /workspace with the typed client and from guest code.

## API reference

- [API reference](/docs/api): Method signatures, types, and the raw HTTP contract for @sandbox-workers/core.
- [Lifecycle](/docs/api/lifecycle): Get a sandbox client, inspect its state, and destroy it.
- [Code interpreter](/docs/api/interpreter): Create code contexts bound to a runtime Worker and run code with the typed client.
- [Files](/docs/api/files): Read, write, and manage files in a sandbox's shared workspace.
- [Errors](/docs/api/errors): The SandboxError hierarchy, the ErrorResponse shape, and the error code table.
- [HTTP API](/docs/api/http-api): The raw JSON contract behind the typed client — the runtime Worker's routes, the sandbox's wire protocol, and the gateway paths.

## Concepts

- [Concepts](/docs/concepts): How sandbox-workers is structured, why it's designed this way, and what you need to understand to use it safely.
- [Architecture](/docs/concepts/architecture): The caller-hosted Sandbox Durable Object, per-runtime Interpreter Durable Objects, and the workspace mirror between them.
- [Sandbox lifecycle](/docs/concepts/sandboxes): How sandboxes are created, what persists, the two idle timers, and destruction.
- [Code contexts](/docs/concepts/code-contexts): Durable REPLs bound to a runtime Worker, the shared workspace mirror, and the memory-snapshot mechanism that keeps them alive.
- [Runtime engines](/docs/concepts/runtimes): How each language's Wasm engine is instrumented, capped, and isolated.
- [Security model](/docs/concepts/security): Isolation guarantees, denied capabilities, and what a public caller must still implement.

## Configuration

- [Configuration](/docs/configuration): Configure your own Worker's wrangler.jsonc for stateless or stateful mode, the runtime Worker's wrangler.jsonc, and guest environment variables.
- [Wrangler configuration](/docs/configuration/wrangler): Your Sandbox Durable Object binding and its migration, the runtime Service Bindings, and the runtime Worker's own configuration.
- [Bindings](/docs/configuration/bindings): Runtime Service Bindings for stateless mode, and the Sandbox Durable Object binding plus binding-name rules for stateful mode.
- [Environment variables](/docs/configuration/environment-variables): Guest envVars per call and per context, setEnvVars layering, per-language access, and the SANDBOX_IDLE_TTL_MS / INTERPRETER_IDLE_TTL_MS settings.

## Runtimes

- [JavaScript](/docs/runtimes/javascript): Execute code with SpiderMonkey 147 (goccy/spidermonkey-wasm v0.2.6) inside a dedicated Wasm Worker.
- [Python](/docs/runtimes/python): Execute code with CPython 3.14.6 inside a dedicated Wasm Worker.
- [Perl](/docs/runtimes/perl): Execute code with Perl 5.42.2 inside a dedicated Wasm Worker.
- [Ruby](/docs/runtimes/ruby): Execute code with CRuby 4.0.0 inside a dedicated Wasm Worker.

## Platform

- [Platform](/docs/platform): Engine limits, runtime licenses, and troubleshooting for sandbox-workers.
- [Limits](/docs/platform/limits): Engine budgets, request and workspace limits, and the PHP evaluation.
- [Runtime licenses](/docs/platform/licenses): Review each runtime license before use or redistribution.
- [Troubleshooting](/docs/platform/troubleshooting): Diagnose deployment, binding, and execution failures.

## Agent resources

- [llms-full.txt](/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [agent-readability.json](/agent-readability.json): Manifest of every agent-facing artifact on this site.