1# Configuration
2 
3## getSandbox Options
4 
5```typescript
6const sandbox = getSandbox(env.Sandbox, 'sandbox-id', {
7  normalizeId: true,         // lowercase ID (required for preview URLs)
8  sleepAfter: '10m',         // sleep after inactivity: '5m', '1h', '2d' (default: '10m')
9  keepAlive: false,          // false = auto-timeout, true = never sleep
10  
11  containerTimeouts: {
12    instanceGetTimeoutMS: 30000,  // 30s for provisioning (default: 30000)
13    portReadyTimeoutMS: 90000     // 90s for container startup (default: 90000)
14  }
15});
16```
17 
18**Sleep Config**:
19- `sleepAfter`: Duration string (e.g., '5m', '10m', '1h') - default: '10m'
20- `keepAlive: false`: Auto-sleep (default, cost-optimized)
21- `keepAlive: true`: Never sleep (higher cost, requires explicit `destroy()`)
22- Sleeping sandboxes wake automatically (cold start)
23 
24## Instance Types
25 
26wrangler.jsonc `instance_type`:
27- `lite`: 256MB RAM, 0.5 vCPU (default)
28- `standard`: 512MB RAM, 1 vCPU
29- `heavy`: 1GB RAM, 2 vCPU
30 
31## Dockerfile Patterns
32 
33**Basic**:
34```dockerfile
35FROM docker.io/cloudflare/sandbox:0.7.0
36RUN pip3 install --no-cache-dir pandas numpy
37EXPOSE 8080  # Required for wrangler dev
38```
39 
40**Scientific**:
41```dockerfile
42FROM docker.io/cloudflare/sandbox:0.7.0
43RUN pip3 install --no-cache-dir \
44    jupyter-server ipykernel matplotlib \
45    pandas seaborn plotly scipy scikit-learn
46```
47 
48**Node.js**:
49```dockerfile
50FROM docker.io/cloudflare/sandbox:0.7.0
51RUN npm install -g typescript ts-node
52```
53 
54**CRITICAL**: `EXPOSE` required for `wrangler dev` port access. Production auto-exposes all ports.
55 
56## CLI Commands
57 
58```bash
59# Dev
60wrangler dev                    # Start local dev server
61wrangler deploy                 # Deploy to production
62wrangler tail                   # Monitor logs
63wrangler containers list        # Check container status
64wrangler secret put KEY         # Set secret
65```
66 
67## Environment & Secrets
68 
69**wrangler.jsonc**:
70```jsonc
71{
72  "vars": {
73    "ENVIRONMENT": "production",
74    "API_URL": "https://api.example.com"
75  },
76  "r2_buckets": [{
77    "binding": "DATA_BUCKET",
78    "bucket_name": "my-data-bucket"
79  }]
80}
81```
82 
83**Usage**:
84```typescript
85const token = env.GITHUB_TOKEN;  // From wrangler secret
86await sandbox.exec('git clone ...', {
87  env: { GIT_TOKEN: token }
88});
89```
90 
91## Preview URL Setup
92 
93**Prerequisites**:
94- Custom domain with wildcard DNS: `*.yourdomain.com → worker.yourdomain.com`
95- `.workers.dev` domains NOT supported
96- `normalizeId: true` in getSandbox
97- `proxyToSandbox()` called first in fetch handler
98 
99## Cron Triggers (Pre-warming)
100 
101```jsonc
102{
103  "triggers": {
104    "crons": ["*/5 * * * *"]  // Every 5 minutes
105  }
106}
107```
108 
109```typescript
110export default {
111  async scheduled(event: ScheduledEvent, env: Env) {
112    const sandbox = getSandbox(env.Sandbox, 'main');
113    await sandbox.exec('echo "keepalive"');  // Wake sandbox
114  }
115};
116```
117 
118## Logging Configuration
119 
120**wrangler.jsonc**:
121```jsonc
122{
123  "vars": {
124    "SANDBOX_LOG_LEVEL": "debug",  // debug | info | warn | error (default: info)
125    "SANDBOX_LOG_FORMAT": "pretty" // json | pretty (default: json)
126  }
127}
128```
129 
130**Dev**: `debug` + `pretty`. **Production**: `info`/`warn` + `json`.
131 
132## Timeout Environment Overrides
133 
134Override default timeouts via environment variables:
135 
136```jsonc
137{
138  "vars": {
139    "SANDBOX_INSTANCE_TIMEOUT_MS": "60000",  // Override instanceGetTimeoutMS
140    "SANDBOX_PORT_TIMEOUT_MS": "120000"      // Override portReadyTimeoutMS
141  }
142}
143```
144