cloudflare-sandbox

Name: cloudflare-sandbox
Author: jackspace

15stars7forks

How to install cloudflare-sandbox?

jackspace/claudeskillz/cloudflare-sandbox

$npx -y skills add jackspace/ClaudeSkillz --skill cloudflare-sandbox

Installs into the current project.

Summary

This skill provides comprehensive knowledge for building applications with Cloudflare Sandboxes SDK, which enables secure, isolated code execution in full Linux containers at the edge. It should be used when executing untrusted code, running Python/Node.js scripts, performing git

Files · 1

View on GitHub

SKILL.md

1	# Cloudflare Sandboxes SDK
2
3	Status: Production Ready (Open Beta)
4	Last Updated: 2025-10-29
5	Dependencies: `cloudflare-worker-base`, `cloudflare-durable-objects` (recommended for understanding)
6	Latest Versions: `@cloudflare/sandbox@0.4.12`, Docker image: `cloudflare/sandbox:0.4.12`
7
8	---
9
10	## Quick Start (15 Minutes)
11
12	### 1. Install SDK and Setup Wrangler
13
14	```bash
15	npm install @cloudflare/sandbox@latest
16	```
17
18	wrangler.jsonc:
19	```jsonc
20	{
21	"name": "my-sandbox-worker",
22	"main": "src/index.ts",
23	"compatibility_flags": ["nodejs_compat"],
24	"containers": [{
25	"class_name": "Sandbox",
26	"image": "cloudflare/sandbox:0.4.12",
27	"instance_type": "lite"
28	}],
29	"durable_objects": {
30	"bindings": [{
31	"class_name": "Sandbox",
32	"name": "Sandbox"
33	}]
34	},
35	"migrations": [{
36	"tag": "v1",
37	"new_sqlite_classes": ["Sandbox"]
38	}]
39	}
40	```
41
42	Why this matters:
43	- `nodejs_compat` enables Node.js APIs required by SDK
44	- `containers` defines the Ubuntu container image
45	- `durable_objects` binding enables persistent routing
46	- `migrations` registers the Sandbox class
47
48	### 2. Create Your First Sandbox Worker
49
50	```typescript
51	import { getSandbox, type Sandbox } from '@cloudflare/sandbox';
52	export { Sandbox } from '@cloudflare/sandbox';
53
54	type Env = {
55	Sandbox: DurableObjectNamespace<Sandbox>;
56	};
57
58	export default {
59	async fetch(request: Request, env: Env): Promise<Response> {
60	// Get sandbox instance (creates if doesn't exist)
61	const sandbox = getSandbox(env.Sandbox, 'my-first-sandbox');
62
63	// Execute Python code
64	const result = await sandbox.exec('python3 -c "print(2 + 2)"');
65
66	return Response.json({
67	output: result.stdout,
68	success: result.success,
69	exitCode: result.exitCode
70	});
71	}
72	};
73	```
74
75	CRITICAL:
76	- MUST export `{ Sandbox }` from `@cloudflare/sandbox` in your Worker
77	- Sandbox ID determines routing (same ID = same container)
78	- First request creates container (~2-3 min cold start)
79	- Subsequent requests are fast (<1s)
80
81	### 3. Deploy and Test
82
83	```bash
84	npm run deploy
85	curl https://your-worker.workers.dev
86	```
87
88	Expected output:
89	```json
90	{
91	"output": "4\n",
92	"success": true,
93	"exitCode": 0
94	}
95	```
96
97	---
98
99	## Architecture (Understanding the 3-Layer Model)
100
101	### How Sandboxes Work
102
103	```
104	┌─────────────────────────────────────────┐
105	│ Your Worker (Layer 1) │
106	│ - Handles HTTP requests │
107	│ - Calls getSandbox() │
108	│ - Uses sandbox.exec(), writeFile(), etc│
109	└──────────────┬──────────────────────────┘
110	│ RPC via Durable Object
111	┌──────────────▼──────────────────────────┐
112	│ Durable Object (Layer 2) │
113	│ - Routes by sandbox ID │
114	│ - Maintains persistent identity │
115	│ - Geographic stickiness │
116	└──────────────┬──────────────────────────┘
117	│ Container API
118	┌──────────────▼──────────────────────────┐
119	│ Ubuntu Container (Layer 3) │
120	│ - Full Linux environment │
121	│ - Python 3.11, Node 20, Git, etc. │
122	│ - Filesystem: /workspace, /tmp, /home │
123	│ - Process isolation (VM-based) │
124	└─────────────────────────────────────────┘
125	```
126
127	Key Insight: Workers handle API logic (fast), Durable Objects route requests (persistent identity), Containers execute code (full capabilities).
128
129	---
130
131	## Critical Container Lifecycle (Most Important Section!)
132
133	### Container States
134
135	```
136	┌─────────┐ First request ┌────────┐ ~10 min idle ┌──────┐
137	│ Not │ ───────────────>│ Active │ ─────────────> │ Idle │
138	│ Created │ │ │ │ │
139	└─────────┘ └───┬────┘

People who liked this also viewed

6 picks

Type

cloudflare-sandbox

15stars7forks

View on GitHub

How to install cloudflare-sandbox?

jackspace/claudeskillz/cloudflare-sandbox

$npx -y skills add jackspace/ClaudeSkillz --skill cloudflare-sandbox

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cloudflare Sandboxes SDK
2
3	Status: Production Ready (Open Beta)
4	Last Updated: 2025-10-29
5	Dependencies: `cloudflare-worker-base`, `cloudflare-durable-objects` (recommended for understanding)
6	Latest Versions: `@cloudflare/sandbox@0.4.12`, Docker image: `cloudflare/sandbox:0.4.12`
7
8	---
9
10	## Quick Start (15 Minutes)
11
12	### 1. Install SDK and Setup Wrangler
13
14	```bash
15	npm install @cloudflare/sandbox@latest
16	```
17
18	wrangler.jsonc:
19	```jsonc
20	{
21	"name": "my-sandbox-worker",
22	"main": "src/index.ts",
23	"compatibility_flags": ["nodejs_compat"],
24	"containers": [{
25	"class_name": "Sandbox",
26	"image": "cloudflare/sandbox:0.4.12",
27	"instance_type": "lite"
28	}],
29	"durable_objects": {
30	"bindings": [{
31	"class_name": "Sandbox",
32	"name": "Sandbox"
33	}]
34	},
35	"migrations": [{
36	"tag": "v1",
37	"new_sqlite_classes": ["Sandbox"]
38	}]
39	}
40	```
41
42	Why this matters:
43	- `nodejs_compat` enables Node.js APIs required by SDK
44	- `containers` defines the Ubuntu container image
45	- `durable_objects` binding enables persistent routing
46	- `migrations` registers the Sandbox class
47
48	### 2. Create Your First Sandbox Worker
49
50	```typescript
51	import { getSandbox, type Sandbox } from '@cloudflare/sandbox';
52	export { Sandbox } from '@cloudflare/sandbox';
53
54	type Env = {
55	Sandbox: DurableObjectNamespace<Sandbox>;
56	};
57
58	export default {
59	async fetch(request: Request, env: Env): Promise<Response> {
60	// Get sandbox instance (creates if doesn't exist)
61	const sandbox = getSandbox(env.Sandbox, 'my-first-sandbox');
62
63	// Execute Python code
64	const result = await sandbox.exec('python3 -c "print(2 + 2)"');
65
66	return Response.json({
67	output: result.stdout,
68	success: result.success,
69	exitCode: result.exitCode
70	});
71	}
72	};
73	```
74
75	CRITICAL:
76	- MUST export `{ Sandbox }` from `@cloudflare/sandbox` in your Worker
77	- Sandbox ID determines routing (same ID = same container)
78	- First request creates container (~2-3 min cold start)
79	- Subsequent requests are fast (<1s)
80
81	### 3. Deploy and Test
82
83	```bash
84	npm run deploy
85	curl https://your-worker.workers.dev
86	```
87
88	Expected output:
89	```json
90	{
91	"output": "4\n",
92	"success": true,
93	"exitCode": 0
94	}
95	```
96
97	---
98
99	## Architecture (Understanding the 3-Layer Model)
100
101	### How Sandboxes Work
102
103	```
104	┌─────────────────────────────────────────┐
105	│ Your Worker (Layer 1) │
106	│ - Handles HTTP requests │
107	│ - Calls getSandbox() │
108	│ - Uses sandbox.exec(), writeFile(), etc│
109	└──────────────┬──────────────────────────┘
110	│ RPC via Durable Object
111	┌──────────────▼──────────────────────────┐
112	│ Durable Object (Layer 2) │
113	│ - Routes by sandbox ID │
114	│ - Maintains persistent identity │
115	│ - Geographic stickiness │
116	└──────────────┬──────────────────────────┘
117	│ Container API
118	┌──────────────▼──────────────────────────┐
119	│ Ubuntu Container (Layer 3) │
120	│ - Full Linux environment │
121	│ - Python 3.11, Node 20, Git, etc. │
122	│ - Filesystem: /workspace, /tmp, /home │
123	│ - Process isolation (VM-based) │
124	└─────────────────────────────────────────┘
125	```
126
127	Key Insight: Workers handle API logic (fast), Durable Objects route requests (persistent identity), Containers execute code (full capabilities).
128
129	---
130
131	## Critical Container Lifecycle (Most Important Section!)
132
133	### Container States
134
135	```
136	┌─────────┐ First request ┌────────┐ ~10 min idle ┌──────┐
137	│ Not │ ───────────────>│ Active │ ─────────────> │ Idle │
138	│ Created │ │ │ │ │
139	└─────────┘ └───┬────┘

People who liked this also viewed

6 picks

Type