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

from cayu.runners import DEFAULT_E2B_CWD

DEFAULT_E2B_CWD = '/home/user/workspace'

Release source · Runtime guarantees · Capability guides

`DEFAULT_E2B_HANDOFF_CLEANUP_TIMEOUT_SECONDS`

from cayu.runners import DEFAULT_E2B_HANDOFF_CLEANUP_TIMEOUT_SECONDS

DEFAULT_E2B_HANDOFF_CLEANUP_TIMEOUT_SECONDS = 15.0

Release source · Runtime guarantees · Capability guides

`DEFAULT_E2B_HANDOFF_TIMEOUT_SECONDS`

from cayu.runners import DEFAULT_E2B_HANDOFF_TIMEOUT_SECONDS

DEFAULT_E2B_HANDOFF_TIMEOUT_SECONDS = 120.0

Release source · Runtime guarantees · Capability guides

`DEFAULT_E2B_PROTECTED_FILE_MAX_BYTES`

from cayu.runners import DEFAULT_E2B_PROTECTED_FILE_MAX_BYTES

DEFAULT_E2B_PROTECTED_FILE_MAX_BYTES = 64 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`E2B_SANDBOX_ID_MAX_BYTES`

from cayu.runners import E2B_SANDBOX_ID_MAX_BYTES

E2B_SANDBOX_ID_MAX_BYTES = 256

Release source · Runtime guarantees · Capability guides

`E2BCloseAction`

from cayu.runners import E2BCloseAction

E2BCloseAction = Literal['kill', 'detach', 'none']

Release source · Runtime guarantees · Capability guides

`E2BGuestHandoffError`

from cayu.runners import E2BGuestHandoffError

A secret-safe failure while establishing the E2B guest boundary.

Bases: RuntimeError.

init (method)

E2BGuestHandoffError.__init__(*, phase: E2BGuestHandoffPhase, reason: str, exit_code: int | None=None) -> None

Release source · Runtime guarantees · Capability guides

`E2BGuestHandoffPhase`

from cayu.runners import E2BGuestHandoffPhase

E2BGuestHandoffPhase = Literal['hardening', 'bootstrap', 'guest_setup', 'guest_probe', 'verification']

Release source · Runtime guarantees · Capability guides

`E2BGuestProvisioner`

from cayu.runners import E2BGuestProvisioner

Short-lived typed root capability issued during trusted E2B bootstrap.

Instances are created only by E2BRunner.create_hardened and are sealed before guest callbacks run. The capability intentionally exposes no arbitrary root command or native filesystem handle.

init (method)

E2BGuestProvisioner.__init__(sandbox: Any, *, default_cwd: str, guest_user: str, operation_timeout_s: float, max_file_bytes: int, allow_existing_exact: bool=False, _construction_token: object | None=None) -> None

is_sealed (property)

E2BGuestProvisioner.is_sealed() -> bool

install_directory (method)

async E2BGuestProvisioner.install_directory(path: str, *, mode: int=493) -> None

Create one protected root-owned directory and register its verification.

install_file (method)

async E2BGuestProvisioner.install_file(path: str, content: str | bytes, *, mode: int=292) -> None

Install one protected root-owned file and register its verification.

Release source · Runtime guarantees · Capability guides

`E2BRunner`

from cayu.runners import E2BRunner

Executes commands in an E2B cloud sandbox.

E2B’s command API executes command strings through Bash. Cayu preserves its process-form contract by shell-quoting argv with shlex.join(...) before handing the command to E2B.

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
`pending_command_settlement_cancellation_safe`	`class attribute`	`True`
`isolation`	`class attribute`	`'e2b'`
`default_cwd`	`str`	`'/'`
`system_execution_mode`	`RunnerSystemExecutionMode`	`'shared'`

workload_authority (method)

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

Return runner-owned authority for an exact provisioned workload.

execution_environment_authority (method)

E2BRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

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

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

E2BRunner.browser_recording_supported() -> bool

Declare that this runner captures and finalizes browser recordings.

execution_profile_identity (property)

E2BRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

preflight_exec (method)

E2BRunner.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 E2B request without provider activity.

exec (method)

async E2BRunner.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 E2BRunner.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 E2BRunner.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 E2BRunner.close() -> None

Apply the configured lifecycle action once.

await_pending_command_settlement (method)

async E2BRunner.await_pending_command_settlement() -> bool

Wait for every deferred late-start cleanup known to this runner.

refresh_execution_admission (method)

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

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

E2BRunner.execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

Read evidence for an explicit, caller-owned requirement set.

This snapshot must not dispatch work or mutate a shared probe plan. The default reads the runner’s existing candidate and makes no new claim from the supplied requirements alone.

execution_admission_observer (method)

E2BRunner.execution_admission_observer(requirements: ExecutionRequirements) -> RunnerExecutionAdmissionObserver

Create a request-scoped evidence owner for this exact runner.

Creation is side-effect-free. The lifecycle owns collection, renewal, and any transferred settlement tasks; the observer cannot admit work.

collect_execution_admission_candidate_for (method)

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

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

is_closed (property)

E2BRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

E2BRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

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

binary_stream_capability (method)

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

E2BRunner.reopen_exec() -> None

Accept an operator’s positive proof that no deferred command remains.

resolve_cwd (method)

E2BRunner.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 E2BRunner.__aenter__() -> Self

aexit (method)

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

init (method)

E2BRunner.__init__(sandbox: Any, *, sandbox_id: str | None=None, default_cwd: str=DEFAULT_E2B_CWD, close_action: E2BCloseAction='none', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, env_overlay: Mapping[str, str] | None=None, exec_user: str | None=None, e2b_module: ModuleType | Any | None=None) -> None

create (method)

async E2BRunner.create(*, template: str | None=None, sandbox_timeout_s: int | None=None, default_cwd: str=DEFAULT_E2B_CWD, close_action: E2BCloseAction='kill', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, ensure_default_cwd: bool=True, metadata: dict[str, str] | None=None, envs: dict[str, str] | None=None, env_overlay: Mapping[str, str] | None=None, exec_user: str | None=None, secure: bool=True, allow_internet_access: bool=True, network: Any | None=None, lifecycle: Any | None=None, volume_mounts: Any | None=None, e2b_module: ModuleType | Any | None=None, **api_options: Any) -> E2BRunner

Create an E2B sandbox and return a runner bound to it.

Provider-specific options intentionally pass through to E2B so Cayu does not invent a weaker abstraction over templates, networking, lifecycle, or volumes.

create_hardened (method)

async E2BRunner.create_hardened(*, template: str | None=None, sandbox_timeout_s: int | None=None, default_cwd: str=DEFAULT_E2B_CWD, close_action: E2BCloseAction='kill', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, metadata: dict[str, str] | None=None, env_overlay: Mapping[str, str] | None=None, guest_user: str='user', network: Any | None=None, lifecycle: Any | None=None, volume_mounts: Any | None=None, handoff_timeout_s: float=DEFAULT_E2B_HANDOFF_TIMEOUT_SECONDS, cleanup_timeout_s: float=DEFAULT_E2B_HANDOFF_CLEANUP_TIMEOUT_SECONDS, max_protected_file_bytes: int=DEFAULT_E2B_PROTECTED_FILE_MAX_BYTES, bootstrap: Callable[[E2BGuestProvisioner], Awaitable[None]] | None=None, guest_setup: Callable[[E2BRunner], Awaitable[None]] | None=None, guest_probe: Callable[[E2BRunner], Awaitable[None]] | None=None, handoff_id: str | None=None, e2b_module: ModuleType | Any | None=None, **api_options: Any) -> E2BRunner

Create, harden, verify, and complete a one-way capability handoff.

bootstrap receives the only public privileged capability. It may install protected files or directories, then is sealed before guest_setup and guest_probe run through the guest-pinned runner. The complete create/handoff sequence is bounded by handoff_timeout_s. Any failure performs bounded sandbox rollback; an ambiguous create is reconciled by a unique provider metadata marker.

Public Internet access is always disabled. network remains available for explicit provider-native allowlists, such as the one proxy endpoint used by Cayu’s virtual-egress adapter.

recover_hardened (method)

async E2BRunner.recover_hardened(handoff_id: str, *, sandbox_timeout_s: int | None=None, default_cwd: str=DEFAULT_E2B_CWD, close_action: E2BCloseAction='kill', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, env_overlay: Mapping[str, str] | None=None, guest_user: str='user', handoff_timeout_s: float=DEFAULT_E2B_HANDOFF_TIMEOUT_SECONDS, cleanup_timeout_s: float=DEFAULT_E2B_HANDOFF_CLEANUP_TIMEOUT_SECONDS, bootstrap: Callable[[E2BGuestProvisioner], Awaitable[None]] | None=None, guest_setup: Callable[[E2BRunner], Awaitable[None]] | None=None, guest_probe: Callable[[E2BRunner], Awaitable[None]] | None=None, e2b_module: ModuleType | Any | None=None, **api_options: Any) -> E2BRunner

Reattach only to the unique sandbox owned by a durable handoff id.

Recovery never creates. Absence therefore remains ambiguous instead of authorizing a second provider allocation after acknowledgement loss.

from_existing (method)

async E2BRunner.from_existing(sandbox_id: str, *, sandbox_timeout_s: int | None=None, default_cwd: str=DEFAULT_E2B_CWD, close_action: E2BCloseAction='none', cancel_timeout_s: float | None=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS, cancellation_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY, timeout_cleanup: RunnerCleanupPolicy=DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY, ensure_default_cwd: bool=True, env_overlay: Mapping[str, str] | None=None, exec_user: str | None=None, e2b_module: ModuleType | Any | None=None, **api_options: Any) -> E2BRunner

Attach to an existing E2B sandbox by id.

drain_failed_creations (method)

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

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

detach_preserving_allocation (method)

async E2BRunner.detach_preserving_allocation() -> None

Close this local capability without deleting the provider sandbox.

fence_guest_processes_for_egress_cutover (method)

async E2BRunner.fence_guest_processes_for_egress_cutover() -> None

Terminate guest-owned processes while preserving sandbox/workspace identity.

update_egress_network (method)

async E2BRunner.update_egress_network(network: Any) -> None

Replace the running sandbox network through E2B’s control plane.

filesystem (method)

E2BRunner.filesystem() -> Any

Return the native E2B filesystem API for workspace adapters.

Release source · Runtime guarantees · Capability guides

`E2BWorkspaceCapability`

from cayu.runners import E2BWorkspaceCapability

Native E2B filesystem access without runner lifecycle authority.

Bases: RunnerWorkspaceCapability.

resource_key (property)

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

Stable identity of the sandbox that backs this capability.

sandbox_id (property)

E2BWorkspaceCapability.sandbox_id() -> str

Provider sandbox id used for truthful workspace identity.

get_info (method)

async E2BWorkspaceCapability.get_info(path: str, *, user: str | None, request_timeout_s: float | None) -> E2BWorkspaceEntry

Return a normalized Cayu-owned entry for one guest path.

list_entries (method)

async E2BWorkspaceCapability.list_entries(path: str, *, depth: int, user: str | None, request_timeout_s: float | None) -> Sequence[E2BWorkspaceEntry]

List normalized Cayu-owned entries below one guest path.

Release source · Runtime guarantees · Capability guides

`E2BWorkspaceEntry`

from cayu.runners import E2BWorkspaceEntry

Cayu-owned normalized view of one E2B filesystem entry.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`path`	`str \| None`	`required`
`type`	`str \| None`	`required`
`symlink_target`	`str \| None`	`None`

from_provider_entry (method)

E2BWorkspaceEntry.from_provider_entry(entry: Any) -> E2BWorkspaceEntry

Release source · Runtime guarantees · Capability guides