> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/reference/compute.sandbox.md).

# compute.sandbox

## Overview

Core methods for creating, destroying, listing, and retrieving sandbox instances.

***

## `create(options?)`

Create a new compute sandbox instance.

**Parameters:**

* `options` (CreateSandboxOptions, optional): Configuration options for sandbox creation
  * `timeout` (number, optional): Sandbox execution timeout in milliseconds
  * `templateId` (string, optional): Provider-agnostic template or image identifier to boot from
  * `snapshotId` (string, optional): Snapshot ID to restore from; each provider maps this to its native concept (E2B template, Daytona snapshot, Modal image, etc.)
  * `metadata` (Record\<string, any>, optional): Custom metadata to attach to the sandbox
  * `envs` (Record\<string, string>, optional): Environment variables to set in the sandbox
  * `signal` (AbortSignal, optional): Cancels sandbox creation and cleans up an orphaned sandbox if the signal aborts
  * `name`, `namespace`, `directory` (string, optional): Provider-specific naming/placement hints
  * Additional provider-specific properties are passed through (e.g. `domain` for E2B)

**Returns:** `Promise<Sandbox>` - New sandbox instance ready for code execution and commands

**Sandbox instance properties:**

* `sandboxId` (string): Unique identifier for the sandbox
* `provider` (string): Provider hosting the sandbox (e.g., 'e2b', 'modal', 'vercel')
* `filesystem` (SandboxFileSystem): File system operations interface
* Core methods: `runCommand()`, `getInfo()`, `getUrl()`, `destroy()`
* See [Sandbox API Reference](/reference/sandbox.md) for complete interface documentation

**CreateSandboxOptions interface:**

```typescript
{
  timeout?: number;                // Execution timeout in milliseconds
  templateId?: string;             // Provider template/image identifier
  snapshotId?: string;             // Snapshot to restore from
  metadata?: Record<string, any>;  // Custom metadata
  envs?: Record<string, string>;   // Environment variables
  signal?: AbortSignal;            // Cancel creation / clean up orphaned sandbox
  name?: string;                   // Provider-specific name
  namespace?: string;              // Provider-specific namespace
  directory?: string;              // Provider-specific working directory
  [key: string]: any;              // Provider-specific properties
}
```

**Examples:**

```typescript
import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Basic sandbox creation
const sandbox = await compute.sandbox.create();
console.log(sandbox.sandboxId);  // "sb_abc123..."
console.log(sandbox.provider);   // "e2b"

// With timeout (30 minutes)
const sandbox = await compute.sandbox.create({
  timeout: 30 * 60 * 1000
});

// With environment variables
const sandbox = await compute.sandbox.create({
  envs: {
    API_KEY: 'your-api-key',
    NODE_ENV: 'production',
    DATABASE_URL: 'postgresql://...'
  }
});

// With provider template/image
const sandbox = await compute.sandbox.create({
  templateId: 'your-template-id'
});

// With custom metadata
const sandbox = await compute.sandbox.create({
  metadata: {
    userId: 'user-123',
    projectId: 'proj-456',
    environment: 'staging'
  }
});

// With multiple options combined
const sandbox = await compute.sandbox.create({
  timeout: 60 * 60 * 1000,  // 1 hour
  templateId: 'your-template-id',
  envs: {
    NODE_ENV: 'production',
    DEBUG: 'true'
  },
  metadata: {
    owner: 'team-backend',
    purpose: 'integration-tests'
  }
});

// Error handling - missing credentials
try {
  const sandbox = await compute.sandbox.create();
} catch (error) {
  console.error('Failed to create sandbox:', error.message);
}
```

**Notes:**

* Configure your provider by importing and initializing a provider package (e.g., `@computesdk/e2b`) with your credentials
* Each call creates a new sandbox instance with a unique `sandboxId`
* The `timeout` option sets maximum sandbox lifetime; sandboxes auto-terminate after this period
* The `templateId` parameter is provider-specific (refers to templates, images, or runtime environments)
* Environment variables set via `envs` are available to all commands and code executed in the sandbox
* Throws an error if the provider is missing required credentials (e.g., API key)

\ <br>

***

## `destroy(sandboxId)`

Destroy a sandbox and clean up all associated resources.

**Parameters:**

* `sandboxId` (string, required): Unique identifier of the sandbox to destroy

**Returns:** `Promise<void>` - Resolves when sandbox is successfully destroyed

> **⚠️ CAUTION:** Destroying a sandbox is a permanent operation. All data, files, and running processes in the sandbox will be irreversibly deleted.

**Examples:**

```typescript
import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Basic cleanup after use
const sandbox = await compute.sandbox.create();
// ... use sandbox ...
await sandbox.destroy();

// Alternative: destroy by ID
await compute.sandbox.destroy(sandbox.sandboxId);

// Batch cleanup - destroy multiple sandboxes
const sandboxIds = ['sb_123...', 'sb_456...', 'sb_789...'];
await Promise.all(sandboxIds.map(id => compute.sandbox.destroy(id)));

// With error handling
try {
  await sandbox.destroy();
  console.log('Sandbox destroyed successfully');
} catch (error) {
  console.error('Failed to destroy sandbox:', error.message);
}

// Best practice: ensure cleanup with finally block
let sandbox;
try {
  sandbox = await compute.sandbox.create();
  await sandbox.runCommand('echo "Hello"');
} finally {
  if (sandbox) {
    await sandbox.destroy();
  }
}
```

**Notes:**

* You can call `sandbox.destroy()` directly on the sandbox instance, or `compute.sandbox.destroy(sandboxId)` with the ID
* Destroying a sandbox terminates all running processes and releases all allocated resources
* This operation is idempotent - calling destroy on an already-destroyed sandbox succeeds without error
* Best practice: Use `finally` blocks or cleanup handlers to ensure sandboxes are destroyed even if errors occur
* All sandbox data and files are permanently lost after destruction

\ <br>

***

## `getById(sandboxId)`

Retrieve an existing sandbox instance by its unique identifier.

**Parameters:**

* `sandboxId` (string, required): Unique identifier of the sandbox to retrieve

**Returns:** `Promise<Sandbox | null>` - Sandbox instance if found, or `null` if the sandbox doesn't exist

**Sandbox instance properties:**

* `sandboxId` (string): Unique identifier for the sandbox
* `provider` (string): Provider hosting the sandbox
* `filesystem` (SandboxFileSystem): File system operations interface
* Core methods: `runCommand()`, `getInfo()`, `getUrl()`, `destroy()`
* See [Sandbox API Reference](/reference/sandbox.md) for complete interface documentation

**Examples:**

```typescript
import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Reconnect to existing sandbox by ID
const sandboxId = 'sb_abc123...';
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox) {
  const result = await sandbox.runCommand('echo "Reconnected!"');
  console.log(result.stdout);  // "Reconnected!"
}

// Store ID and reconnect later
// Step 1: Create and store ID
const newSandbox = await compute.sandbox.create();
const storedId = newSandbox.sandboxId;
// Store storedId in database, config file, etc.

// Step 2: Later, retrieve using stored ID
const retrievedSandbox = await compute.sandbox.getById(storedId);
if (retrievedSandbox) {
  await retrievedSandbox.runCommand('npm install');
}

// Check if sandbox exists before using
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox === null) {
  console.log('Sandbox not found - creating new one');
  const newSandbox = await compute.sandbox.create();
} else {
  console.log('Sandbox found - using existing one');
  await sandbox.runCommand('echo "Still active!"');
}

// Graceful handling of missing sandbox
const sandboxId = 'sb_might_not_exist...';
const sandbox = await compute.sandbox.getById(sandboxId);

if (sandbox) {
  // Sandbox exists - use it
  await sandbox.runCommand('npm test');
  console.log('Tests completed on existing sandbox');
} else {
  // Sandbox not found - handle accordingly
  console.log('Sandbox no longer exists');
}
```

**Notes:**

* Returns `null` for non-existent or destroyed sandboxes (does not throw errors)
* Retrieved sandboxes have full functionality identical to newly created sandboxes
* Useful for reconnecting to long-lived sandboxes or implementing persistent sandbox patterns
* Sandbox IDs can be stored and used to reconnect later across application restarts

\ <br>

***

## `list()`

Retrieve a list of your active sandboxes from your provider.

```typescript
import { e2b } from '@computesdk/e2b';

const compute = e2b({ apiKey: process.env.E2B_API_KEY });

const sandboxes = await compute.sandbox.list();

for (const sandbox of sandboxes) {
  console.log(sandbox.sandboxId);
}
```

**Notes:**

* Returns all active sandboxes for the configured provider
* Provider support for listing sandboxes varies — check your provider's documentation for details

\ <br>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/reference/compute.sandbox.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.