Session management

Sessions are bash shell execution contexts within a sandbox. Think of them as terminal tabs in the same computer.

Sandbox = A user or task workspace
Session = A shell in that workspace

Sessions are useful for organizing work inside one sandbox. They are not a security boundary between users because sessions share the same filesystem and process space.

Default session

By default, every sandbox has a default session that maintains shell state between commands while the container is active:

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

Working directory, environment variables, and exported variables carry over between commands. This state resets if the container restarts due to inactivity.

If you set enableDefaultSession: false when calling getSandbox(), operations without an explicit sessionId run in isolation instead of using the default session:

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

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

Without the default session, the second command does not inherit shell state from the first command. It is recommended that you always apply this setting as it will become the default in a future Sandbox SDK release. Create or retrieve an explicit session when you want commands to share shell state.

Automatic session creation

The container automatically creates sessions on first use. If you reference a non-existent session ID, the container creates it with default settings:

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

This behavior is particularly relevant after deleting a session:

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

This auto-creation means commands still run when they reference a non-existent session. However, custom configuration (environment variables, working directory) is lost after deletion.

Creating sessions

Create additional sessions for separate workflows in the same sandbox:

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

You can also set a default command timeout for all commands in a session:

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

Individual commands can override the session timeout with the timeout option on exec(). For more details, refer to the Sessions API and the execute commands guide.

What is scoped to a session

Each session has its own:

Shell environment:

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

Working directory:

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

Environment variables (set via createSession options):

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

What is shared across sessions

All sessions in a sandbox share:

Filesystem:

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

Processes:

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

When to use sessions

Use sessions when:

You need separate shell state for one user's tasks
Running parallel operations with different environments
Keeping AI agent credentials separate from app runtime

Example - separate dev and runtime environments:

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

Use separate sandboxes when:

You need complete isolation for untrusted code
Different users need separate workspaces
User data must stay separated
Independent resource allocation is needed

Best practices

Session cleanup

Clean up temporary sessions to free resources while keeping the sandbox running:

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

Default session cannot be deleted:

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

Filesystem scope

Sessions share the sandbox filesystem - file operations affect all sessions:

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

Sandbox lifecycle - Understanding sandbox management
Sessions API - Complete session API reference