cayu.workspaces.microsandbox

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_MICROSANDBOX_WORKSPACE_LIST_LIMIT

from cayu.workspaces import DEFAULT_MICROSANDBOX_WORKSPACE_LIST_LIMIT

DEFAULT_MICROSANDBOX_WORKSPACE_LIST_LIMIT = 500

Release source · Runtime guarantees · Capability guides

DEFAULT_MICROSANDBOX_WORKSPACE_READ_LIMIT_BYTES

from cayu.workspaces import DEFAULT_MICROSANDBOX_WORKSPACE_READ_LIMIT_BYTES

DEFAULT_MICROSANDBOX_WORKSPACE_READ_LIMIT_BYTES = 256 * 1024

Release source · Runtime guarantees · Capability guides

MicrosandboxWorkspace

from cayu.workspaces import MicrosandboxWorkspace

Workspace backed by a Microsandbox 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 realpath check (TOCTOU). Those operations require python3 inside the guest. list uses Microsandbox’s native filesystem API with best-effort realpath containment; any subsequent read is re-checked by the guard.

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)

MicrosandboxWorkspace.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 MicrosandboxWorkspace.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> WorkspaceReadResult

bounded_read_limit (method)

MicrosandboxWorkspace.bounded_read_limit(max_bytes: int) -> int

write_bytes (method)

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

delete (method)

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

create_bytes (method)

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

replace_bytes (method)

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

delete_if_revision (method)

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

require_absent (method)

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

move_if_revision (method)

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

list (method)

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

list_git_entries (method)

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

List regular files and symlinks without following either entry type.

resource_key (property)

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

tar_copy_policy_identity (method)

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

MicrosandboxWorkspace.bounded_tar_stream_reader() -> BoundedTarStreamReader | None

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

tar_stream_writer (method)

MicrosandboxWorkspace.tar_stream_writer() -> TarStreamWriter | None

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

branch_capabilities (method)

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

MicrosandboxWorkspace.branch_lifecycle_summary() -> WorkspaceBranchLifecycleSummary

Return bounded lifecycle states for branch handles attached here.

create_branch (method)

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

MicrosandboxWorkspace.is_bound_to_runner(runner: Runner) -> bool

runner_cwd (property)

MicrosandboxWorkspace.runner_cwd() -> str

bound_runner_resource_key (property)

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

init (method)

MicrosandboxWorkspace.__init__(runner: Runner, *, root: str=DEFAULT_MICROSANDBOX_CWD, workspace_id: str | None=None, default_read_limit_bytes: int=DEFAULT_MICROSANDBOX_WORKSPACE_READ_LIMIT_BYTES, default_list_limit: int=DEFAULT_MICROSANDBOX_WORKSPACE_LIST_LIMIT) -> None

resolve (method)

MicrosandboxWorkspace.resolve(path: str) -> str

Release source · Runtime guarantees · Capability guides