`BackendProtocol`¶

BackendProtocol ¶

Bases: ABC

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

All file data is represented as dicts with the following structure: { "content": list[str], # Lines of text content "created_at": str, # ISO format timestamp "modified_at": str, # ISO format timestamp }

METHOD	DESCRIPTION
`ls_info`	List all files in a directory with metadata.
`als_info`	Async version of ls_info.
`read`	Read file content with line numbers.
`aread`	Async version of read.
`grep_raw`	Search for a literal text pattern in files.
`agrep_raw`	Async version of grep_raw.
`glob_info`	Find files matching a glob pattern.
`aglob_info`	Async version of glob_info.
`write`	Write content to a new file in the filesystem, error if file exists.
`awrite`	Async version of write.
`edit`	Perform exact string replacements in an existing file.
`aedit`	Async version of edit.
`upload_files`	Upload multiple files to the sandbox.
`aupload_files`	Async version of upload_files.
`download_files`	Download multiple files from the sandbox.
`adownload_files`	Async version of download_files.

ls_info ¶

ls_info(path: str) -> list[FileInfo]

List all files in a directory with metadata.

PARAMETER	DESCRIPTION
`path`	Absolute path to the directory to list. Must start with '/'. TYPE: `str`

RETURNS	DESCRIPTION
`list[FileInfo]`	List of FileInfo dicts containing file metadata:
`list[FileInfo]`	`path` (required): Absolute file path
`list[FileInfo]`	`is_dir` (optional): True if directory
`list[FileInfo]`	`size` (optional): File size in bytes
`list[FileInfo]`	`modified_at` (optional): ISO 8601 timestamp

als_info `async` ¶

als_info(path: str) -> list[FileInfo]

Async version of ls_info.

read ¶

read(file_path: str, offset: int = 0, limit: int = 2000) -> str

Read file content with line numbers.

PARAMETER	DESCRIPTION
`file_path`	Absolute path to the file to read. Must start with '/'. TYPE: `str`
`offset`	Line number to start reading from (0-indexed). Default: 0. TYPE: `int` DEFAULT: `0`
`limit`	Maximum number of lines to read. Default: 2000. TYPE: `int` DEFAULT: `2000`

RETURNS	DESCRIPTION
`str`	String containing file content formatted with line numbers (cat -n format),
`str`	starting at line 1. Lines longer than 2000 characters are truncated.
`str`	Returns an error string if the file doesn't exist or can't be read.

Note

Use pagination (offset/limit) for large files to avoid context overflow
First scan: read(path, limit=100) to see file structure
Read more: read(path, offset=100, limit=200) for next section
ALWAYS read a file before editing it
If file exists but is empty, you'll receive a system reminder warning

aread `async` ¶

aread(file_path: str, offset: int = 0, limit: int = 2000) -> str

Async version of read.

grep_raw ¶

grep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Search for a literal text pattern in files.

PARAMETER	DESCRIPTION
`pattern`	Literal string to search for (NOT regex). Performs exact substring matching within file content. Example: "TODO" matches any line containing "TODO" TYPE: `str`
`path`	Optional directory path to search in. If None, searches in current working directory. Example: "/workspace/src" TYPE: `str \| None` DEFAULT: `None`
`glob`	Optional glob pattern to filter which FILES to search. Filters by filename/path, not content. Supports standard glob wildcards: - `` matches any characters in filename - `` matches any directories recursively - `?` matches single character - `[abc]` matches one character from set TYPE:* `str \| None` DEFAULT: `None`

Examples:

"*.py" - only search Python files
"**/*.txt" - search all .txt files recursively
"src/**/*.js" - search JS files under src/
"test[0-9].txt" - search test0.txt, test1.txt, etc.

RETURNS	DESCRIPTION
`list[GrepMatch] \| str`	On success: list[GrepMatch] with structured results containing: - path: Absolute file path - line: Line number (1-indexed) - text: Full line content containing the match
`list[GrepMatch] \| str`	On error: str with error message (e.g., invalid path, permission denied)

agrep_raw `async` ¶

agrep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Async version of grep_raw.

glob_info ¶

glob_info(pattern: str, path: str = '/') -> list[FileInfo]

Find files matching a glob pattern.

PARAMETER	DESCRIPTION
`pattern`	Glob pattern with wildcards to match file paths. Supports standard glob syntax: - `` matches any characters within a filename/directory - `` matches any directories recursively - `?` matches a single character - `[abc]` matches one character from set TYPE:* `str`
`path`	Base directory to search from. Default: "/" (root). The pattern is applied relative to this path. TYPE: `str` DEFAULT: `'/'`

RETURNS	DESCRIPTION
`list[FileInfo]`	list of FileInfo

aglob_info `async` ¶

aglob_info(pattern: str, path: str = '/') -> list[FileInfo]

Async version of glob_info.

write ¶

write(file_path: str, content: str) -> WriteResult

Write content to a new file in the filesystem, error if file exists.

PARAMETER	DESCRIPTION
`file_path`	Absolute path where the file should be created. Must start with '/'. TYPE: `str`
`content`	String content to write to the file. TYPE: `str`

RETURNS	DESCRIPTION
`WriteResult`	WriteResult

awrite `async` ¶

awrite(file_path: str, content: str) -> WriteResult

Async version of write.

edit ¶

edit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Perform exact string replacements in an existing file.

PARAMETER	DESCRIPTION
`file_path`	Absolute path to the file to edit. Must start with '/'. TYPE: `str`
`old_string`	Exact string to search for and replace. Must match exactly including whitespace and indentation. TYPE: `str`
`new_string`	String to replace old_string with. Must be different from old_string. TYPE: `str`
`replace_all`	If True, replace all occurrences. If False (default), old_string must be unique in the file or the edit fails. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`EditResult`	EditResult

aedit `async` ¶

aedit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Async version of edit.

upload_files ¶

upload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Upload multiple files to the sandbox.

This API is designed to allow developers to use it either directly or by exposing it to LLMs via custom tools.

PARAMETER	DESCRIPTION
`files`	List of (path, content) tuples to upload. TYPE: `list[tuple[str, bytes]]`

RETURNS	DESCRIPTION
`list[FileUploadResponse]`	List of FileUploadResponse objects, one per input file.
`list[FileUploadResponse]`	Response order matches input order (response[i] for files[i]).
`list[FileUploadResponse]`	Check the error field to determine success/failure per file.

Examples:

responses = sandbox.upload_files(
    [
        ("/app/config.json", b"{...}"),
        ("/app/data.txt", b"content"),
    ]
)

aupload_files `async` ¶

aupload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Async version of upload_files.

download_files ¶

download_files(paths: list[str]) -> list[FileDownloadResponse]

Download multiple files from the sandbox.

This API is designed to allow developers to use it either directly or by exposing it to LLMs via custom tools.

PARAMETER	DESCRIPTION
`paths`	List of file paths to download. TYPE: `list[str]`

RETURNS	DESCRIPTION
`list[FileDownloadResponse]`	List of FileDownloadResponse objects, one per input path.
`list[FileDownloadResponse]`	Response order matches input order (response[i] for paths[i]).
`list[FileDownloadResponse]`	Check the error field to determine success/failure per file.

adownload_files `async` ¶

adownload_files(paths: list[str]) -> list[FileDownloadResponse]

Async version of download_files.

SandboxBackendProtocol ¶

Bases: BackendProtocol

Protocol for sandboxed backends with isolated runtime.

Sandboxed backends run in isolated environments (e.g., separate processes, containers) and communicate via defined interfaces.

METHOD	DESCRIPTION
`execute`	Execute a command in the process.
`aexecute`	Async version of execute.
`ls_info`	List all files in a directory with metadata.
`als_info`	Async version of ls_info.
`read`	Read file content with line numbers.
`aread`	Async version of read.
`grep_raw`	Search for a literal text pattern in files.
`agrep_raw`	Async version of grep_raw.
`glob_info`	Find files matching a glob pattern.
`aglob_info`	Async version of glob_info.
`write`	Write content to a new file in the filesystem, error if file exists.
`awrite`	Async version of write.
`edit`	Perform exact string replacements in an existing file.
`aedit`	Async version of edit.
`upload_files`	Upload multiple files to the sandbox.
`aupload_files`	Async version of upload_files.
`download_files`	Download multiple files from the sandbox.
`adownload_files`	Async version of download_files.

id `property` ¶

id: str

Unique identifier for the sandbox backend instance.

execute ¶

execute(command: str) -> ExecuteResponse

Execute a command in the process.

Simplified interface optimized for LLM consumption.

PARAMETER	DESCRIPTION
`command`	Full shell command string to execute. TYPE: `str`

RETURNS	DESCRIPTION
`ExecuteResponse`	ExecuteResponse with combined output, exit code, optional signal, and truncation flag.

aexecute `async` ¶

aexecute(command: str) -> ExecuteResponse

Async version of execute.

ls_info ¶

ls_info(path: str) -> list[FileInfo]

List all files in a directory with metadata.

PARAMETER	DESCRIPTION
`path`	Absolute path to the directory to list. Must start with '/'. TYPE: `str`

RETURNS	DESCRIPTION
`list[FileInfo]`	List of FileInfo dicts containing file metadata:
`list[FileInfo]`	`path` (required): Absolute file path
`list[FileInfo]`	`is_dir` (optional): True if directory
`list[FileInfo]`	`size` (optional): File size in bytes
`list[FileInfo]`	`modified_at` (optional): ISO 8601 timestamp

als_info `async` ¶

als_info(path: str) -> list[FileInfo]

Async version of ls_info.

read ¶

read(file_path: str, offset: int = 0, limit: int = 2000) -> str

Read file content with line numbers.

PARAMETER	DESCRIPTION
`file_path`	Absolute path to the file to read. Must start with '/'. TYPE: `str`
`offset`	Line number to start reading from (0-indexed). Default: 0. TYPE: `int` DEFAULT: `0`
`limit`	Maximum number of lines to read. Default: 2000. TYPE: `int` DEFAULT: `2000`

RETURNS	DESCRIPTION
`str`	String containing file content formatted with line numbers (cat -n format),
`str`	starting at line 1. Lines longer than 2000 characters are truncated.
`str`	Returns an error string if the file doesn't exist or can't be read.

Note

Use pagination (offset/limit) for large files to avoid context overflow
First scan: read(path, limit=100) to see file structure
Read more: read(path, offset=100, limit=200) for next section
ALWAYS read a file before editing it
If file exists but is empty, you'll receive a system reminder warning

aread `async` ¶

aread(file_path: str, offset: int = 0, limit: int = 2000) -> str

Async version of read.

grep_raw ¶

grep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Search for a literal text pattern in files.

PARAMETER	DESCRIPTION
`pattern`	Literal string to search for (NOT regex). Performs exact substring matching within file content. Example: "TODO" matches any line containing "TODO" TYPE: `str`
`path`	Optional directory path to search in. If None, searches in current working directory. Example: "/workspace/src" TYPE: `str \| None` DEFAULT: `None`
`glob`	Optional glob pattern to filter which FILES to search. Filters by filename/path, not content. Supports standard glob wildcards: - `` matches any characters in filename - `` matches any directories recursively - `?` matches single character - `[abc]` matches one character from set TYPE:* `str \| None` DEFAULT: `None`

Examples:

"*.py" - only search Python files
"**/*.txt" - search all .txt files recursively
"src/**/*.js" - search JS files under src/
"test[0-9].txt" - search test0.txt, test1.txt, etc.

RETURNS	DESCRIPTION
`list[GrepMatch] \| str`	On success: list[GrepMatch] with structured results containing: - path: Absolute file path - line: Line number (1-indexed) - text: Full line content containing the match
`list[GrepMatch] \| str`	On error: str with error message (e.g., invalid path, permission denied)

agrep_raw `async` ¶

agrep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Async version of grep_raw.

glob_info ¶

glob_info(pattern: str, path: str = '/') -> list[FileInfo]

Find files matching a glob pattern.

PARAMETER	DESCRIPTION
`pattern`	Glob pattern with wildcards to match file paths. Supports standard glob syntax: - `` matches any characters within a filename/directory - `` matches any directories recursively - `?` matches a single character - `[abc]` matches one character from set TYPE:* `str`
`path`	Base directory to search from. Default: "/" (root). The pattern is applied relative to this path. TYPE: `str` DEFAULT: `'/'`

RETURNS	DESCRIPTION
`list[FileInfo]`	list of FileInfo

aglob_info `async` ¶

aglob_info(pattern: str, path: str = '/') -> list[FileInfo]

Async version of glob_info.

write ¶

write(file_path: str, content: str) -> WriteResult

Write content to a new file in the filesystem, error if file exists.

PARAMETER	DESCRIPTION
`file_path`	Absolute path where the file should be created. Must start with '/'. TYPE: `str`
`content`	String content to write to the file. TYPE: `str`

RETURNS	DESCRIPTION
`WriteResult`	WriteResult

awrite `async` ¶

awrite(file_path: str, content: str) -> WriteResult

Async version of write.

edit ¶

edit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Perform exact string replacements in an existing file.

PARAMETER	DESCRIPTION
`file_path`	Absolute path to the file to edit. Must start with '/'. TYPE: `str`
`old_string`	Exact string to search for and replace. Must match exactly including whitespace and indentation. TYPE: `str`
`new_string`	String to replace old_string with. Must be different from old_string. TYPE: `str`
`replace_all`	If True, replace all occurrences. If False (default), old_string must be unique in the file or the edit fails. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`EditResult`	EditResult

aedit `async` ¶

aedit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Async version of edit.

upload_files ¶

upload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Upload multiple files to the sandbox.

This API is designed to allow developers to use it either directly or by exposing it to LLMs via custom tools.

PARAMETER	DESCRIPTION
`files`	List of (path, content) tuples to upload. TYPE: `list[tuple[str, bytes]]`

RETURNS	DESCRIPTION
`list[FileUploadResponse]`	List of FileUploadResponse objects, one per input file.
`list[FileUploadResponse]`	Response order matches input order (response[i] for files[i]).
`list[FileUploadResponse]`	Check the error field to determine success/failure per file.

Examples:

responses = sandbox.upload_files(
    [
        ("/app/config.json", b"{...}"),
        ("/app/data.txt", b"content"),
    ]
)

aupload_files `async` ¶

aupload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Async version of upload_files.

download_files ¶

download_files(paths: list[str]) -> list[FileDownloadResponse]

Download multiple files from the sandbox.

This API is designed to allow developers to use it either directly or by exposing it to LLMs via custom tools.

PARAMETER	DESCRIPTION
`paths`	List of file paths to download. TYPE: `list[str]`

RETURNS	DESCRIPTION
`list[FileDownloadResponse]`	List of FileDownloadResponse objects, one per input path.
`list[FileDownloadResponse]`	Response order matches input order (response[i] for paths[i]).
`list[FileDownloadResponse]`	Check the error field to determine success/failure per file.

adownload_files `async` ¶

adownload_files(paths: list[str]) -> list[FileDownloadResponse]

Async version of download_files.

BackendProtocol¶