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

← Sandbox SDK / sandbox / concepts

Управление сессиями

Сессии представляют собой контексты выполнения bash shell внутри sandbox. Их можно представить как вкладки терминала на одном компьютере.

Сессии удобны для организации работы внутри одного sandbox. Они не являются границей безопасности между пользователями, поскольку используют общую файловую систему и общее пространство процессов.

Сессия по умолчанию

По умолчанию у каждой песочницы есть сеанс по умолчанию, который сохраняет состояние shell между командами, пока контейнер активен:

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

Рабочий каталог, переменные окружения и экспортированные переменные сохраняются между командами. Это состояние сбрасывается при перезапуске контейнера из-за простоя.

Если вы зададите enableDefaultSession: false при вызове getSandbox(), операции без явного указания sessionId выполняются изолированно вместо использования сессии по умолчанию:

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

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

Без сессии по умолчанию вторая команда не наследует состояние оболочки от первой. Рекомендуется всегда применять эту настройку, поскольку в одном из будущих релизов Sandbox SDK она станет значением по умолчанию. Создавайте или получайте явную сессию, если хотите, чтобы команды использовали общее состояние оболочки.

Автоматическое создание сессии

Контейнер автоматически создаёт сеансы при первом использовании. Если вы указываете несуществующий ID сеанса, контейнер создаёт его с настройками по умолчанию:

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

Это особенно важно учитывать после удаления сессии:

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

Благодаря автоматическому созданию сессии команды выполняются, даже если ссылаются на несуществующую сессию. Однако после удаления пользовательская конфигурация (переменные окружения, рабочий каталог) теряется.

Создание сессий

Создайте дополнительные сеансы для отдельных рабочих процессов в одной песочнице:

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");

Вы также можете задать таймаут команды по умолчанию для всех команд в сессии:

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

Отдельные команды могут переопределять тайм-аут сессии с помощью timeout опцию для exec(). Подробнее см. Sessions API и руководство по выполнению команд.

Что привязано к сессии

У каждой сессии есть собственные:

Окружение shell:

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

Рабочий каталог:

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

Переменные окружения (задаётся через createSession опции):

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

Что является общим для всех сессий

Все сессии в рамках sandbox совместно используют:

Файловая система:

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

Процессы:

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

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

Используйте сессии, если:

Пример: раздельные окружения для разработки и выполнения:

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

Используйте отдельные песочницы, если:

Рекомендации

Очистка сессии

Очистка временных сеансов чтобы освободить ресурсы, не останавливая sandbox:

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

Сессию по умолчанию нельзя удалить:

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

Область файловой системы

Сессии используют общую файловую систему sandbox - файловые операции влияют на все сессии:

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