examples

Name: examples
Author: cloudflare/sandbox-sdk

$npx mdskill add cloudflare/sandbox-sdk/examples

Manages examples directory and Docker dev workflows for SDK projects

Runs and tests SDK examples using wrangler dev and Docker
Relies on Docker, Wrangler CLI, and project SDK components
Analyzes example requirements and Dockerfile configurations
Provides build instructions and runtime guidance for developers

SKILL.md

.github/skills/examplesView on GitHub ↗

---
name: examples
description: Use when working in the examples/ directory, running an example with wrangler dev, adding a new example, or answering questions about EXPOSE directives and the local Docker dev loop. (project)
---

# Examples

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/`):

```bash
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

1. Copy `examples/minimal/` as a starting point.
2. Update `package.json` `name` and any wrangler config (`wrangler.jsonc`) — class names, DO bindings, container image tag.
3. Add a `README.md` with an `# H1` title (the README scanner uses it) and a short description of what the example demonstrates.
4. Make sure the example builds and `npm run dev` works from a clean checkout.
5. If the example demonstrates a new SDK capability, link to it from `packages/sandbox/README.md`.

## Local Development Tips

- Examples link to `@cloudflare/sandbox` via the workspace, so SDK changes are picked up after a build (`npm run build` from repo root).
- Container changes require `npm run docker:rebuild` to take effect.
- If you hit stale-image issues, delete the container image (`docker images | grep sandbox`) and re-run `npm run dev`.

More from cloudflare/sandbox-sdk

Skill	Description
architecture	Use when navigating the codebase for the first time, adding a new client method, adding a new container handler/service, or understanding how a request flows from Worker through the Sandbox DO into the container. Covers the three-layer architecture, client pattern, container runtime structure, and monorepo layout. (project)
changesets	Use when creating a changeset, preparing a release, or bumping versions. Covers which packages to reference, how to write user-facing changeset descriptions, the release automation flow, and the npm/Docker version sync requirement. (project)
coding-standards	Use when writing or reviewing TypeScript in this repo. Covers the no-`any` rule and where to put new types, the uppercase-acronym style guide, and the rules for code comments (no historical context). (project)
git-commit	Use when creating git commits to ensure commit messages follow project standards. Applies the 7 rules for great commit messages with focus on conciseness and imperative mood.
logging	Use when adding logs, debugging, or working with the Logger across the SDK and container runtime. Covers the constructor-injection pattern, child loggers, env-var configuration, and test mocking. (project)
sandbox-bridge	Use when you need to exercise a real, running Sandbox deployment via HTTP — for example to validate SDK changes against a live container, reproduce a user-reported issue, or experiment with the API (including FUSE bucket mounts) without spinning up `wrangler dev`. Documents the Sandbox bridge worker reachable via `SANDBOX_WORKER_URL` + `SANDBOX_API_KEY` when the host injects them.
session-execution	Use when working on or reviewing session execution, command handling, shell state, FIFO-based streaming, or stdout/stderr separation. Relevant for session.ts, command handlers, exec/execStream, or anything involving shell process management. (project)
testing	Use when writing or running tests for this project. Covers unit vs E2E test decisions, test file locations, mock patterns, and project-specific testing conventions. (project)