Skip to main content
The Sandbox class is the main entry point to OpenSandbox. Use it to create new sandboxes, connect to existing ones, and access all sub-modules (commands, filesystem, PTY, templates).

​
Creating a Sandbox

import { Sandbox } from 'opensandbox';

const sandbox = await Sandbox.create({
  template: 'base',
  timeout: 300,
  envs: { NODE_ENV: 'production' },
  metadata: { owner: 'my-agent' },
});

​
Sandbox.create(opts?)

Creates a new sandbox and returns a connected Sandbox instance.
​
opts
SandboxOpts
Returns: Promise<Sandbox>

​
Connecting to an Existing Sandbox

const sandbox = await Sandbox.connect('sandbox-abc123', {
  apiKey: 'sk-...',
});

​
Sandbox.connect(sandboxId, opts?)

Connects to a running sandbox by ID.
​
sandboxId
string
required
The ID of the sandbox to connect to.
​
opts
object
Returns: Promise<Sandbox>

​
Properties

PropertyTypeDescription
sandboxIdstringUnique identifier for the sandbox
statusstringCurrent status: "running", "stopped", or "error"
filesFilesystemFilesystem operations
commandsCommandsCommand execution
ptyPtyPTY terminal access

​
Instance Methods

​
sandbox.kill()

Stops and destroys the sandbox. All data is lost. 
await sandbox.kill();
Returns: Promise<void>

​
sandbox.isRunning()

Checks if the sandbox is still alive. 
const alive = await sandbox.isRunning();
if (!alive) {
  console.log('Sandbox has stopped');
}
Returns: Promise<boolean>

​
sandbox.setTimeout(timeout)

Updates the sandbox timeout. Resets the TTL countdown. 
// Extend the sandbox for another 10 minutes
await sandbox.setTimeout(600);
​
timeout
number
required
New timeout in seconds.
Returns: Promise<void>