deepagents sandboxes

Requires Python 3.11+ and the contree-sdk[langchain] extra. See LangChain DeepAgents for executable scenarios. Adapters accept the public executor contracts; they do not require concrete session implementations. Other inherited BaseSandbox tools belong to deepagents.

class contree_sdk.langchain.ContreeAsyncSandbox(session)

A deepagents sandbox with native asynchronous session operations.

async adelete(file_path)

Async version of delete.

Return type:

DeleteResult

async adownload_files(paths)

Async version of download_files.

Return type:

list[FileDownloadResponse]

async aedit(file_path, old_string, new_string, replace_all=False)

Async version of edit, delegating to aexecute and aupload_files.

Return type:

EditResult

async aexecute(command, *, timeout=None)

Async version of execute.

Return type:

ExecuteResponse

async aexecute_with_offload(command, capture_path, *, max_inline_bytes, max_capture_bytes=None, timeout=None)

Async version of execute_with_offload, delegating to aexecute.

Return type:

ExecuteOffloadResult

async aglob(pattern, path=None)

Async version of glob, delegating to aexecute.

Bounded by ASYNC_GLOB_TIMEOUT: the remote script’s own TIME_BUDGET covers only the walk, so without an outer timeout a wedged sandbox hangs the caller with no upper bound.

Return type:

GlobResult

async agrep(pattern, path=None, glob=None, *, max_count=None)

Async version of grep, delegating to aexecute with timeout guard.

Return type:

GrepResult

async als(path)

Async version of ls, delegating to aexecute.

Return type:

LsResult

async aread(file_path, offset=0, limit=2000)

Async version of read, delegating to aexecute.

Return type:

ReadResult

async aupload_files(files)

Async version of upload_files.

Return type:

list[FileUploadResponse]

async awrite(file_path, content)

Async version of write, delegating to aexecute and aupload_files.

Return type:

WriteResult

delete(file_path)

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.

Parameters:

file_path (str) – Absolute path to the file or directory to delete.

Return type:

DeleteResult

Returns:

DeleteResult with the deleted path on success, or an error if the

path does not exist or the deletion command fails.

download_files(paths)

Download multiple files from the sandbox.

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

Return type:

list[FileDownloadResponse]

async download_one_file(path)

Return type:

FileDownloadResponse

edit(file_path, old_string, new_string, replace_all=False)

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.

Parameters:

• file_path (str) – Absolute path to the file to edit.

• old_string (str) – The exact substring to find.

• new_string (str) – The replacement string.

• replace_all (bool) –

  If True, replace every occurrence.

  If False (default), error when more than one occurrence exists.

Return type:

EditResult

Returns:

EditResult with path and occurrences on success, or error

on failure.

enable_capture_offload: bool = False

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.

execute(command, *, timeout=None)

Execute a command in the sandbox and return ExecuteResponse.

Parameters:

• command (str) – Full shell command string to execute.

• timeout (int | None) –

  Maximum time in seconds to wait for the command to complete.

  If None, uses the backend’s default timeout.

Return type:

ExecuteResponse

Returns:

ExecuteResponse with combined output, exit code, and truncation flag.

execute_with_offload(command, capture_path, *, max_inline_bytes, max_capture_bytes=None, timeout=None)

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

Return type:

ExecuteOffloadResult

Returns:

An ExecuteOffloadResult. offloaded=True when the result was left at capture_path and response.output holds only the preview; offloaded=False when response.output is the complete output.

glob(pattern, path=None)

Structured glob matching returning GlobResult.

Returned paths are absolute (see _absolutize_glob_path), which _check_fs_permission relies on to apply deny rules.

Return type:

GlobResult

grep(pattern, path=None, glob=None, *, max_count=None)

Search file contents for a literal string using grep -F.

Parameters:

• pattern (str) – Literal string to search for (not a regex).

• path (str | None) –

  Directory or file to search in.

  Defaults to “.”.

• glob (str | None) – Optional glob to restrict the search. Patterns without a / (e.g. ‘*.py’) match basenames at any depth via grep –include; patterns containing a / (e.g. ‘src/**/*.py’) match the search-root-relative path via an in-process Python glob.

• max_count (int | None) – Optional total cap on returned matches across all files. None returns every match; an int stops the search once the cap is reached and flags the result with truncated=True.

Return type:

GrepResult

Returns:

GrepResult with a list of GrepMatch dicts, or error on failure.

property id: str

Unique identifier for the sandbox backend.

ls(path)

Structured listing with file metadata using os.scandir.

Return type:

LsResult

read(file_path, offset=0, limit=2000)

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.

Parameters:

• file_path (str) – Absolute path to the file to read.

• offset (int) –

  Starting line number (0-indexed).

  Only applied to text files, and clamped to the start of the file when negative.

• limit (int) –

  Maximum number of lines to return.

  Only applied to text files with content: a non-positive value returns empty content with no pagination metadata. Empty files return the empty-file reminder regardless of limit.

Return type:

ReadResult

Returns:

ReadResult with file_data on success or error on failure.

upload_files(files)

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)

Return type:

list[FileUploadResponse]

write(file_path, content)

Write content to a file, creating or overwriting it if it already exists.

Parameters:

• file_path (str) – Absolute path for the file.

• content (str) – UTF-8 text content to write.

Return type:

WriteResult

Returns:

WriteResult with path on success or error on failure.

class contree_sdk.langchain.ContreeSandbox(session)

A deepagents adapter for any SyncExecutor implementation.

Mutating calls on this adapter are serialized. The executor remains caller-owned. deepagents may dispatch async calls through a thread pool; use ContreeAsyncSandbox for a native async executor.

async adelete(file_path)

Async version of delete.

Return type:

DeleteResult

async adownload_files(paths)

Async version of download_files.

Return type:

list[FileDownloadResponse]

async aedit(file_path, old_string, new_string, replace_all=False)

Async version of edit, delegating to aexecute and aupload_files.

Return type:

EditResult

async aexecute(command, *, timeout=None)

Async version of execute.

Return type:

ExecuteResponse

async aexecute_with_offload(command, capture_path, *, max_inline_bytes, max_capture_bytes=None, timeout=None)

Async version of execute_with_offload, delegating to aexecute.

Return type:

ExecuteOffloadResult

async aglob(pattern, path=None)

Async version of glob, delegating to aexecute.

Bounded by ASYNC_GLOB_TIMEOUT: the remote script’s own TIME_BUDGET covers only the walk, so without an outer timeout a wedged sandbox hangs the caller with no upper bound.

Return type:

GlobResult

async agrep(pattern, path=None, glob=None, *, max_count=None)

Async version of grep, delegating to aexecute with timeout guard.

Return type:

GrepResult

async als(path)

Async version of ls, delegating to aexecute.

Return type:

LsResult

async aread(file_path, offset=0, limit=2000)

Async version of read, delegating to aexecute.

Return type:

ReadResult

async aupload_files(files)

Async version of upload_files.

Return type:

list[FileUploadResponse]

async awrite(file_path, content)

Async version of write, delegating to aexecute and aupload_files.

Return type:

WriteResult

delete(file_path)

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.

Parameters:

file_path (str) – Absolute path to the file or directory to delete.

Return type:

DeleteResult

Returns:

DeleteResult with the deleted path on success, or an error if the

path does not exist or the deletion command fails.

download_files(paths)

Download multiple files from the sandbox.

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

Return type:

list[FileDownloadResponse]

download_one_file(path)

Return type:

FileDownloadResponse

edit(file_path, old_string, new_string, replace_all=False)

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.

Parameters:

• file_path (str) – Absolute path to the file to edit.

• old_string (str) – The exact substring to find.

• new_string (str) – The replacement string.

• replace_all (bool) –

  If True, replace every occurrence.

  If False (default), error when more than one occurrence exists.

Return type:

EditResult

Returns:

EditResult with path and occurrences on success, or error

on failure.

enable_capture_offload: bool = False

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.

execute(command, *, timeout=None)

Execute a command in the sandbox and return ExecuteResponse.

Parameters:

• command (str) – Full shell command string to execute.

• timeout (int | None) –

  Maximum time in seconds to wait for the command to complete.

  If None, uses the backend’s default timeout.

Return type:

ExecuteResponse

Returns:

ExecuteResponse with combined output, exit code, and truncation flag.

execute_with_offload(command, capture_path, *, max_inline_bytes, max_capture_bytes=None, timeout=None)

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

Return type:

ExecuteOffloadResult

Returns:

An ExecuteOffloadResult. offloaded=True when the result was left at capture_path and response.output holds only the preview; offloaded=False when response.output is the complete output.

glob(pattern, path=None)

Structured glob matching returning GlobResult.

Returned paths are absolute (see _absolutize_glob_path), which _check_fs_permission relies on to apply deny rules.

Return type:

GlobResult

grep(pattern, path=None, glob=None, *, max_count=None)

Search file contents for a literal string using grep -F.

Parameters:

• pattern (str) – Literal string to search for (not a regex).

• path (str | None) –

  Directory or file to search in.

  Defaults to “.”.

• glob (str | None) – Optional glob to restrict the search. Patterns without a / (e.g. ‘*.py’) match basenames at any depth via grep –include; patterns containing a / (e.g. ‘src/**/*.py’) match the search-root-relative path via an in-process Python glob.

• max_count (int | None) – Optional total cap on returned matches across all files. None returns every match; an int stops the search once the cap is reached and flags the result with truncated=True.

Return type:

GrepResult

Returns:

GrepResult with a list of GrepMatch dicts, or error on failure.

property id: str

Unique identifier for the sandbox backend.

ls(path)

Structured listing with file metadata using os.scandir.

Return type:

LsResult

read(file_path, offset=0, limit=2000)

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.

Parameters:

• file_path (str) – Absolute path to the file to read.

• offset (int) –

  Starting line number (0-indexed).

  Only applied to text files, and clamped to the start of the file when negative.

• limit (int) –

  Maximum number of lines to return.

  Only applied to text files with content: a non-positive value returns empty content with no pagination metadata. Empty files return the empty-file reminder regardless of limit.

Return type:

ReadResult

Returns:

ReadResult with file_data on success or error on failure.

upload_files(files)

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)

Return type:

list[FileUploadResponse]

write(file_path, content)

Write content to a file, creating or overwriting it if it already exists.

Parameters:

• file_path (str) – Absolute path for the file.

• content (str) – UTF-8 text content to write.

Return type:

WriteResult

Returns:

WriteResult with path on success or error on failure.