BaseSandbox()Async version of upload_files.
Base sandbox implementation with execute() as the core abstract method.
This class provides default implementations for all protocol methods.
File listing, grep, and glob use shell commands via execute(). Read uses
a server-side Python script via execute() for paginated access. Write
delegates content transfer to upload_files(). Edit uses a server-side
script for small payloads and uploads old/new strings as temp files with
a server-side replace for large ones.
BaseSandbox does not reduce or partition the trust boundary of
execute(). Its helper methods are convenience wrappers built on top of
the subclass-provided command-execution primitive and assume callers who
can use BaseSandbox already have whatever shell-execution capability
that backend exposes.
Subclasses must implement execute(), upload_files(), download_files(),
and the id property.
Whether FilesystemMiddleware may use capture-at-source offload for execute.
When True, large execute output is captured to a file in the sandbox and
only a preview is returned, avoiding a round-trip back through the agent
process. Defaults to False (opt-in) because the capture wrapper's shell and
coreutils assumptions are not guaranteed on every sandbox image; subclasses
known to be compatible set it to True. When False, execute_with_offload
runs the command unwrapped and the middleware falls back to inline execution
plus generic eviction.
Unique identifier for the sandbox backend.
Execute a command in the sandbox and return ExecuteResponse.
Run command, offloading large output to a file in the sandbox.
Captures the command's combined output: returned inline when it is at or
below max_inline_bytes, otherwise left at capture_path (so the caller
can surface a read_file pointer) with only a head/tail preview returned.
Captured output is hard-capped at max_capture_bytes (default
_EXECUTE_CAPTURE_MAX_BYTES) without killing the command, so the exit
code is preserved. When enable_capture_offload is False, the command
runs unwrapped and the full output is returned (offloaded=False), so
callers can fall back to their own handling (e.g. generic eviction).
Async version of execute_with_offload, delegating to aexecute.
Structured listing with file metadata using os.scandir.
Async version of ls, delegating to aexecute.
Read file content with server-side line-based pagination.
Runs a Python script on the sandbox via execute() that reads the
file, detects encoding, and applies offset/limit pagination for text
files. Only the requested page is returned over the wire, and text
output is capped to about 500 KiB to avoid backend stdout/log transport
failures. When that cap is exceeded, the returned content is truncated
with guidance to continue pagination using a different offset or
smaller limit.
Binary files (non-UTF-8) are returned base64-encoded without pagination.
Async version of read, delegating to aexecute.
Write content to a file, creating or overwriting it if it already exists.
Async version of write, delegating to aexecute and aupload_files.
Edit a file by replacing exact string occurrences.
For small payloads (combined old/new under _EDIT_INLINE_MAX_BYTES),
runs a server-side Python script via execute() — single round-trip,
no file transfer. For larger payloads, uploads old/new strings as
temp files and runs a server-side replace script — the source file
never leaves the sandbox.
read() normalizes CRLF to LF for the LLM, so old_string is
typically LF-only. The server-side script tries old_string as-is
first, then CRLF- and LF-normalized variants, and applies the same
transform to new_string so the file's line-ending style is
preserved on write. On mixed-ending files, replace_all=True only
touches occurrences in the first matching style — subsequent edits
can replace the rest.
Async version of edit, delegating to aexecute and aupload_files.
Delete a file or directory from the sandbox via a server-side rm.
Runs test -e || test -L first: a path that does not exist (and is not
a broken symlink) returns a not-found error, matching the contract of
FilesystemBackend and StateBackend. Because a shell test has no
error channel, a non-zero probe conflates "absent" with "unstattable"
(e.g. an unsearchable parent directory); an unknown exit code is not
treated as absent and falls through to the delete.
Uses rm -rf, so directories are removed recursively along with their
contents. A recursive delete may remove some entries before failing
partway; a non-zero rm exit (e.g. a permission error) is reported as
a failure.
Search file contents for a literal string using grep -F.
Async version of grep, delegating to aexecute with timeout guard.
Structured glob matching returning GlobResult.
Async version of glob, delegating to aexecute.
Upload multiple files to the sandbox.
Implementations must support partial success - catch exceptions per-file
and return errors in FileUploadResponse objects rather than raising.
Upload files is responsible for ensuring that the parent path exists (if user permissions allow the user to write to the given directory)
Download multiple files from the sandbox.
Implementations must support partial success - catch exceptions per-file
and return errors in FileDownloadResponse objects rather than raising.