cayu.runners.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_CWD

from cayu.runners import DEFAULT_MICROSANDBOX_CWD

DEFAULT_MICROSANDBOX_CWD = '/workspace'

Release source · Runtime guarantees · Capability guides

DEFAULT_MICROSANDBOX_IMAGE

from cayu.runners import DEFAULT_MICROSANDBOX_IMAGE

DEFAULT_MICROSANDBOX_IMAGE = 'python:3.13'

Release source · Runtime guarantees · Capability guides

DEFAULT_MICROSANDBOX_RECONNECT_TIMEOUT_SECONDS

from cayu.runners import DEFAULT_MICROSANDBOX_RECONNECT_TIMEOUT_SECONDS

DEFAULT_MICROSANDBOX_RECONNECT_TIMEOUT_SECONDS = 15.0

Release source · Runtime guarantees · Capability guides

DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS

from cayu.runners import DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS

DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS = 5.0

Release source · Runtime guarantees · Capability guides

MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS

from cayu.runners import MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS

MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS = 1.0

Release source · Runtime guarantees · Capability guides

MICROSANDBOX_NAME_MAX_BYTES

from cayu.runners import MICROSANDBOX_NAME_MAX_BYTES

MICROSANDBOX_NAME_MAX_BYTES = 128

Release source · Runtime guarantees · Capability guides

MicrosandboxCleanupError

from cayu.runners import MicrosandboxCleanupError

Terminal bounded Microsandbox lifecycle cleanup failure.

Bases: RuntimeError.

init (method)

MicrosandboxCleanupError.__init__(message: str, *, diagnostic: dict[str, Any]) -> None

Release source · Runtime guarantees · Capability guides

MicrosandboxCloseAction

from cayu.runners import MicrosandboxCloseAction

MicrosandboxCloseAction = Literal['remove', 'stop', 'detach', 'none']

Release source · Runtime guarantees · Capability guides

MicrosandboxReconnectIdentityError

from cayu.runners import MicrosandboxReconnectIdentityError

The provider handle does not match durable reconnect identity.

Bases: ValueError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

MicrosandboxRunner

from cayu.runners import MicrosandboxRunner

Executes commands in a Microsandbox microVM sandbox.

The runner does not inherit the trusted host process environment. Pass explicit env values, preferably resolved at the environment/vault boundary. Commands are serialized so a guest-agent liveness transition completes before another guest launch. reopen_exec() does not clear confirmed guest-agent unavailability; reconnect with a new runner instead.

Bases: Runner.

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
isolation	class attribute	'microsandbox'
default_cwd	str	'/'
system_execution_mode	RunnerSystemExecutionMode	'shared'

workload_authority (method)

MicrosandboxRunner.workload_authority(name: str) -> RunnerWorkloadAuthority | None

Return runner-owned authority for an exact provisioned workload.

execution_environment_authority (method)

MicrosandboxRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

MicrosandboxRunner.output_secret_values_present() -> bool | None

Report whether command output can contain runner-owned secret values.

None is fail-closed unknown authority. Wrappers must merge their own secret registry with the wrapped runner’s declaration.

browser_control_endpoint_reachable (method)

MicrosandboxRunner.browser_control_endpoint_reachable(endpoint: str) -> bool | None

Report whether the guest can dial a browser control or recording endpoint.

None makes no declaration: reachability then rests on deployment configuration, as with Docker’s colocated control-server alias. A runner whose guest has a fixed, verified control path returns False for every endpoint outside it, so no control credential is sent there.

browser_recording_supported (method)

MicrosandboxRunner.browser_recording_supported() -> bool

Declare that this runner captures and finalizes browser recordings.

execution_profile_identity (property)

MicrosandboxRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

preflight_exec (method)

MicrosandboxRunner.preflight_exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> None

Validate the complete Microsandbox request without provider activity.

exec (method)

async MicrosandboxRunner.exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

exec_redacted (method)

async MicrosandboxRunner.exec_redacted(command: ExecCommand, *, redactor: SecretRedactor, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

exec_system (method)

async MicrosandboxRunner.exec_system(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute a control-plane lifecycle command on the declared system lane.

close (method)

async MicrosandboxRunner.close() -> None

Apply the configured lifecycle action once.

await_pending_command_settlement (method)

async MicrosandboxRunner.await_pending_command_settlement() -> bool

Wait for command cleanup deferred beyond an exec result.

Return True only when every command-cleanup operation dispatched before this call has positively reached its terminal boundary. This hook is consulted only after a runner explicitly reports deferred cleanup. Such runners must override it; the default fails closed so an unknown extension cannot turn absence of evidence into quiescence.

refresh_execution_admission (method)

async MicrosandboxRunner.refresh_execution_admission() -> None

Re-probe live admission evidence when supported by this runner.

The default makes no new claim. A supporting implementation may renew only the exact runner represented by its current admission candidate; it must not replace the environment, immutable image, or toolchain identity. It must also settle every dispatched probe, or transfer an authenticated settlement owner, before returning or raising. Callers must re-read and validate the complete candidate after this hook; requesting renewal never authorizes execution by itself.

execution_admission_candidate (method)

MicrosandboxRunner.execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Return explicit provider-neutral admission evidence, when implemented.

The default deliberately makes no capability claim. Runtimes must fail closed when a workload requires evidence that its selected runner does not provide.

collect_execution_admission_candidate (method)

async MicrosandboxRunner.collect_execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Collect final evidence after lifecycle-owned mutating setup completes.

The default adapts existing side-effect-free snapshot implementations. Runners whose evidence depends on live external state override this hook and complete or positively transfer settlement ownership for every dispatched probe before returning or raising for any reason.

execution_admission_candidate_for (method)

MicrosandboxRunner.execution_admission_candidate_for(requirements)

execution_admission_observer (method)

MicrosandboxRunner.execution_admission_observer(requirements)

collect_execution_admission_candidate_for (method)

async MicrosandboxRunner.collect_execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

Collect final request-bound evidence under lifecycle ownership.

Requirements are input, never proof. Implementations must isolate concurrent requirement sets and settle or positively transfer every dispatched probe under the same contract as the ordinary collector.

resource_key (property)

MicrosandboxRunner.resource_key() -> tuple[object, ...]

is_closed (property)

MicrosandboxRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

MicrosandboxRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

MicrosandboxRunner.workspace_capability(capability_type: type[RunnerWorkspaceCapabilityT]) -> RunnerWorkspaceCapabilityT | None

binary_stream_capability (method)

MicrosandboxRunner.binary_stream_capability() -> RunnerBinaryStreamCapability | None

Return bounded binary execution when its support is already known.

Discovery must not provision a runner or execute commands. Wrappers with an unknown target return None until support is established, so workspace transfers can retain their text transport fallback. Returned capabilities must preserve the owning runner’s execution fences.

reopen_exec (method)

MicrosandboxRunner.reopen_exec() -> None

Clear an intentional execution fence on an otherwise-open runner.

This is not recovery authority for inconclusive command cleanup. Poisoned instances cannot be reopened, including after a late cleanup acknowledgement; a new independently verified allocation owner is needed.

resolve_cwd (method)

MicrosandboxRunner.resolve_cwd(cwd: str | None=None) -> str

Resolve a requested cwd to a canonical path inside the runner root.

Relative requests are resolved against default_cwd. An absolute input is accepted only when it is already contained by the runner root, making canonicalization idempotent for policy-authorized execution.

aenter (method)

async MicrosandboxRunner.__aenter__() -> Self

aexit (method)

async MicrosandboxRunner.__aexit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> bool

init (method)

MicrosandboxRunner.__init__(sandbox: Any, *, name: str, default_cwd: str=DEFAULT_MICROSANDBOX_CWD, close_action: MicrosandboxCloseAction='none', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, liveness_timeout_s: float=MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, remove_timeout_s: float=DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS, env_overlay: Mapping[str, str] | None=None, sandbox_module: ModuleType | Any | None=None, _restarted_from_stopped: bool=False) -> None

create (method)

async MicrosandboxRunner.create(name: str, *, image: Any=DEFAULT_MICROSANDBOX_IMAGE, default_cwd: str=DEFAULT_MICROSANDBOX_CWD, close_action: MicrosandboxCloseAction='remove', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, liveness_timeout_s: float=MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, remove_timeout_s: float=DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS, ensure_default_cwd: bool=True, env_overlay: Mapping[str, str] | None=None, sandbox_module: ModuleType | Any | None=None, **sandbox_options: Any) -> MicrosandboxRunner

Create a sandbox and return a runner bound to it.

Guest networking defaults to microsandbox.Network.none(). Pass an explicit provider network policy to opt into another creation-time network contract.

Other provider-specific options are passed through unchanged, including volumes, resources, labels, secrets, and replace behavior. An explicit network policy is also forwarded unchanged.

from_existing (method)

async MicrosandboxRunner.from_existing(name: str, *, default_cwd: str=DEFAULT_MICROSANDBOX_CWD, close_action: MicrosandboxCloseAction='none', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, liveness_timeout_s: float=MICROSANDBOX_LIVENESS_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, remove_timeout_s: float=DEFAULT_MICROSANDBOX_REMOVE_TIMEOUT_SECONDS, env_overlay: Mapping[str, str] | None=None, sandbox_module: ModuleType | Any | None=None, reconnect_timeout_s: float=DEFAULT_MICROSANDBOX_RECONNECT_TIMEOUT_SECONDS, expected_created_at: float | None=None) -> MicrosandboxRunner

Attach to an existing Microsandbox sandbox by name.

The sandbox creator owns its creation-time network contract. Attaching does not inspect, replace, or strengthen that network policy.

closed (property)

MicrosandboxRunner.closed() -> bool

Whether this runner instance has completed its lifecycle action.

restarted_from_stopped (property)

MicrosandboxRunner.restarted_from_stopped() -> bool

Whether this attachment made a stopped allocation executable.

drain_failed_creations (method)

async MicrosandboxRunner.drain_failed_creations(*, timeout_s: float=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS) -> int

Retry retained process-local constructor rollback; return unsettled count.

drain_failed_attachments (method)

async MicrosandboxRunner.drain_failed_attachments(*, timeout_s: float=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS) -> int

Retry exact retained attachment restoration; return the unsettled count.

last_cleanup_diagnostic (property)

MicrosandboxRunner.last_cleanup_diagnostic() -> dict[str, Any] | None

Return the latest lifecycle cleanup diagnostic, if close was attempted.

filesystem (method)

MicrosandboxRunner.filesystem() -> Any

Return the native Microsandbox filesystem API for workspace adapters.

real_path (method)

async MicrosandboxRunner.real_path(path: str) -> str

Resolve a guest path through Microsandbox’s SFTP realpath API.

The SSH client and SFTP channel are opened once and cached for reuse: listing a directory resolves one path per entry, and a fresh SSH handshake per call made large listings pathologically slow (~500 handshakes to resolve 500 files). On any session error the cached session is dropped and the call is retried once against a fresh handshake, so a transient disconnect does not fail the whole listing.

Release source · Runtime guarantees · Capability guides

MicrosandboxUnavailableError

from cayu.runners import MicrosandboxUnavailableError

The Microsandbox guest agent was confirmed unreachable after a command.

Bases: RunnerUnavailableError.

init (method)

MicrosandboxUnavailableError.__init__(*, sandbox_name: str, last_command: Mapping[str, Any], probe: Mapping[str, Any]) -> None

Release source · Runtime guarantees · Capability guides

MicrosandboxWorkspaceCapability

from cayu.runners import MicrosandboxWorkspaceCapability

Native Microsandbox filesystem access without runner lifecycle authority.

Bases: RunnerWorkspaceCapability.

resource_key (property)

MicrosandboxWorkspaceCapability.resource_key() -> tuple[object, ...]

Stable identity of the sandbox that backs this capability.

sandbox_name (property)

MicrosandboxWorkspaceCapability.sandbox_name() -> str

Provider sandbox name used for truthful workspace identity.

list_entries (method)

async MicrosandboxWorkspaceCapability.list_entries(path: str) -> Sequence[MicrosandboxWorkspaceEntry]

List normalized Cayu-owned entries for one guest directory.

real_path (method)

async MicrosandboxWorkspaceCapability.real_path(path: str) -> str

Resolve a canonical guest path through the provider transport.

Release source · Runtime guarantees · Capability guides

MicrosandboxWorkspaceEntry

from cayu.runners import MicrosandboxWorkspaceEntry

Cayu-owned normalized view of one Microsandbox filesystem entry.

Decorators: @dataclass(frozen=True).

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
path	str | None	required
kind	str | None	required

from_provider_entry (method)

MicrosandboxWorkspaceEntry.from_provider_entry(entry: Any) -> MicrosandboxWorkspaceEntry

Release source · Runtime guarantees · Capability guides