Skip to main content
Options for configuring sandbox behavior, timeouts, and lifecycle management.

​
Type Definition

interface SandboxOptions {
  sleepAfter?: string | number;
  baseUrl?: string;
  keepAlive?: boolean;
  normalizeId?: boolean;
  containerTimeouts?: {
    instanceGetTimeoutMS?: number;
    portReadyTimeoutMS?: number;
    waitIntervalMS?: number;
  };
}

​
Properties

​
sleepAfter
string | number
default:"'10m'"
Duration after which the sandbox will sleep if no requests are received.Can be:
  • A string like "30s", "3m", "5m", "1h" (seconds, minutes, or hours)
  • A number representing seconds (e.g., 180 for 3 minutes)
Ignored when keepAlive is true.
​
baseUrl
string
Base URL for the sandbox API (advanced use cases)
​
keepAlive
boolean
default:false
Keep the container alive indefinitely by preventing automatic shutdown.When true:
  • Container never auto-sleeps
  • Must call sandbox.destroy() explicitly to cleanup
  • Use for long-running services or when activity can’t be automatically detected
Important: Call sandbox.destroy() when done to avoid resource leaks.
​
normalizeId
boolean
default:false
Normalize sandbox ID to lowercase for preview URL compatibility.Required for preview URLs because hostnames are case-insensitive (RFC 3986).Important: Different normalizeId values create different Durable Object instances:
  • getSandbox(ns, "MyProject") → DO key: "MyProject"
  • getSandbox(ns, "MyProject", {normalizeId: true}) → DO key: "myproject"
Future change: Will default to true in a future version. To prepare:
  • Use lowercase IDs, or
  • Explicitly pass normalizeId: true
​
containerTimeouts
object
Container startup timeout configuration. Tune based on container characteristics.Can also be configured via environment variables:
  • SANDBOX_INSTANCE_TIMEOUT_MS
  • SANDBOX_PORT_TIMEOUT_MS
  • SANDBOX_POLL_INTERVAL_MS
Precedence: options > env vars > SDK defaults

​
Example: Basic Configuration

import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(
  env.SANDBOX,
  'my-sandbox',
  {
    sleepAfter: '30m',
    normalizeId: true
  }
);

​
Example: Keep Alive for Long-Running Service

const sandbox = getSandbox(
  env.SANDBOX,
  'websocket-server',
  {
    keepAlive: true
  }
);

// Start server
await sandbox.startProcess('node server.js');

// Server runs indefinitely
// Must cleanup manually:
process.on('SIGTERM', async () => {
  await sandbox.destroy();
});

​
Example: Heavy Container Timeouts

// For containers with ML models or large dependencies
const sandbox = getSandbox(
  env.SANDBOX,
  'ml-inference',
  {
    containerTimeouts: {
      portReadyTimeoutMS: 180_000, // 3 minutes
      instanceGetTimeoutMS: 60_000  // 1 minute
    }
  }
);

​
Example: Fail-Fast Configuration

// For latency-sensitive applications
const sandbox = getSandbox(
  env.SANDBOX,
  'api-backend',
  {
    containerTimeouts: {
      instanceGetTimeoutMS: 15_000,
      portReadyTimeoutMS: 30_000
    },
    sleepAfter: '5m'
  }
);

​
Example: Environment Variable Timeouts

# wrangler.toml
[env.production.vars]
SANDBOX_INSTANCE_TIMEOUT_MS = "45000"
SANDBOX_PORT_TIMEOUT_MS = "120000"
SANDBOX_POLL_INTERVAL_MS = "500"

// Timeouts read from env vars automatically
const sandbox = getSandbox(env.SANDBOX, 'my-sandbox');

// Or override specific values
const sandbox = getSandbox(
  env.SANDBOX,
  'my-sandbox',
  {
    containerTimeouts: {
      portReadyTimeoutMS: 60_000 // Override just this one
    }
  }
);

​
Timeout Configuration Guide

​
Default Settings (Most Use Cases)

// SDK defaults work for most applications
const sandbox = getSandbox(env.SANDBOX, 'my-sandbox');
// instanceGetTimeoutMS: 30s
// portReadyTimeoutMS: 90s

​
Heavy Containers

// Containers with large dependencies, ML models
containerTimeouts: {
  portReadyTimeoutMS: 180_000 // 3 minutes
}

​
Fail-Fast Applications

// Latency-sensitive apps that need quick feedback
containerTimeouts: {
  instanceGetTimeoutMS: 15_000,
  portReadyTimeoutMS: 30_000
}

​
Notes

  • Options are set when calling getSandbox(), not when creating the namespace
  • Container timeouts can be configured per-sandbox or globally via env vars
  • normalizeId affects Durable Object routing - different values create different instances
  • keepAlive: true requires manual cleanup to avoid resource leaks
  • Sleep timeout resets on each request
  • Sleeping sandboxes restart automatically on next request
  • Startup timeouts account for container provisioning delays

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us