cayu.runners.aws_lambda_microvm

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_LAMBDA_MICROVM_CWD

from cayu.runners import DEFAULT_LAMBDA_MICROVM_CWD

DEFAULT_LAMBDA_MICROVM_CWD = '/workspace'

Release source · Runtime guarantees · Capability guides

HttpxLambdaMicroVMEndpointTransport

from cayu.runners import HttpxLambdaMicroVMEndpointTransport

Authenticated HTTPS transport for the Cayu MicroVM sidecar.

init (method)

HttpxLambdaMicroVMEndpointTransport.__init__() -> None

aclose (method)

async HttpxLambdaMicroVMEndpointTransport.aclose() -> None

health (method)

async HttpxLambdaMicroVMEndpointTransport.health(*, endpoint: str, token: str, timeout_s: float) -> Mapping[str, Any]

start_command (method)

async HttpxLambdaMicroVMEndpointTransport.start_command(*, endpoint: str, token: str, command_id: str, payload: dict[str, Any], timeout_s: float) -> Mapping[str, Any]

get_command (method)

async HttpxLambdaMicroVMEndpointTransport.get_command(*, endpoint: str, token: str, command_id: str, timeout_s: float) -> Mapping[str, Any]

cancel_command (method)

async HttpxLambdaMicroVMEndpointTransport.cancel_command(*, endpoint: str, token: str, command_id: str, timeout_s: float) -> Mapping[str, Any]

release_command (method)

async HttpxLambdaMicroVMEndpointTransport.release_command(*, endpoint: str, token: str, command_id: str, timeout_s: float) -> Mapping[str, Any]

claim_owner (method)

async HttpxLambdaMicroVMEndpointTransport.claim_owner(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

check_owner (method)

async HttpxLambdaMicroVMEndpointTransport.check_owner(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

acquire_lifecycle (method)

async HttpxLambdaMicroVMEndpointTransport.acquire_lifecycle(*, endpoint: str, token: str, claim_id: str, action: str, timeout_s: float) -> Mapping[str, Any]

release_lifecycle (method)

async HttpxLambdaMicroVMEndpointTransport.release_lifecycle(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

configure_control_relay (method)

async HttpxLambdaMicroVMEndpointTransport.configure_control_relay(*, endpoint: str, token: str, owner_claim: str, host: str, port: int, timeout_s: float) -> Mapping[str, Any]

Release source · Runtime guarantees · Capability guides

LambdaMicroVMAllocationTerminated

from cayu.runners import LambdaMicroVMAllocationTerminated

An idempotent replay resolved an allocation that is no longer usable.

Bases: LambdaMicroVMError.

init (method)

LambdaMicroVMAllocationTerminated.__init__(message: str, *, microvm_id: str, state: str) -> None

Release source · Runtime guarantees · Capability guides

LambdaMicroVMBrowserWorkloadError

from cayu.runners import LambdaMicroVMBrowserWorkloadError

The MicroVM image does not contain this Cayu release’s browser worker.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMClientTokenConflict

from cayu.runners import LambdaMicroVMClientTokenConflict

AWS rejected a client-token replay because its request parameters changed.

No MicroVM is created by the rejected request. The earlier allocation, if any, remains owned by the original request and must not be replaced.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMCloseAction

from cayu.runners import LambdaMicroVMCloseAction

LambdaMicroVMCloseAction = Literal['terminate', 'suspend', 'none']

Release source · Runtime guarantees · Capability guides

LambdaMicroVMEndpointTransientError

from cayu.runners import LambdaMicroVMEndpointTransientError

A transport failure eligible for bounded command-state read retry only.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMEndpointTransport

from cayu.runners import LambdaMicroVMEndpointTransport

Bases: Protocol.

health (method)

async LambdaMicroVMEndpointTransport.health(*, endpoint: str, token: str, timeout_s: float) -> Mapping[str, Any]

start_command (method)

async LambdaMicroVMEndpointTransport.start_command(*, endpoint: str, token: str, command_id: str, payload: dict[str, Any], timeout_s: float) -> Mapping[str, Any]

get_command (method)

async LambdaMicroVMEndpointTransport.get_command(*, endpoint: str, token: str, command_id: str, timeout_s: float) -> Mapping[str, Any]

cancel_command (method)

async LambdaMicroVMEndpointTransport.cancel_command(*, endpoint: str, token: str, command_id: str, timeout_s: float) -> Mapping[str, Any]

claim_owner (method)

async LambdaMicroVMEndpointTransport.claim_owner(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

check_owner (method)

async LambdaMicroVMEndpointTransport.check_owner(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

acquire_lifecycle (method)

async LambdaMicroVMEndpointTransport.acquire_lifecycle(*, endpoint: str, token: str, claim_id: str, action: str, timeout_s: float) -> Mapping[str, Any]

release_lifecycle (method)

async LambdaMicroVMEndpointTransport.release_lifecycle(*, endpoint: str, token: str, claim_id: str, timeout_s: float) -> Mapping[str, Any]

configure_control_relay (method)

async LambdaMicroVMEndpointTransport.configure_control_relay(*, endpoint: str, token: str, owner_claim: str, host: str, port: int, timeout_s: float) -> Mapping[str, Any]

Release source · Runtime guarantees · Capability guides

LambdaMicroVMEndpointUnauthorized

from cayu.runners import LambdaMicroVMEndpointUnauthorized

The endpoint JWE token was rejected and should be refreshed.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMError

from cayu.runners import LambdaMicroVMError

Base error for AWS Lambda MicroVM runner failures.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMLifecycleInProgress

from cayu.runners import LambdaMicroVMLifecycleInProgress

The current owner is suspending or terminating the MicroVM.

The sidecar refuses new claims and commands until the lease is settled: the owner releases it after a provider request that was never sent or was definitively rejected, or the guest’s matching suspend/terminate hook observes the request’s effect. The lease never expires by time.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMOwnershipSuperseded

from cayu.runners import LambdaMicroVMOwnershipSuperseded

A later host claimed this MicroVM; this runner may no longer act on it.

Execution is permanently closed and lifecycle mutations are skipped so a stale owner cannot run commands in, suspend, or terminate its successor’s MicroVM.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMOwnershipUnverified

from cayu.runners import LambdaMicroVMOwnershipUnverified

The sidecar could not confirm this runner still owns the MicroVM.

No suspend or terminate was sent. An unreachable sidecar is not proof that no successor owns the MicroVM, so the mutation is refused and cleanup stays pending for an authoritative path: the runtime’s allocation reap, which runs under the durable allocation fence, or the MicroVM’s maximum duration.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMProtocolError

from cayu.runners import LambdaMicroVMProtocolError

A control-plane or sidecar response violated the runner contract.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides

LambdaMicroVMRunner

from cayu.runners import LambdaMicroVMRunner

Execute commands through a Cayu sidecar in an AWS Lambda MicroVM.

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	'lambda-microvm'
default_cwd	class attribute	DEFAULT_LAMBDA_MICROVM_CWD
system_execution_mode	RunnerSystemExecutionMode	'separate'

workload_authority (method)

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

Declare the browser workload only after this MicroVM’s image proved it.

execution_environment_authority (method)

LambdaMicroVMRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

LambdaMicroVMRunner.output_secret_values_present() -> bool

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

browser_control_endpoint_reachable (method)

LambdaMicroVMRunner.browser_control_endpoint_reachable(endpoint: str) -> bool

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

Only the verified control relay leaves the agent namespace, so only its exact wss://cayu-control:18443 authority is reachable. Anything else would carry a control credential toward an address the guest cannot reach, so it is reported unreachable.

browser_recording_supported (method)

LambdaMicroVMRunner.browser_recording_supported() -> bool

Declare recording once the worker and its control relay are both verified.

Frames leave through the control relay, and the adapter finalizes recordings in the guest before the MicroVM is suspended or terminated.

execution_profile_identity (property)

LambdaMicroVMRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

preflight_exec (method)

LambdaMicroVMRunner.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 sidecar request without provider activity.

exec (method)

async LambdaMicroVMRunner.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 LambdaMicroVMRunner.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 LambdaMicroVMRunner.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

Run a control-plane lifecycle command outside the unprivileged agent profile.

close (method)

async LambdaMicroVMRunner.close() -> None

await_pending_command_settlement (method)

async LambdaMicroVMRunner.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 LambdaMicroVMRunner.refresh_execution_admission() -> None

Refuse renewal for a MicroVM that cannot execute; claims are request-scoped.

Executable evidence is renewed by the request’s admission observer, which re-reads the complete identity. This hook adds no claim.

execution_admission_candidate (method)

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

LambdaMicroVMRunner.execution_admission_candidate_for(requirements)

execution_admission_observer (method)

LambdaMicroVMRunner.execution_admission_observer(requirements)

Own live executable evidence for this exact MicroVM and requirement set.

collect_execution_admission_candidate_for (method)

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

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

is_closed (property)

LambdaMicroVMRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

LambdaMicroVMRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

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

binary_stream_capability (method)

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

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

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

aexit (method)

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

init (method)

LambdaMicroVMRunner.__init__(client: Any, *, microvm_id: str, endpoint: str, image_identifier: str | None=None, image_version: str | None=None, region_name: str | None=None, default_cwd: str=DEFAULT_LAMBDA_MICROVM_CWD, close_action: LambdaMicroVMCloseAction='none', endpoint_transport: LambdaMicroVMEndpointTransport | None=None, owns_client: bool=False, poll_interval_s: float=DEFAULT_LAMBDA_MICROVM_POLL_INTERVAL_SECONDS, request_timeout_s: float=DEFAULT_LAMBDA_MICROVM_REQUEST_TIMEOUT_SECONDS, auth_token_expiration_minutes: int=DEFAULT_LAMBDA_MICROVM_AUTH_TOKEN_MINUTES, 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) -> None

configure_browser_control_relay (method)

async LambdaMicroVMRunner.configure_browser_control_relay(*, host: str, port: int, ca_certificate_pem: bytes, timeout_s: int=30) -> None

Give the agent namespace one verified path to the Cayu control server, or raise.

A trusted command installs the control server’s public CA where the browser worker reads control roots. The owner-fenced sidecar then relays cayu-control:18443 in the agent namespace to host:port (a private IPv4 target). Finally the agent profile completes a TLS handshake through the relay with the worker’s own control trust, which proves the route, the name mapping, and certificate verification without sending any credential. Only then does browser_control_endpoint_reachable report the relay endpoint.

verify_browser_workload (method)

async LambdaMicroVMRunner.verify_browser_workload(*, timeout_s: int=30, launch_timeout_s: int=LAMBDA_MICROVM_BROWSER_LAUNCH_TIMEOUT_SECONDS) -> None

Prove the image carries this Cayu release’s browser worker, or raise.

A trusted-profile probe hashes the root-owned worker files and reads the pinned component versions through the exact interpreter the worker command names. Then the agent profile launches Chromium once with its sandbox enabled and renders a page, which proves the sandbox works on this MicroVM and pays the first, lazily loaded Chromium start before any tool can run. Only when both pass does workload_authority report the browser workloads; the image is immutable for the MicroVM’s lifetime and unwritable by agent commands, so the proof holds until this runner is discarded.

create (method)

async LambdaMicroVMRunner.create(image_identifier: str, *, region_name: str | None=None, profile_name: str | None=None, endpoint_url: str | None=None, image_version: str | None=None, execution_role_arn: str | None=None, ingress_network_connectors: list[str] | None=None, egress_network_connectors: list[str] | None=None, idle_policy: dict[str, Any] | None=None, maximum_duration_in_seconds: int | None=None, run_hook_payload: str | None=None, default_cwd: str=DEFAULT_LAMBDA_MICROVM_CWD, close_action: LambdaMicroVMCloseAction='terminate', client: Any | None=None, endpoint_transport: LambdaMicroVMEndpointTransport | None=None, ready_timeout_s: float=DEFAULT_LAMBDA_MICROVM_READY_TIMEOUT_SECONDS, poll_interval_s: float=DEFAULT_LAMBDA_MICROVM_POLL_INTERVAL_SECONDS, request_timeout_s: float=DEFAULT_LAMBDA_MICROVM_REQUEST_TIMEOUT_SECONDS, auth_token_expiration_minutes: int=DEFAULT_LAMBDA_MICROVM_AUTH_TOKEN_MINUTES, 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, client_token: str | None=None, client_token_not_after: float | None=None) -> LambdaMicroVMRunner

Allocate a MicroVM and wait until its sidecar is ready.

With client_token, submission is idempotent: transient control-plane failures replay the same token and parameters, and a replay adopts the allocation AWS already created for that token. The adopted state is read back with get_microvm because a replay response repeats the original acknowledgement. A token-owned allocation that is already failed or terminated raises LambdaMicroVMAllocationTerminated; changed parameters raise LambdaMicroVMClientTokenConflict. Neither creates a replacement. client_token_not_after bounds when any submission for the token may be sent (see run_microvm_with_client_token).

drain_abandoned_allocations (method)

async LambdaMicroVMRunner.drain_abandoned_allocations(*, timeout_s: float=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS) -> int

Retry process-local abandoned allocations; return the unsettled count.

Each call retries settled failures once and joins still-running cleanup. Timeout or caller cancellation never cancels provider work. Applications should drain again when a provider failure has been repaired.

from_existing (method)

async LambdaMicroVMRunner.from_existing(microvm_id: str, *, region_name: str | None=None, profile_name: str | None=None, endpoint_url: str | None=None, default_cwd: str=DEFAULT_LAMBDA_MICROVM_CWD, close_action: LambdaMicroVMCloseAction='none', client: Any | None=None, endpoint_transport: LambdaMicroVMEndpointTransport | None=None, ready_timeout_s: float=DEFAULT_LAMBDA_MICROVM_READY_TIMEOUT_SECONDS, poll_interval_s: float=DEFAULT_LAMBDA_MICROVM_POLL_INTERVAL_SECONDS, request_timeout_s: float=DEFAULT_LAMBDA_MICROVM_REQUEST_TIMEOUT_SECONDS, auth_token_expiration_minutes: int=DEFAULT_LAMBDA_MICROVM_AUTH_TOKEN_MINUTES, 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) -> LambdaMicroVMRunner

suspend (method)

async LambdaMicroVMRunner.suspend() -> None

wait_until_suspended (method)

async LambdaMicroVMRunner.wait_until_suspended(timeout_s: float=DEFAULT_LAMBDA_MICROVM_READY_TIMEOUT_SECONDS) -> None

Wait for positive control-plane evidence that guest execution is suspended.

resume (method)

async LambdaMicroVMRunner.resume() -> None

terminate (method)

async LambdaMicroVMRunner.terminate() -> None

wait_until_terminated (method)

async LambdaMicroVMRunner.wait_until_terminated(timeout_s: float=DEFAULT_LAMBDA_MICROVM_READY_TIMEOUT_SECONDS) -> None

Wait for positive control-plane evidence that guest execution terminated.

kill (method)

async LambdaMicroVMRunner.kill() -> None

owner_fence_generation (property)

LambdaMicroVMRunner.owner_fence_generation() -> str | None

Non-secret identity of this runner’s current sidecar owner claim.

None until the runner has claimed the MicroVM or once any guest operation reported that a successor superseded it. Because every guest operation is fenced, a successor that claims inside a caller’s window makes some operation in that window fail and clears this value.

Release source · Runtime guarantees · Capability guides

LambdaMicroVMSubmissionClosed

from cayu.runners import LambdaMicroVMSubmissionClosed

A RunMicrovm request was not sent because its submission deadline passed.

Nothing reached AWS, so the refused request cannot create an allocation.

Bases: LambdaMicroVMError.

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

Release source · Runtime guarantees · Capability guides