Skip to content
zidane
SDK reference

zidane/contexts/sandbox

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

import { … } from 'zidane/contexts/sandbox'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.

TypeScript
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#

createSandboxContextFunction#

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

TypeScript
function createSandboxContext(provider: SandboxProvider): ExecutionContext

Parameters

Parameters
NameTypeDescription
providerSandboxProvider

Sandbox backend that creates and drives sandboxes.

Example

Example
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()),
})

src/contexts/sandbox.ts:75

Interfaces#

SandboxProviderInterface#

Backend of a remote sandbox. Implement it to plug a sandbox service into createSandboxContext.

TypeScript
interface SandboxProvider

Properties

SandboxProvider properties
NameTypeDescription
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.

namestring

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.

src/contexts/sandbox.ts:18