BaseSandbox

BaseSandbox

Bases: SandboxBackendProtocol, ABC

Base sandbox implementation with execute() as abstract method.

This class provides default implementations for all protocol methods using shell commands. Subclasses only need to implement execute().

METHOD	DESCRIPTION
execute	Execute a command in the sandbox and return ExecuteResponse.
ls_info	Structured listing with file metadata using os.scandir.
read	Read file content with line numbers using a single shell command.
write	Create a new file. Returns WriteResult; error populated on failure.
edit	Edit a file by replacing string occurrences. Returns EditResult.
grep_raw	Structured search results or error string for invalid input.
glob_info	Structured glob matching returning FileInfo dicts.
upload_files	Upload multiple files to the sandbox.
download_files	Download multiple files from the sandbox.
als_info	Async version of ls_info.
aread	Async version of read.
agrep_raw	Async version of grep_raw.
aglob_info	Async version of glob_info.
awrite	Async version of write.
aedit	Async version of edit.
aupload_files	Async version of upload_files.
adownload_files	Async version of download_files.
aexecute	Async version of execute.

id abstractmethod property

id: str

Unique identifier for the sandbox backend.

execute abstractmethod

execute(command: str) -> ExecuteResponse

Execute a command in the sandbox and return ExecuteResponse.

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.

ls_info

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

Structured listing with file metadata using os.scandir.

read

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

Read file content with line numbers using a single shell command.

write

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

Create a new file. Returns WriteResult; error populated on failure.

edit

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

Edit a file by replacing string occurrences. Returns EditResult.

grep_raw

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

Structured search results or error string for invalid input.

glob_info

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

Structured glob matching returning FileInfo dicts.

upload_files abstractmethod

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

Upload multiple files to the sandbox.

Implementations must support partial success - catch exceptions per-file and return errors in FileUploadResponse objects rather than raising.

download_files abstractmethod

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

Download multiple files from the sandbox.

Implementations must support partial success - catch exceptions per-file and return errors in FileDownloadResponse objects rather than raising.

als_info async

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

Async version of ls_info.

aread async

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

Async version of read.

agrep_raw async

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

Async version of grep_raw.

aglob_info async

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

Async version of glob_info.

awrite async

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

Async version of write.

aedit async

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

Async version of edit.

aupload_files async

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

Async version of upload_files.

adownload_files async

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

Async version of download_files.

aexecute async

aexecute(command: str) -> ExecuteResponse

Async version of execute.