1# Common Patterns
2 
3## AI Code Execution with Code Context
4 
5```typescript
6export default {
7  async fetch(request: Request, env: Env): Promise<Response> {
8    const { code, variables } = await request.json();
9    const sandbox = getSandbox(env.Sandbox, 'ai-agent');
10    
11    // Create context with persistent variables
12    const ctx = await sandbox.createCodeContext({
13      language: 'python',
14      variables: variables || {}
15    });
16    
17    // Execute with rich outputs (text, images, HTML)
18    const result = await sandbox.runCode(code, { context: ctx });
19    
20    return Response.json({
21      results: result.results,  // RichOutput[] (text, html, png, json, etc.)
22      error: result.error,
23      success: !result.error
24    });
25  }
26};
27```
28 
29## Interactive Dev Environment
30 
31```typescript
32export default {
33  async fetch(request: Request, env: Env): Promise<Response> {
34    const proxyResponse = await proxyToSandbox(request, env);
35    if (proxyResponse) return proxyResponse;
36    
37    const sandbox = getSandbox(env.Sandbox, 'ide', { normalizeId: true });
38    
39    if (request.url.endsWith('/start')) {
40      await sandbox.exec('curl -fsSL https://code-server.dev/install.sh | sh');
41      await sandbox.startProcess('code-server --bind-addr 0.0.0.0:8080', {
42        processId: 'vscode'
43      });
44      
45      const exposed = await sandbox.exposePort(8080);
46      return Response.json({ url: exposed.url });
47    }
48    
49    return new Response('Try /start');
50  }
51};
52```
53 
54## WebSocket Real-Time Service
55 
56```typescript
57export default {
58  async fetch(request: Request, env: Env): Promise<Response> {
59    const proxyResponse = await proxyToSandbox(request, env);
60    if (proxyResponse) return proxyResponse;
61 
62    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
63      const sandbox = getSandbox(env.Sandbox, 'realtime-service');
64      return await sandbox.wsConnect(request, 8080);
65    }
66 
67    // Non-WebSocket: expose preview URL
68    const sandbox = getSandbox(env.Sandbox, 'realtime-service');
69    const { url } = await sandbox.exposePort(8080, {
70      hostname: new URL(request.url).hostname
71    });
72    return Response.json({ wsUrl: url.replace('https', 'wss') });
73  }
74};
75```
76 
77**Dockerfile**:
78```dockerfile
79FROM docker.io/cloudflare/sandbox:0.7.0
80RUN npm install -g ws
81EXPOSE 8080
82```
83 
84## Process Readiness Pattern
85 
86```typescript
87export default {
88  async fetch(request: Request, env: Env): Promise<Response> {
89    const sandbox = getSandbox(env.Sandbox, 'app-server');
90    
91    // Start server
92    const process = await sandbox.startProcess(
93      'node server.js',
94      { processId: 'server' }
95    );
96    
97    // Wait for server to be ready
98    await process.waitForPort(8080);  // Wait for port listening
99    
100    // Now safe to expose
101    const { url } = await sandbox.exposePort(8080);
102    return Response.json({ url });
103  }
104};
105```
106 
107## Persistent Data with Bucket Mounting
108 
109```typescript
110export default {
111  async fetch(request: Request, env: Env): Promise<Response> {
112    const sandbox = getSandbox(env.Sandbox, 'data-processor');
113    
114    // Mount R2 bucket (production only)
115    await sandbox.mountBucket(env.DATA_BUCKET, '/data', {
116      readOnly: false
117    });
118    
119    // Process files in bucket
120    const result = await sandbox.exec('python3 /workspace/process.py', {
121      env: { DATA_DIR: '/data/input' }
122    });
123    
124    // Results written to /data/output are persisted in R2
125    return Response.json({ success: result.success });
126  }
127};
128```
129 
130## CI/CD Pipeline
131 
132```typescript
133export default {
134  async fetch(request: Request, env: Env): Promise<Response> {
135    const { repo, branch } = await request.json();
136    const sandbox = getSandbox(env.Sandbox, `ci-${repo}-${Date.now()}`);
137    
138    await sandbox.exec(`git clone -b ${branch} ${repo} /workspace/repo`);
139    
140    const install = await sandbox.exec('npm install', {
141      cwd: '/workspace/repo',
142      stream: true,
143      onOutput: (stream, data) => console.log(data)
144    });
145    
146    if (!install.success) {
147      return Response.json({ success: false, error: 'Install failed' });
148    }
149    
150    const test = await sandbox.exec('npm test', { cwd: '/workspace/repo' });
151    
152    return Response.json({
153      success: test.success,
154      output: test.stdout,
155      exitCode: test.exitCode
156    });
157  }
158};
159```
160 
161 
162 
163 
164 
165## Multi-Tenant Pattern
166 
167```typescript
168export default {
169  async fetch(request: Request, env: Env): Promise<Response> {
170    const userId = request.headers.get('X-User-ID');
171    const sandbox = getSandbox(env.Sandbox, 'multi-tenant');
172    
173    // Each user gets isolated session
174    let session;
175    try {
176      session = await sandbox.getSession(userId);
177    } catch {
178      session = await sandbox.createSession({
179        id: userId,
180        cwd: `/workspace/users/${userId}`,
181        env: { USER_ID: userId }
182      });
183    }
184    
185    const code = await request.text();
186    const result = await session.exec(`python3 -c "${code}"`);
187    
188    return Response.json({ output: result.stdout });
189  }
190};
191```
192 
193## Git Operations
194 
195```typescript
196// Clone repo
197await sandbox.exec('git clone https://github.com/user/repo.git /workspace/repo');
198 
199// Authenticated (use env secrets)
200await sandbox.exec(`git clone https://${env.GITHUB_TOKEN}@github.com/user/repo.git`);
201```
202