# API Reference

## Command Execution

```typescript
// Basic
const result = await sandbox.exec('python3 script.py')
// Returns: { stdout, stderr, exitCode, success, duration }

// With options
await sandbox.exec('python3 test.py', {
  cwd: '/workspace/project',
  env: { API_KEY: 'secret' },
  stream: true,
  onOutput: (stream, data) => console.log(data),
})
```

## File Operations

```typescript
// Read/Write
const { content } = await sandbox.readFile('/workspace/data.txt')
await sandbox.writeFile('/workspace/file.txt', 'content') // Auto-creates dirs

// List/Delete
const files = await sandbox.listFiles('/workspace')
await sandbox.deleteFile('/workspace/temp.txt')
await sandbox.deleteFile('/workspace/dir', { recursive: true })

// Utils
await sandbox.mkdir('/workspace/dir', { recursive: true })
await sandbox.pathExists('/workspace/file.txt')
```

## Background Processes

```typescript
// Start
const process = await sandbox.startProcess('python3 -m http.server 8080', {
  processId: 'web-server',
  cwd: '/workspace/public',
  env: { PORT: '8080' },
})
// Returns: { id, pid, command }

// Wait for readiness
await process.waitForPort(8080) // Wait for port to listen
await process.waitForLog(/Server running/) // Wait for log pattern
await process.waitForExit() // Wait for completion

// Management
const processes = await sandbox.listProcesses()
const info = await sandbox.getProcess('web-server')
await sandbox.stopProcess('web-server')
const logs = await sandbox.getProcessLogs('web-server')
```

## Port Exposure

```typescript
// Expose port
const { url } = await sandbox.exposePort(8080, {
  name: 'web-app',
  hostname: request.hostname,
})

// Management
await sandbox.isPortExposed(8080)
await sandbox.getExposedPorts(request.hostname)
await sandbox.unexposePort(8080)
```

## Sessions (Isolated Contexts)

Each session maintains own shell state, env vars, cwd, process namespace.

```typescript
// Create with context
const session = await sandbox.createSession({
  id: 'user-123',
  cwd: '/workspace/user123',
  env: { USER_ID: '123' },
})

// Use (full sandbox API)
await session.exec('echo $USER_ID')
await session.writeFile('config.txt', 'data')

// Manage
await sandbox.getSession('user-123')
await sandbox.deleteSession('user-123')
```

## Code Interpreter

```typescript
// Create context with variables
const ctx = await sandbox.createCodeContext({
  language: 'python',
  variables: {
    data: [1, 2, 3, 4, 5],
    config: { verbose: true },
  },
})

// Execute code with rich outputs
const result = await ctx.runCode(`
import matplotlib.pyplot as plt
plt.plot(data, [x**2 for x in data])
plt.savefig('plot.png')
print(f"Processed {len(data)} points")
`)
// Returns: { outputs: [{ type: 'text'|'image'|'html', content }], error }

// Context persists variables across runs
const result2 = await ctx.runCode('print(data[0])') // Still has 'data'
```

## WebSocket Connections

```typescript
// Proxy WebSocket to sandbox service
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const proxyResponse = await proxyToSandbox(request, env)
    if (proxyResponse) return proxyResponse

    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
      const sandbox = getSandbox(env.Sandbox, 'realtime')
      return await sandbox.wsConnect(request, 8080)
    }

    return new Response('Not a WebSocket request', { status: 400 })
  },
}
```

## Bucket Mounting (S3 Storage)

```typescript
// Mount R2 bucket (production only, not wrangler dev)
await sandbox.mountBucket(env.DATA_BUCKET, '/data', {
  readOnly: false,
})

// Access files in mounted bucket
await sandbox.exec('ls /data')
await sandbox.writeFile('/data/output.txt', 'result')

// Unmount
await sandbox.unmountBucket('/data')
```

**Note**: Bucket mounting only works in production. Mounted buckets are sandbox-scoped (visible to all sessions in that sandbox).

## Lifecycle Management

```typescript
// Terminate container immediately
await sandbox.destroy()

// REQUIRED when using keepAlive: true
const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true })
try {
  await sandbox.writeFile('/tmp/code.py', code)
  const result = await sandbox.exec('python /tmp/code.py')
  return result.stdout
} finally {
  await sandbox.destroy() // Free resources
}
```

Deletes: files, processes, sessions, network connections, exposed ports.

## Error Handling

```typescript
// Command errors
const result = await sandbox.exec('python3 invalid.py')
if (!result.success) {
  console.error('Exit code:', result.exitCode)
  console.error('Stderr:', result.stderr)
}

// SDK errors
try {
  await sandbox.readFile('/nonexistent')
} catch (error) {
  if (error.code === 'FILE_NOT_FOUND') {
    /* ... */
  } else if (error.code === 'CONTAINER_NOT_READY') {
    /* retry */
  } else if (error.code === 'TIMEOUT') {
    /* ... */
  }
}

// Retry pattern (see gotchas.md for full implementation)
```