INTEGRITY Документация

← Sandbox SDK / sandbox / configuration

Параметры песочницы

Настройте поведение песочницы, передав параметры при создании экземпляра песочницы с помощью getSandbox().

Доступные варианты

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

const sandbox = getSandbox(binding, sandboxId, options?: SandboxOptions);

enableDefaultSession

Тип: boolean По умолчанию: true

Определяет, что происходит, если вы вызываете методы песочницы без явного указания sessionId. Когда true, неявные операции используют сессию песочницы по умолчанию и сохраняют состояние shell между вызовами. Когда false, неявные операции выполняются изолированно и не наследуют состояние shell от предыдущих вызовов, если вы явно не указали сессию.

Используйте enableDefaultSession: true для интерактивных или сохраняющих состояние рабочих процессов, где команды должны использовать общий рабочий каталог и экспортированные переменные. Используйте enableDefaultSession: false для обработки запросов без сохранения состояния, где один вызов не должен влиять на следующий. Рекомендуется установить значение false : поддержка сессии по умолчанию будет удалена в будущей версии Sandbox SDK, а использование createSession() явно, это рекомендуемый подход на будущее.

// Default behavior: implicit operations use the default session
const statefulSandbox = getSandbox(env.Sandbox, "user-123");

await statefulSandbox.exec("cd /workspace/app");
const statefulResult = await statefulSandbox.exec("pwd");
// statefulResult.stdout: "/workspace/app"
// The second exec inherited the working directory from the first.

// Sessionless behavior: implicit operations do not share shell state
const statelessSandbox = getSandbox(env.Sandbox, "api-worker", {
	enableDefaultSession: false,
});

await statelessSandbox.exec("cd /workspace/app");
const statelessResult = await statelessSandbox.exec("pwd");
// statelessResult.stdout: "/workspace"
// The second exec did not inherit shell state from the first.
// Default behavior: implicit operations use the default session
const statefulSandbox = getSandbox(env.Sandbox, 'user-123');

await statefulSandbox.exec('cd /workspace/app');
const statefulResult = await statefulSandbox.exec('pwd');
// statefulResult.stdout: "/workspace/app"
// The second exec inherited the working directory from the first.

// Sessionless behavior: implicit operations do not share shell state
const statelessSandbox = getSandbox(env.Sandbox, 'api-worker', {
  enableDefaultSession: false
});

await statelessSandbox.exec('cd /workspace/app');
const statelessResult = await statelessSandbox.exec('pwd');
// statelessResult.stdout: "/workspace"
// The second exec did not inherit shell state from the first.

keepAlive

Тип: boolean По умолчанию: false

Поддерживайте контейнер активным бессрочно, предотвращая автоматическое отключение. Когда true, контейнер автоматически отправляет пинги проверки активности каждые 30 секунд, чтобы предотвратить вытеснение, и никогда не завершается по тайм-ауту самостоятельно.

Как это работает: Песочница автоматически отправляет в контейнер лёгкие ping-запросы каждые 30 секунд. Это предотвращает вытеснение контейнера из-за неактивности и минимизирует нагрузку на ресурсы. Также можно динамически включать и отключать keepAlive с помощью setKeepAlive().

keepAlive флаг сохраняется при циклах гибернации и пробуждения Durable Object. После включения повторно задавать его не нужно, даже когда песочница пробуждается после гибернации.

// For long-running processes that need the container to stay alive
const sandbox = getSandbox(env.Sandbox, "user-123", {
	keepAlive: true,
});

// Run your long-running process
await sandbox.startProcess("python long_running_script.py");

// Important: Must explicitly destroy when done
try {
	// Your work here
} finally {
	await sandbox.destroy(); // Required to prevent containers running indefinitely
}
// For long-running processes that need the container to stay alive
const sandbox = getSandbox(env.Sandbox, 'user-123', {
  keepAlive: true
});

// Run your long-running process
await sandbox.startProcess('python long_running_script.py');

// Important: Must explicitly destroy when done
try {
  // Your work here
} finally {
  await sandbox.destroy(); // Required to prevent containers running indefinitely
}

sleepAfter

Тип: string | number По умолчанию: "10m" (10 минут)

Время бездействия, после которого sandbox автоматически переходит в спящий режим. Принимает строки длительности ("30s", "5m", "1h") или числа (в секундах).

// Sleep after 30 seconds of inactivity
const sandbox = getSandbox(env.Sandbox, "user-123", {
	sleepAfter: "30s",
});

// Sleep after 5 minutes (using number)
const sandbox2 = getSandbox(env.Sandbox, "user-456", {
	sleepAfter: 300, // 300 seconds = 5 minutes
});
// Sleep after 30 seconds of inactivity
const sandbox = getSandbox(env.Sandbox, 'user-123', {
  sleepAfter: '30s'
});

// Sleep after 5 minutes (using number)
const sandbox2 = getSandbox(env.Sandbox, 'user-456', {
  sleepAfter: 300  // 300 seconds = 5 minutes
});

containerTimeouts

Тип: object

Настройте тайм-ауты для операций запуска контейнера.

// Extended startup with custom Dockerfile work
// (installing packages, starting services before SDK)
const sandbox = getSandbox(env.Sandbox, "data-processor", {
	containerTimeouts: {
		portReadyTimeoutMS: 180_000, // 3 minutes for startup work
	},
});

// Wait longer during traffic spikes
const sandbox2 = getSandbox(env.Sandbox, "user-env", {
	containerTimeouts: {
		instanceGetTimeoutMS: 60_000, // 1 minute for provisioning
	},
});
// Extended startup with custom Dockerfile work
// (installing packages, starting services before SDK)
const sandbox = getSandbox(env.Sandbox, 'data-processor', {
  containerTimeouts: {
    portReadyTimeoutMS: 180_000  // 3 minutes for startup work
  }
});

// Wait longer during traffic spikes
const sandbox2 = getSandbox(env.Sandbox, 'user-env', {
  containerTimeouts: {
    instanceGetTimeoutMS: 60_000   // 1 minute for provisioning
  }
});

Доступные варианты тайм-аута:

Переопределения переменных окружения:

Приоритет: options > env vars > значения по умолчанию SDK

Логирование

Тип: Переменные окружения

Настройте журналирование SDK для отладки и мониторинга. Задайте их в настройках Worker в wrangler.jsonc файл.

Доступные варианты:

{
	"vars": {
		"SANDBOX_LOG_LEVEL": "debug",
		"SANDBOX_LOG_FORMAT": "pretty"
	}
}
[vars]
SANDBOX_LOG_LEVEL = "debug"
SANDBOX_LOG_FORMAT = "pretty"

Используйте debug + pretty для локальной разработки. Используйте info или warn + json для продакшена (структурированное логирование).

normalizeId

Тип: boolean По умолчанию: false (станет true в будущей версии)

Используйте строчные ID песочниц при их создании. Если true, указанный вами ID приводится к нижнему регистру перед созданием Durable Object (например, "MyProject-123" → "myproject-123").

Почему это важно: Preview-URL извлекает идентификатор песочницы из имени хоста, которое всегда приводится к нижнему регистру из-за регистронезависимости DNS. Без нормализации песочница, созданная с идентификатором "MyProject-123", станет недоступна через preview-URL, поскольку маршрутизация URL ищет "myproject-123" (другой Durable Object).

// Without normalization (default)
const sandbox1 = getSandbox(env.Sandbox, "MyProject-123");
// Creates Durable Object with ID: "MyProject-123"
// Preview URL: 8000-myproject-123.example.com
// Problem: URL routes to "myproject-123" (different DO)

// With normalization
const sandbox2 = getSandbox(env.Sandbox, "MyProject-123", {
	normalizeId: true,
});
// Creates Durable Object with ID: "myproject-123"
// Preview URL: 8000-myproject-123.example.com
// Works: URL routes to "myproject-123" (same DO)
// Without normalization (default)
const sandbox1 = getSandbox(env.Sandbox, 'MyProject-123');
// Creates Durable Object with ID: "MyProject-123"
// Preview URL: 8000-myproject-123.example.com
// Problem: URL routes to "myproject-123" (different DO)

// With normalization
const sandbox2 = getSandbox(env.Sandbox, 'MyProject-123', {
  normalizeId: true
});
// Creates Durable Object with ID: "myproject-123"
// Preview URL: 8000-myproject-123.example.com
// Works: URL routes to "myproject-123" (same DO)

Когда использовать normalizeId

Используйте normalizeId: true когда:

Рекомендуемая практика: Используйте идентификаторы в нижнем регистре с самого начала ('my-project-123' вместо 'MyProject-123').

Когда использовать sleepAfter

Используйте пользовательский sleepAfter значения в:

Тайм-аут по умолчанию в 10 минут подходит для большинства приложений. При необходимости настройте его под ваши задачи.

Когда использовать keepAlive

Используйте keepAlive: true для:

С keepAlive, контейнеры автоматически отправляют heartbeat-пинги каждые 30 секунд, чтобы избежать вытеснения, и никогда не переходят в спящий режим самостоятельно. Используйте для сценариев, где вы явно управляете жизненным циклом.