PosixShellSandbox

Defined in: src/sandbox/posix-shell.ts:65

Abstract sandbox that provides shell-based defaults for file and code operations. Assumes a POSIX-compatible shell (sh/bash) on the target.

Subclasses only need to implement executeStreaming. The remaining operations — executeCodeStreaming, readFile, writeFile, removeFile, and listFiles — are implemented via shell commands piped through executeStreaming.

Subclasses may override any method with a native implementation for better performance or to handle edge cases (e.g., binary-safe file transfer via Docker stdin pipes, or native API calls for cloud backends).

Subclasses must apply options.env in executeStreaming or it has no effect: backends that build a shell-command string prepend buildShellEnvPrefix; backends that set env via process flags (e.g. Docker’s -e) call validateEnvKeys and pass the values directly.

Extends

Sandbox

Constructors

Constructor

new PosixShellSandbox(): PosixShellSandbox;

Returns

PosixShellSandbox

Inherited from

Sandbox.constructor

Properties

toolPrefix

toolPrefix: string = 'sandbox';

Defined in: src/sandbox/base.ts:118

Prefix applied to tool names when registered on an agent (e.g. 'sandbox' produces sandbox_bash). Set to undefined to disable prefixing. Defaults to 'sandbox'.

Inherited from

Sandbox.toolPrefix

Methods

executeStreaming()

abstract executeStreaming(command, options?): AsyncIterable<
  | StreamChunk
| ExecutionResult>;

Defined in: src/sandbox/base.ts:54

Execute a shell command, streaming output.

Yields StreamChunk objects for stdout and stderr as output arrives. The final yield is an ExecutionResult with the exit code and complete output.

Parameters

Parameter	Type	Description
`command`	`string`	The shell command to execute.
`options?`	`ExecuteOptions`	Execution options.

Returns

AsyncIterable< | StreamChunk | ExecutionResult>

Async iterable yielding StreamChunks followed by a final ExecutionResult.

Inherited from

Sandbox.executeStreaming

getTools()

getTools(): Tool[];

Defined in: src/sandbox/base.ts:125

Tools this sandbox vends to an agent, registered during Agent.initialize(). A tool is skipped if the user already registered one with the same name. Override to provide them.

Returns

Tool[]

Inherited from

Sandbox.getTools

execute()

execute(command, options?): Promise<ExecutionResult>;

Defined in: src/sandbox/base.ts:141

Execute a shell command and return the result.

Consumes executeStreaming and returns the final ExecutionResult. Use executeStreaming when you need to process output as it arrives.

Parameters

Parameter	Type	Description
`command`	`string`	The shell command to execute.
`options?`	`ExecuteOptions`	Execution options.

Returns

Promise<ExecutionResult>

The execution result with exit code and output.

Inherited from

Sandbox.execute

executeCode()

executeCode(
   code,
   language,
options?): Promise<ExecutionResult>;

Defined in: src/sandbox/base.ts:161

Execute source code and return the result.

Consumes executeCodeStreaming and returns the final ExecutionResult. Use executeCodeStreaming when you need to process output as it arrives.

Parameters

Parameter	Type	Description
`code`	`string`	The source code to execute.
`language`	`string`	The interpreter to use.
`options?`	`ExecuteOptions`	Execution options.

Returns

Promise<ExecutionResult>

The execution result with exit code and output.

Inherited from

Sandbox.executeCode

readText()

readText(path): Promise<string>;

Defined in: src/sandbox/base.ts:179

Read a text file from the sandbox filesystem.

Convenience wrapper over readFile that decodes bytes as UTF-8. For other encodings, call readFile and decode manually.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the file to read.

Returns

Promise<string>

The file contents decoded as a UTF-8 string.

Inherited from

Sandbox.readText

writeText()

writeText(path, content): Promise<void>;

Defined in: src/sandbox/base.ts:192

Write a text file to the sandbox filesystem.

Convenience wrapper over writeFile that encodes a string as UTF-8. For other encodings, encode manually and call writeFile.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the file to write.
`content`	`string`	The text content to write.

Returns

Promise<void>

Inherited from

Sandbox.writeText

executeCodeStreaming()

executeCodeStreaming(
   code,
   language,
   options?): AsyncGenerator<
  | StreamChunk
| ExecutionResult, void, undefined>;

Defined in: src/sandbox/posix-shell.ts:66

Execute source code via a language interpreter, streaming output.

Parameters

Parameter	Type	Description
`code`	`string`	The source code to execute.
`language`	`string`	The interpreter to use (e.g., `"python3"`, `"node"`).
`options?`	`ExecuteOptions`	Execution options.

Returns

AsyncGenerator< | StreamChunk | ExecutionResult, void, undefined>

Async iterable yielding StreamChunks followed by a final ExecutionResult.

Overrides

Sandbox.executeCodeStreaming

readFile()

readFile(path): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: src/sandbox/posix-shell.ts:79

Read a file from the sandbox filesystem as raw bytes.

Returns Uint8Array to support both text and binary files. Use readText for a convenience wrapper that decodes to a string.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the file to read.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The file contents as raw bytes.

Throws

Error if the file does not exist.

Overrides

Sandbox.readFile

writeFile()

writeFile(path, content): Promise<void>;

Defined in: src/sandbox/posix-shell.ts:87

Write raw bytes to a file in the sandbox filesystem.

Implementations should create parent directories if they do not exist. Use writeText for a convenience wrapper that encodes a string.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the file to write.
`content`	`Uint8Array`	The content to write.

Returns

Promise<void>

Overrides

Sandbox.writeFile

removeFile()

removeFile(path): Promise<void>;

Defined in: src/sandbox/posix-shell.ts:98

Remove a file from the sandbox filesystem.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the file to remove.

Returns

Promise<void>

Throws

Error if the file does not exist.

Overrides

Sandbox.removeFile

listFiles()

listFiles(path): Promise<FileInfo[]>;

Defined in: src/sandbox/posix-shell.ts:105

List files in a sandbox directory.

Returns FileInfo entries with name, isDir, and size metadata. Fields isDir and size may be undefined if the backend cannot determine them.

Parameters

Parameter	Type	Description
`path`	`string`	Path to the directory to list.

Returns

Promise<FileInfo[]>

Array of FileInfo entries for the directory contents.

Throws

Error if the directory does not exist.

Overrides

Sandbox.listFiles