Sessions

Create isolated execution contexts within a sandbox. Each session maintains its own shell state, environment variables, and working directory. See Session management concept for details.

Note

Every sandbox has a default session that automatically maintains shell state. Create additional sessions when you need isolated shell contexts for different environments or parallel workflows. For sandbox-level operations like creating containers or destroying the entire sandbox, see the Lifecycle API.

Methods

createSession()

Create a new isolated execution session.

TypeScript

const session = await sandbox.createSession(options?: SessionOptions): Promise<ExecutionSession>

Parameters:

• options (optional):
  • id - Custom session ID (auto-generated if not provided)
  • env - Environment variables for this session
  • cwd - Working directory (default: "/workspace")

Returns: Promise<ExecutionSession> with all sandbox methods bound to this session

JavaScript

JavaScript

// Multiple isolated environments
const prodSession = await sandbox.createSession({
  id: "prod",
  env: { NODE_ENV: "production", API_URL: "https://api.example.com" },
  cwd: "/workspace/prod",
});

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

// Run in parallel
const [prodResult, testResult] = await Promise.all([
  prodSession.exec("npm run build"),
  testSession.exec("npm run build"),
]);

TypeScript

TypeScript

// Multiple isolated environments
const prodSession = await sandbox.createSession({
  id: 'prod',
  env: { NODE_ENV: 'production', API_URL: 'https://api.example.com' },
  cwd: '/workspace/prod'
});

const testSession = await sandbox.createSession({
  id: 'test',
  env: { NODE_ENV: 'test', API_URL: 'http://localhost:3000' },
  cwd: '/workspace/test'
});

// Run in parallel
const [prodResult, testResult] = await Promise.all([
  prodSession.exec('npm run build'),
  testSession.exec('npm run build')
]);

getSession()

Retrieve an existing session by ID.

TypeScript

const session = await sandbox.getSession(sessionId: string): Promise<ExecutionSession>

Parameters:

• sessionId - ID of an existing session

Returns: Promise<ExecutionSession> bound to the specified session

JavaScript

JavaScript

// First request - create session
const session = await sandbox.createSession({ id: "user-123" });
await session.exec("git clone https://github.com/user/repo.git");
await session.exec("cd repo && npm install");

// Second request - resume session (environment and cwd preserved)
const session = await sandbox.getSession("user-123");
const result = await session.exec("cd repo && npm run build");

TypeScript

TypeScript

// First request - create session
const session = await sandbox.createSession({ id: 'user-123' });
await session.exec('git clone https://github.com/user/repo.git');
await session.exec('cd repo && npm install');

// Second request - resume session (environment and cwd preserved)
const session = await sandbox.getSession('user-123');
const result = await session.exec('cd repo && npm run build');

---

deleteSession()

Delete a session and clean up its resources.

TypeScript

const result = await sandbox.deleteSession(sessionId: string): Promise<SessionDeleteResult>

Parameters:

• sessionId - ID of the session to delete (cannot be "default")

Returns: Promise<SessionDeleteResult> containing:

• success - Whether deletion succeeded
• sessionId - ID of the deleted session
• timestamp - Deletion timestamp

JavaScript

JavaScript

// Create a temporary session for a specific task
const tempSession = await sandbox.createSession({ id: "temp-task" });

try {
  await tempSession.exec("npm run heavy-task");
} finally {
  // Clean up the session when done
  await sandbox.deleteSession("temp-task");
}

TypeScript

TypeScript

// Create a temporary session for a specific task
const tempSession = await sandbox.createSession({ id: 'temp-task' });

try {
  await tempSession.exec('npm run heavy-task');
} finally {
  // Clean up the session when done
  await sandbox.deleteSession('temp-task');
}

Warning

Deleting a session immediately terminates all running commands. The default session cannot be deleted.

---

setEnvVars()

Set environment variables in the sandbox.

TypeScript

await sandbox.setEnvVars(envVars: Record<string, string>): Promise<void>

Parameters:

• envVars - Key-value pairs of environment variables to set

Warning

Call setEnvVars() before any other sandbox operations to ensure environment variables are available from the start.

JavaScript

JavaScript

const sandbox = getSandbox(env.Sandbox, "user-123");

// Set environment variables first
await sandbox.setEnvVars({
  API_KEY: env.OPENAI_API_KEY,
  DATABASE_URL: env.DATABASE_URL,
  NODE_ENV: "production",
});

// Now commands can access these variables
await sandbox.exec("python script.py");

TypeScript

TypeScript

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

// Set environment variables first
await sandbox.setEnvVars({
  API_KEY: env.OPENAI_API_KEY,
  DATABASE_URL: env.DATABASE_URL,
  NODE_ENV: 'production'
});

// Now commands can access these variables
await sandbox.exec('python script.py');

---

ExecutionSession methods

The ExecutionSession object has all sandbox methods bound to the specific session:

Category	Methods
Commands	exec(), execStream()
Processes	startProcess(), listProcesses(), killProcess(), killAllProcesses(), getProcessLogs(), streamProcessLogs()
Files	writeFile(), readFile(), mkdir(), deleteFile(), renameFile(), moveFile(), gitCheckout()
Environment	setEnvVars()
Code Interpreter	createCodeContext(), runCode(), listCodeContexts(), deleteCodeContext()

Related resources

• Session management concept - How sessions work
• Commands API - Execute commands