# zidane/contexts/sandbox

> The generic remote sandbox context and the provider interface that E2B and Daytona implement.

Import: `import { … } from 'zidane/contexts/sandbox'`. Source: [src/contexts/sandbox.ts](https://github.com/Tahul/zidane/blob/main/src/contexts/sandbox.ts).

Use `createSandboxContext` when you want an `ExecutionContext` backed by a remote sandbox. It takes a `SandboxProvider`, a small interface that creates, attaches to and destroys sandboxes. Pass the E2B or Daytona provider, or implement the interface for your own backend.

```ts
import { createSandboxContext } from 'zidane/contexts/sandbox'
import { createE2BProvider } from 'zidane/contexts/e2b'

const context = createSandboxContext(createE2BProvider({ cwd: '/home/user/project' }))
const handle = await context.spawn()
const result = await context.exec(handle, 'uname -a')
console.log(result.stdout)
await context.destroy(handle)
```

## Functions

### `createSandboxContext`

Function.

Creates an execution context that runs commands and file operations in a remote sandbox through `provider`.

```ts
function createSandboxContext(provider: SandboxProvider): ExecutionContext
```

**Parameters**

- `provider` (`SandboxProvider`): Sandbox backend that creates and drives sandboxes.

**Returns** `ExecutionContext`

**Example**

```ts
import { createAgent } from 'zidane'
import { createE2BProvider } from 'zidane/contexts/e2b'
import { createSandboxContext } from 'zidane/contexts/sandbox'
import { basic } from 'zidane/presets'
import { anthropic } from 'zidane/providers/anthropic'

const agent = createAgent({
  ...basic,
  provider: anthropic(),
  execution: createSandboxContext(createE2BProvider()),
})
```

Source: [src/contexts/sandbox.ts:75](https://github.com/Tahul/zidane/blob/main/src/contexts/sandbox.ts#L75)

## Interfaces

### `SandboxProvider`

Interface.

Backend of a remote sandbox. Implement it to plug a sandbox service into [`createSandboxContext`](https://zidane.si/docs/reference/contexts-sandbox.md#createSandboxContext).

```ts
interface SandboxProvider
```

**Properties**

- `destroy` (`(sandboxId: string) => Promise<void>`): Destroys the sandbox and releases its resources.
- `exec` (`(sandboxId: string, command: string, options?: { cwd?: string; env?: Record<string, string>; timeout?: number }) => Promise<ExecResult>`): Runs a command in the sandbox and returns its buffered output.
- `execStream?` (`(sandboxId: string, command: string, options?: { cwd?: string; env?: Record<string, string>; signal?: AbortSignal }) => Promise<StreamHandle>`): Optional live bidirectional stream — see `ExecutionContext.execStream`
  for the implementor contract. Providers whose backing API has no stdin
  channel omit it; `createSandboxContext` then leaves `execStream` off the
  context entirely so `capabilities.stream` stays false and callers get a
  clear "unsupported" error instead of a silent host spawn.
- `listFiles` (`(sandboxId: string, path: string, options?: ListFilesOptions) => Promise<string[]>`): Lists files under a path, or glob matches when `options.glob` is set.
- `name` (`string`): Provider name, such as `e2b` or `daytona`.
- `openTerminal?` (`(sandboxId: string, options: TerminalOptions) => Promise<TerminalProcess>`): Optional interactive terminal — see `ExecutionContext.openTerminal`.
- `readFile` (`(sandboxId: string, path: string) => Promise<string>`): Reads a text file from the sandbox.
- `reconnectTerminal?` (`(sandboxId: string, id: string, options: TerminalOptions) => Promise<TerminalProcess | null>`): Re-attach to a terminal by id — see `ExecutionContext.reconnectTerminal`.
- `spawn` (`(config: SpawnConfig) => Promise<{ cwd: string; id: string }>`): Creates a sandbox and returns its id and working directory.
- `writeFile` (`(sandboxId: string, path: string, content: string | Buffer<ArrayBufferLike>, encoding?: BufferEncoding) => Promise<void>`): Writes a file into the sandbox.

Source: [src/contexts/sandbox.ts:18](https://github.com/Tahul/zidane/blob/main/src/contexts/sandbox.ts#L18)