examples
Verwenden Sie, wenn Sie im Verzeichnis examples/ arbeiten, ein Beispiel mit wrangler dev ausführen, ein neues Beispiel hinzufügen oder Fragen zu EXPOSE-Direktiven und den… beantworten.
npx skills add https://github.com/cloudflare/sandbox-sdk --skill examplesExamples
The examples/ directory contains working sample apps that exercise the SDK end-to-end. They double as integration smoke tests and as reference material for users.
Running an Example
From inside an example directory (e.g. examples/minimal/):
npm run dev # Start wrangler dev (builds Docker on first run)
The first run builds the container image, so it's slow. Subsequent runs reuse the image unless the SDK or Dockerfile changes. If you've changed the container runtime or SDK, run npm run docker:rebuild from the repo root before npm run dev.
Available Examples
| Example | Demonstrates |
|---|---|
minimal | Smallest possible Sandbox SDK setup |
authentication | Auth-protected sandbox access |
claude-code | Running Claude Code inside a sandbox |
code-interpreter | CodeInterpreter API + Workers AI |
codex / codex-app-server | OpenAI Codex integration patterns |
collaborative-terminal | Multi-user terminal sharing |
openai-agents | OpenAI Agents SDK + Sandbox |
opencode | OpenCode integration |
time-machine | Snapshot/restore patterns |
typescript-validator | Running tsc against user code |
vite-sandbox | Vite dev server proxied through preview URLs |
websocket-tunnel | WebSocket transport / port exposure |
alpine | Alpine-based container variant |
EXPOSE Directives
The Cloudflare containers primitive does not require EXPOSE directives — all ports are accessible in both local dev and production without them.
Including EXPOSE is still recommended in example Dockerfiles because it documents which ports the app uses (standard Docker convention). Don't add it expecting it to gate access; add it as documentation.
Adding a New Example
- Copy
examples/minimal/as a starting point. - Update
package.jsonnameand any wrangler config (wrangler.jsonc) — class names, DO bindings, container image tag. - Add a
README.mdwith an# H1title (the README scanner uses it) and a short description of what the example demonstrates. - Make sure the example builds and
npm run devworks from a clean checkout. - If the example demonstrates a new SDK capability, link to it from
packages/sandbox/README.md.
Local Development Tips
- Examples link to
@cloudflare/sandboxvia the workspace, so SDK changes are picked up after a build (npm run buildfrom repo root). - Container changes require
npm run docker:rebuildto take effect. - If you hit stale-image issues, delete the container image (
docker images | grep sandbox) and re-runnpm run dev.