PosixShellSandbox

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

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

Parameter	Type	Description
command	string	The shell command to execute.
options?	ExecuteOptions	Execution options (timeout, cwd).

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

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

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

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

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

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