1# API Reference
2 
3## Command Execution
4 
5```typescript
6// Basic
7const result = await sandbox.exec('python3 script.py');
8// Returns: { stdout, stderr, exitCode, success, duration }
9 
10// With options
11await sandbox.exec('python3 test.py', {
12  cwd: '/workspace/project',
13  env: { API_KEY: 'secret' },
14  stream: true,
15  onOutput: (stream, data) => console.log(data)
16});
17```
18 
19## File Operations
20 
21```typescript
22// Read/Write
23const { content } = await sandbox.readFile('/workspace/data.txt');
24await sandbox.writeFile('/workspace/file.txt', 'content');  // Auto-creates dirs
25 
26// List/Delete
27const files = await sandbox.listFiles('/workspace');
28await sandbox.deleteFile('/workspace/temp.txt');
29await sandbox.deleteFile('/workspace/dir', { recursive: true });
30 
31// Utils
32await sandbox.mkdir('/workspace/dir', { recursive: true });
33await sandbox.pathExists('/workspace/file.txt');
34```
35 
36## Background Processes
37 
38```typescript
39// Start
40const process = await sandbox.startProcess('python3 -m http.server 8080', {
41  processId: 'web-server',
42  cwd: '/workspace/public',
43  env: { PORT: '8080' }
44});
45// Returns: { id, pid, command }
46 
47// Wait for readiness
48await process.waitForPort(8080);  // Wait for port to listen
49await process.waitForLog(/Server running/);  // Wait for log pattern
50await process.waitForExit();  // Wait for completion
51 
52// Management
53const processes = await sandbox.listProcesses();
54const info = await sandbox.getProcess('web-server');
55await sandbox.stopProcess('web-server');
56const logs = await sandbox.getProcessLogs('web-server');
57```
58 
59## Port Exposure
60 
61```typescript
62// Expose port
63const { url } = await sandbox.exposePort(8080, {
64  name: 'web-app',
65  hostname: request.hostname
66});
67 
68// Management
69await sandbox.isPortExposed(8080);
70await sandbox.getExposedPorts(request.hostname);
71await sandbox.unexposePort(8080);
72```
73 
74## Sessions (Isolated Contexts)
75 
76Each session maintains own shell state, env vars, cwd, process namespace.
77 
78```typescript
79// Create with context
80const session = await sandbox.createSession({
81  id: 'user-123',
82  cwd: '/workspace/user123',
83  env: { USER_ID: '123' }
84});
85 
86// Use (full sandbox API)
87await session.exec('echo $USER_ID');
88await session.writeFile('config.txt', 'data');
89 
90// Manage
91await sandbox.getSession('user-123');
92await sandbox.deleteSession('user-123');
93```
94 
95## Code Interpreter
96 
97```typescript
98// Create context with variables
99const ctx = await sandbox.createCodeContext({
100  language: 'python',
101  variables: {
102    data: [1, 2, 3, 4, 5],
103    config: { verbose: true }
104  }
105});
106 
107// Execute code with rich outputs
108const result = await sandbox.runCode(`
109import matplotlib.pyplot as plt
110plt.plot(data, [x**2 for x in data])
111plt.savefig('plot.png')
112print(f"Processed {len(data)} points")
113`, { context: ctx });
114// Returns: ExecutionResult { code, logs, results: RichOutput[], error, executionCount }
115 
116// Context persists variables across runs
117const result2 = await sandbox.runCode('print(data[0])', { context: ctx });  // Still has 'data'
118```
119 
120## WebSocket Connections
121 
122```typescript
123// Proxy WebSocket to sandbox service
124export default {
125  async fetch(request: Request, env: Env): Promise<Response> {
126    const proxyResponse = await proxyToSandbox(request, env);
127    if (proxyResponse) return proxyResponse;
128 
129    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
130      const sandbox = getSandbox(env.Sandbox, 'realtime');
131      return await sandbox.wsConnect(request, 8080);
132    }
133    
134    return new Response('Not a WebSocket request', { status: 400 });
135  }
136};
137```
138 
139## Bucket Mounting (S3 Storage)
140 
141```typescript
142// Mount R2 bucket (production only, not wrangler dev)
143await sandbox.mountBucket(env.DATA_BUCKET, '/data', {
144  readOnly: false
145});
146 
147// Access files in mounted bucket
148await sandbox.exec('ls /data');
149await sandbox.writeFile('/data/output.txt', 'result');
150 
151// Unmount
152await sandbox.unmountBucket('/data');
153```
154 
155**Note**: Bucket mounting only works in production. Mounted buckets are sandbox-scoped (visible to all sessions in that sandbox).
156 
157## Lifecycle Management
158 
159```typescript
160// Terminate container immediately
161await sandbox.destroy();
162 
163// REQUIRED when using keepAlive: true
164const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });
165try {
166  await sandbox.writeFile('/tmp/code.py', code);
167  const result = await sandbox.exec('python /tmp/code.py');
168  return result.stdout;
169} finally {
170  await sandbox.destroy();  // Free resources
171}
172```
173 
174Deletes: files, processes, sessions, network connections, exposed ports.
175 
176## Error Handling
177 
178```typescript
179// Command errors
180const result = await sandbox.exec('python3 invalid.py');
181if (!result.success) {
182  console.error('Exit code:', result.exitCode);
183  console.error('Stderr:', result.stderr);
184}
185 
186// SDK errors
187try {
188  await sandbox.readFile('/nonexistent');
189} catch (error) {
190  if (error.code === 'FILE_NOT_FOUND') { /* ... */ }
191  else if (error.code === 'CONTAINER_NOT_READY') { /* retry */ }
192  else if (error.code === 'TIMEOUT') { /* ... */ }
193}
194 
195// Retry pattern (see gotchas.md for full implementation)
196```
197 
198 
199