PosixShellSandbox

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

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).

Extends

Sandbox

Constructors

Constructor

new PosixShellSandbox(): PosixShellSandbox;

Returns

PosixShellSandbox

Inherited from

Sandbox.constructor

Methods

executeStreaming()

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

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

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 (timeout, cwd). |

Returns

AsyncIterable< | StreamChunk | ExecutionResult>

Async iterable yielding StreamChunks followed by a final ExecutionResult.

Inherited from

Sandbox.executeStreaming

execute()

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

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

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

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:139

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 (timeout, cwd). |

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:157

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:170

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:43

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 (timeout, cwd). |

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:56

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:64

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:75

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:82

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