INTEGRITY Dokumentace

← Sandbox SDK / sandbox / concepts

Správa relací

Relace jsou kontexty pro spouštění příkazů shellu bash uvnitř sandboxu. Můžete si je představit jako karty terminálu na tomtéž počítači.

Relace se hodí k organizaci práce uvnitř jednoho sandboxu. Nejde ale o bezpečnostní hranici mezi uživateli, protože relace sdílejí stejný souborový systém i prostor procesů.

Výchozí relace

Každý sandbox má ve výchozím nastavení výchozí relaci, která mezi příkazy udržuje stav shellu, dokud je kontejner aktivní:

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// These commands run in the default session
await sandbox.exec("cd /app");
await sandbox.exec("pwd");  // Output: /app

await sandbox.exec("export MY_VAR=hello");
await sandbox.exec("echo $MY_VAR");  // Output: hello

Pracovní adresář, proměnné prostředí a exportované proměnné se zachovávají mezi jednotlivými příkazy. Tento stav se resetuje, pokud se kontejner restartuje kvůli neaktivitě.

Pokud nastavíte enableDefaultSession: false při volání getSandbox(), operace bez explicitního sessionId běžet izolovaně místo použití výchozí relace:

const sandbox = getSandbox(env.Sandbox, 'my-sandbox', {
  enableDefaultSession: false
});

await sandbox.exec("cd /app");
await sandbox.exec("pwd");  // Output: /workspace (cd was not inherited)

Bez výchozí relace druhý příkaz nezdědí stav shellu z prvního příkazu. Doporučujeme toto nastavení používat vždy, protože se v budoucí verzi Sandbox SDK stane výchozím. Pokud chcete, aby si příkazy sdílely stav shellu, vytvořte nebo načtěte explicitní relaci.

Automatické vytváření relace

Kontejner vytváří relace automaticky při prvním použití. Pokud odkážete na neexistující ID relace, kontejner ji vytvoří s výchozím nastavením:

// This session does not exist yet
const result = await sandbox.exec('echo hello', { sessionId: 'new-session' });
// Container automatically creates 'new-session' with defaults:
// - cwd: '/workspace'
// - env: {} (empty)

Toto chování je obzvláště důležité po smazání relace:

// Create and configure a session
const session = await sandbox.createSession({
  id: 'temp',
  env: { MY_VAR: 'value' }
});

// Delete the session
await sandbox.deleteSession('temp');

// Using the same session ID again works - auto-created with defaults
const result = await sandbox.exec('echo $MY_VAR', { sessionId: 'temp' });
// Output: (empty) - MY_VAR is not set in the freshly created session

Toto automatické vytváření znamená, že příkazy se spustí, i když odkazují na neexistující relaci. Vlastní konfigurace (proměnné prostředí, pracovní adresář) se však po smazání ztratí.

Vytváření relací

Vytvořte další relace pro oddělené pracovní postupy ve stejném sandboxu:

const buildSession = await sandbox.createSession({
  id: "build",
  env: { NODE_ENV: "production" },
  cwd: "/build"
});

const testSession = await sandbox.createSession({
  id: "test",
  env: { NODE_ENV: "test" },
  cwd: "/test"
});

// Different shell contexts
await buildSession.exec("npm run build");
await testSession.exec("npm test");

Pro všechny příkazy v relaci můžete také nastavit výchozí časový limit:

const session = await sandbox.createSession({
  id: "ci",
  commandTimeoutMs: 30000 // 30s timeout for all commands
});

await session.exec("npm test"); // Times out after 30s if still running

Jednotlivé příkazy mohou časový limit relace přepsat pomocí timeout možnost na exec(). Další podrobnosti najdete v Sessions API a průvodce spouštěním příkazů.

Co je vázáno na relaci

Každá relace má svoje vlastní:

Prostředí shellu:

await session1.exec("export MY_VAR=hello");
await session2.exec("echo $MY_VAR");  // Empty - different shell

Pracovní adresář:

await session1.exec("cd /workspace/project1");
await session2.exec("pwd");  // Different working directory

Proměnné prostředí (nastaveno pomocí createSession voleb):

const session1 = await sandbox.createSession({
  env: { API_KEY: 'key-1' }
});
const session2 = await sandbox.createSession({
  env: { API_KEY: 'key-2' }
});

Co je sdíleno mezi relacemi

Všechny relace v sandboxu sdílí:

Souborový systém:

await session1.writeFile('/workspace/file.txt', 'data');
await session2.readFile('/workspace/file.txt');  // Can read it

Procesy:

await session1.startProcess('node server.js');
await session2.listProcesses();  // Sees the server

Kdy použít relace

Relace používejte, když:

Příklad: oddělená vývojová a provozní prostředí:

// Phase 1: AI agent writes code (with API keys)
const devSession = await sandbox.createSession({
  id: "dev",
  env: { ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }
});
await devSession.exec('ai-tool "build a web server"');

// Phase 2: Run the code (without API keys)
const appSession = await sandbox.createSession({
  id: "app",
  env: { PORT: "3000" }
});
await appSession.exec("node server.js");

Samostatné sandboxy používejte, když:

Osvědčené postupy

Čištění relace

Vyčistěte dočasné relace pro uvolnění prostředků při zachování běžícího sandboxu:

try {
  const session = await sandbox.createSession({ id: 'temp' });
  await session.exec('command');
} finally {
  await sandbox.deleteSession('temp');
}

Výchozí relaci nelze odstranit:

// This throws an error
await sandbox.deleteSession('default');
// Error: Cannot delete default session. Use sandbox.destroy() instead.

Rozsah souborového systému

Relace sdílejí souborový systém sandboxu - operace se soubory ovlivní všechny session:

// Bad - affects all sessions
await session.exec('rm -rf /workspace/*');

// For user data or untrusted code, use a separate sandbox
const userSandbox = getSandbox(env.Sandbox, `user-${userId}`);