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.

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

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

destroy()

Destroy the sandbox container and free up resources.

TypeScript

await sandbox.destroy(): Promise<void>

Note

Containers automatically sleep after 3 minutes of inactivity, but still count toward account limits. Use destroy() to immediately free up resources.

JavaScript

JavaScript

async function executeCode(code) {
  const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);

  try {
    await sandbox.writeFile("/tmp/code.py", code);
    const result = await sandbox.exec("python /tmp/code.py");
    return result.stdout;
  } finally {
    await sandbox.destroy();
  }
}

TypeScript

TypeScript

async function executeCode(code: string): Promise<string> {
  const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);

  try {
    await sandbox.writeFile('/tmp/code.py', code);
    const result = await sandbox.exec('python /tmp/code.py');
    return result.stdout;
  } finally {
    await sandbox.destroy();
  }
}

ExecutionSession methods

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

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