cayu.workspaces.e2b

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

DEFAULT_E2B_WORKSPACE_LIST_DEPTH

from cayu.workspaces import DEFAULT_E2B_WORKSPACE_LIST_DEPTH

DEFAULT_E2B_WORKSPACE_LIST_DEPTH = 64

Release source · Runtime guarantees · Capability guides

DEFAULT_E2B_WORKSPACE_LIST_LIMIT

from cayu.workspaces import DEFAULT_E2B_WORKSPACE_LIST_LIMIT

DEFAULT_E2B_WORKSPACE_LIST_LIMIT = 500

Release source · Runtime guarantees · Capability guides

DEFAULT_E2B_WORKSPACE_READ_LIMIT_BYTES

from cayu.workspaces import DEFAULT_E2B_WORKSPACE_READ_LIMIT_BYTES

DEFAULT_E2B_WORKSPACE_READ_LIMIT_BYTES = 256 * 1024

Release source · Runtime guarantees · Capability guides

E2BWorkspace

from cayu.workspaces import E2BWorkspace

Workspace backed by an E2B sandbox.

read_bytes/write_bytes/delete run through a guest-side guard program (see cayu.workspaces._guest_guard) that resolves and opens every path component atomically with O_NOFOLLOW inside the sandbox, so a co-resident guest process cannot race a host-side symlink check (TOCTOU). Those operations require python3 inside the guest and run as the runner’s default exec user (the user override applies only to list). list uses E2B’s native filesystem API and is advisory: symlinked entries are skipped best-effort, and any subsequent read is re-checked by the guard. If the native traversal reaches default_list_depth, the result is explicitly marked incomplete because the SDK does not report whether deeper entries were omitted.

Bases: RunnerBoundWorkspace.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
id	str	required

reference_binding (method)

E2BWorkspace.reference_binding() -> WorkspaceReferenceBinding

Bind application data to this workspace incarnation.

The default is object-lifetime scoped and fails closed after reopening. Durable adapters may override this method only when they can preserve an incarnation across recovery and rotate it on replacement. Never restore a generation from the application reference being validated.

read_bytes (method)

async E2BWorkspace.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> WorkspaceReadResult

bounded_read_limit (method)

E2BWorkspace.bounded_read_limit(max_bytes: int) -> int

write_bytes (method)

async E2BWorkspace.write_bytes(path: str, content: bytes) -> None

delete (method)

async E2BWorkspace.delete(path: str) -> None

create_bytes (method)

async E2BWorkspace.create_bytes(path: str, content: bytes) -> WorkspaceMutationResult

replace_bytes (method)

async E2BWorkspace.replace_bytes(path: str, content: bytes, *, expected_revision: str) -> WorkspaceMutationResult

delete_if_revision (method)

async E2BWorkspace.delete_if_revision(path: str, *, expected_revision: str) -> WorkspaceMutationResult

require_absent (method)

async E2BWorkspace.require_absent(path: str) -> None

move_if_revision (method)

async E2BWorkspace.move_if_revision(source_path: str, destination_path: str, *, expected_source_revision: str, require_destination_absent: bool=True) -> WorkspaceMoveResult

list (method)

async E2BWorkspace.list(pattern: str='**/*', *, limit: int | None=None) -> WorkspaceListResult

list_git_entries (method)

async E2BWorkspace.list_git_entries(*, limit: int) -> WorkspaceGitEntryListResult

List regular files and symlinks without following either entry type.

resource_key (property)

E2BWorkspace.resource_key() -> tuple[object, ...] | None

tar_copy_policy_identity (method)

E2BWorkspace.tar_copy_policy_identity() -> tuple[object, ...] | None

Return an exact, content-free identity for tar copy security policy.

SyncBinding only shares a sealed archive when both adapters opt in with stable identities. Implementations must change the identity whenever path exclusions, archive parsing, or extraction policy changes. None conservatively disables sharing for this adapter.

bounded_tar_stream_reader (method)

E2BWorkspace.bounded_tar_stream_reader() -> BoundedTarStreamReader | None

Return an explicit bounded streaming-tar reader capability, if any.

tar_stream_writer (method)

E2BWorkspace.tar_stream_writer() -> TarStreamWriter | None

Return an explicit streaming-tar writer capability, if any.

branch_capabilities (method)

E2BWorkspace.branch_capabilities() -> WorkspaceBranchCapabilities

Return explicit workspace-branch guarantees for this adapter.

Unsupported is the compatibility default. Capability must be declared by the exact adapter instance and is never inferred from adjacent filesystem, snapshot, runner, sync, reconnect, or Git behavior.

branch_lifecycle_summary (method)

E2BWorkspace.branch_lifecycle_summary() -> WorkspaceBranchLifecycleSummary

Return bounded lifecycle states for branch handles attached here.

create_branch (method)

async E2BWorkspace.create_branch(request: WorkspaceBranchRequest) -> WorkspaceBranchCreationResult

Create an isolated bounded workspace branch when supported.

Branching is an optional capability rather than an abstract workspace requirement. Backends that do not implement the complete isolation and publication contract return a typed unsupported result.

is_bound_to_runner (method)

E2BWorkspace.is_bound_to_runner(runner: Runner) -> bool

runner_cwd (property)

E2BWorkspace.runner_cwd() -> str

bound_runner_resource_key (property)

E2BWorkspace.bound_runner_resource_key() -> tuple[object, ...]

init (method)

E2BWorkspace.__init__(runner: Runner, *, root: str=DEFAULT_E2B_CWD, workspace_id: str | None=None, default_read_limit_bytes: int=DEFAULT_E2B_WORKSPACE_READ_LIMIT_BYTES, default_list_limit: int=DEFAULT_E2B_WORKSPACE_LIST_LIMIT, default_list_depth: int=DEFAULT_E2B_WORKSPACE_LIST_DEPTH, user: str | None=None, request_timeout_s: float | None=None) -> None

resolve (method)

E2BWorkspace.resolve(path: str) -> str

Release source · Runtime guarantees · Capability guides