INTEGRITY Dokumentace

← Sandbox SDK / sandbox / configuration

Možnosti sandboxu

Chování sandboxu nakonfigurujte předáním možností při vytváření instance sandboxu pomocí getSandbox().

Dostupné možnosti

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

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

enableDefaultSession

Typ: boolean Výchozí: true

Určuje, co se stane, když zavoláte metody sandboxu bez explicitního sessionId. Když true, implicitní operace používají výchozí relaci sandboxu a zachovávají stav shellu mezi voláními. Pokud false, implicitní operace běží izolovaně a nepřebírají stav shellu z předchozích volání, pokud explicitně necílíte na konkrétní relaci.

Použijte enableDefaultSession: true pro interaktivní nebo stavové úlohy, kde by příkazy měly sdílet pracovní adresář a exportované proměnné. Použijte enableDefaultSession: false pro bezstavové zpracování požadavků, kde by jedno volání nemělo ovlivnit další. Doporučuje se nastavit tuto hodnotu na false : podpora výchozí relace bude v budoucí verzi Sandbox SDK odstraněna a používání createSession() explicitně je do budoucna preferovaným postupem.

// 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

Typ: boolean Výchozí: false

Udržujte kontejner trvale aktivní tím, že zabráníte automatickému vypnutí. Když true, kontejner automaticky odesílá signály heartbeat každých 30 sekund, aby se zabránilo jeho vystěhování, a nikdy automaticky nevyprší časový limit.

Jak to funguje: Sandbox automaticky plánuje odlehčené ping požadavky na kontejner každých 30 sekund. Tím se zabraňuje vyřazení kontejneru kvůli nečinnosti a zároveň se minimalizuje zátěž na zdroje. Funkci keepAlive můžete dynamicky zapnout nebo vypnout také pomocí setKeepAlive().

keepAlive příznak zůstává zachován i přes cykly hibernace a probuzení Durable Object. Jakmile ho jednou zapnete, není potřeba ho po probuzení sandboxu z hibernace znovu nastavovat.

// 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

Typ: string | number Výchozí: "10m" (10 minut)

Doba nečinnosti, po které sandbox automaticky přejde do režimu spánku. Přijímá řetězce s dobou trvání ("30s", "5m", "1h") nebo čísla (sekundy).

// 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

Typ: object

Nakonfigurujte časové limity pro operace spouštění kontejneru.

// 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
  }
});

Dostupné možnosti časového limitu:

Přepisování proměnných prostředí:

Přednost: options > env vars > výchozí hodnoty SDK

Protokolování

Typ: Proměnné prostředí

Řízení logování SDK pro ladění a monitorování. Tyto hodnoty nastavte ve vašem Workeru v wrangler.jsonc .

Dostupné možnosti:

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

Použijte debug + pretty pro lokální vývoj. Použijte info nebo warn + json pro produkci (strukturované logování).

normalizeId

Typ: boolean Výchozí: false (stane se true v budoucí verzi)

Při vytváření sandboxů používejte malá písmena v ID sandboxu. Pokud true, ID, které zadáte, se před vytvořením Durable Object převede na malá písmena (např. „MyProject-123“ → „myproject-123“).

Proč na tom záleží: Náhledové URL adresy získávají ID sandboxu z hostname, které je vždy malými písmeny, protože DNS nerozlišuje velikost písmen. Bez normalizace se sandbox vytvořený s "MyProject-123" stane přes náhledovou URL adresu nedostupným, protože směrování URL hledá "myproject-123" (jiný 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)

Kdy použít normalizeId

Použijte normalizeId: true když:

Doporučený postup: Od začátku používejte ID malými písmeny ('my-project-123' místo 'MyProject-123').

Kdy použít sleepAfter

Používejte vlastní sleepAfter hodnoty na:

Výchozí 10minutový timeout vyhovuje většině aplikací. Upravte ho podle svých potřeb.

Kdy použít keepAlive

Použijte keepAlive: true pro:

S keepAlive, kontejnery automaticky odesílají heartbeat pingy každých 30 sekund, aby nedošlo k jejich odstranění, a nikdy samy neusnou. Použijte pro scénáře, kde životní cyklus řídíte explicitně sami.