cayu.egress.adapter

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.

`EgressAdapterRegistry`

from cayu.egress import EgressAdapterRegistry

Resolves a runner kind to its egress adapter, failing closed by default.

resolve never returns None: an unregistered runner kind yields an UnsupportedEgressAdapter whose prepare raises, so callers cannot accidentally skip enforcement.

init (method)

EgressAdapterRegistry.__init__() -> None

register (method)

EgressAdapterRegistry.register(adapter: SandboxEgressAdapter) -> None

resolve (method)

EgressAdapterRegistry.resolve(runner_kind: str) -> SandboxEgressAdapter

Release source · Runtime guarantees · Capability guides

`EgressAuthorityCutoverRequest`

from cayu.egress import EgressAuthorityCutoverRequest

Trusted live inputs for one quiescent same-allocation authority rotation.

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
`session_id`	`str`	`required`
`environment_name`	`str`	`required`
`owner_fingerprint`	`str`	`required`
`environment_fingerprint`	`str`	`required`
`runner`	`Runner`	`field(repr=False)`
`current_binding`	`EgressBinding`	`field(repr=False)`
`expected_authority`	`EgressAuthorityIdentity`	`required`
`target_authority`	`EgressAuthorityIdentity`	`required`
`target_broker`	`TransparentEgressBroker`	`field(repr=False)`
`target_grants`	`tuple[VirtualCredentialGrant, ...]`	`field(repr=False)`
`target_env_overlay`	`Mapping[str, str]`	`field(repr=False)`
`target_egress_destinations`	`tuple[str, ...]`	`required`
`revoke_current_authority`	`Callable[[], Awaitable[bool]]`	`field(repr=False)`
`ca_cert_host_path`	`str`	`required`
`guest_ca_path`	`str`	`required`
`invocation_quiescent`	`bool`	`required`

Release source · Runtime guarantees · Capability guides

`EgressAuthorityCutoverResult`

from cayu.egress import EgressAuthorityCutoverResult

A live replacement binding paired with its durable-safe activation receipt.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`binding`	`EgressBinding`	`field(repr=False)`
`receipt`	`EgressAuthorityCutoverReceipt`	`required`
`cancellation`	`asyncio.CancelledError \| None`	`field(default=None, repr=False)`
`cancellation_requests_consumed`	`int`	`field(default=0, repr=False)`

Release source · Runtime guarantees · Capability guides

`EgressAuthorityRenewalRequest`

from cayu.egress import EgressAuthorityRenewalRequest

Trusted inputs for renewing an unchanged authority on one parked allocation.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`environment_name`	`str`	`required`
`environment_fingerprint`	`str`	`required`
`runner`	`Runner`	`field(repr=False)`
`current_binding`	`EgressBinding`	`field(repr=False)`
`authority`	`EgressAuthorityIdentity`	`required`
`renewed_grants`	`tuple[VirtualCredentialGrant, ...]`	`field(repr=False)`
`renewed_env_overlay`	`Mapping[str, str]`	`field(repr=False)`
`egress_destinations`	`tuple[str, ...]`	`required`
`ca_cert_host_path`	`str`	`required`
`guest_ca_path`	`str`	`required`
`invocation_quiescent`	`bool`	`required`

Release source · Runtime guarantees · Capability guides

`EgressBinding`

from cayu.egress import EgressBinding

The result of configuring enforced egress for one runner workload.

env is the overlay the runner must apply to the workload process (proxy vars + CA trust). ca_cert_pem is the per-session CA the workload must trust. close tears everything down (removes networks/sidecars and revokes grants) and is idempotent.

Decorators: @dataclass.

Fields and attributes

Name	Type	Default
`env`	`dict[str, str]`	`field(default_factory=dict)`
`ca_cert_pem`	`bytes \| None`	`None`
`runner_kind`	`str \| None`	`None`
`network`	`str \| None`	`None`
`sidecar`	`str \| None`	`None`
`guest_ca_path`	`str \| None`	`None`
`proxy_url`	`str \| None`	`None`
`proxy_port`	`int \| None`	`None`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`teardown`	`Callable[[], Awaitable[None]] \| None`	`None`
`certificate_authority`	`Any`	`field(default=None, repr=False)`
`adopt_certificate_authority`	`Callable[[Any], None] \| None`	`field(default=None, repr=False)`
`relinquish_certificate_authority`	`Callable[[Any], None] \| None`	`field(default=None, repr=False)`
`teardown_timeout_s`	`float`	`DEFAULT_EGRESS_TEARDOWN_TIMEOUT_SECONDS`
`authority_fingerprint`	`str \| None`	`None`
`authority_generation`	`int \| None`	`None`

proxy_endpoint (property)

EgressBinding.proxy_endpoint() -> HttpProxyEndpoint | None

close (method)

async EgressBinding.close() -> None

transfer_certificate_authority_to (method)

EgressBinding.transfer_certificate_authority_to(replacement: EgressBinding) -> None

Move teardown ownership to a staged binding using the exact same CA.

bind_authority (method)

EgressBinding.bind_authority(authority: EgressAuthorityIdentity) -> None

Freeze the exact authority generation enforced by this live path.

Release source · Runtime guarantees · Capability guides

`RunnerFinalizationResult`

from cayu.egress import RunnerFinalizationResult

Positive lifecycle evidence after runner finalization.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`workspace_mutations_quiescent`	`bool`	`required`
`allocation_preserved`	`bool`	`False`

Release source · Runtime guarantees · Capability guides

`SandboxEgressAdapter`

from cayu.egress import SandboxEgressAdapter

Configures egress and creates the matching enforced runner.

An adapter must either return a binding that provably routes provider traffic through the broker (and blocks direct egress), or raise UnsupportedEgressError. It must never return a binding that leaves direct egress open — that would silently downgrade the security boundary. Runner creation lives on the same interface so a prepared binding cannot be paired with an unrelated factory that ignores its network policy.

Bases: ABC.

Fields and attributes

Name	Type	Default
`runner_kind`	`str`	`required`
`process_external_allocation`	`bool \| None`	`None`
`allocation_provider`	`str \| None`	`None`
`allocation_adapter_generation`	`str \| None`	`None`
`supports_reconnect`	`bool`	`False`
`supports_allocation_fingerprint`	`bool`	`False`
`egress_authority_cutover_strategy`	`EgressAuthorityCutoverStrategy`	`EgressAuthorityCutoverStrategy.UNSUPPORTED`

prepare (method)

async SandboxEgressAdapter.prepare(*, session_id: str, grants: Sequence[VirtualCredentialGrant], broker: TransparentEgressBroker) -> EgressBinding

Configure enforced egress for the session or raise.

create_runner (method)

async SandboxEgressAdapter.create_runner(request: VirtualEgressRunnerRequest) -> Runner

Create a runner that applies this adapter’s binding without downgrade.

create_or_recover_runner (method)

async SandboxEgressAdapter.create_or_recover_runner(request: VirtualEgressRunnerRequest, *, allow_create: bool) -> Runner

Create once or recover the intent-owned external allocation.

allow_create is true only for the worker that durably advanced the allocation intent from PREPARED to DISPATCHED. Recovery workers must perform positive lookup and must never infer that absence authorizes a second provider submission.

declared_workload_authority (method)

SandboxEgressAdapter.declared_workload_authority(name: str, *, image: str) -> RunnerWorkloadAuthority | None

Declare a workload every runner created for image will prove.

A factory uses this before any allocation exists. Returning an authority is a promise that runner creation verifies it and fails otherwise, so a created runner reports the same authority or is never admitted. The default declares nothing.

prepare_allocation_metadata (method)

async SandboxEgressAdapter.prepare_allocation_metadata(request: VirtualEgressAllocationPreparation) -> dict[str, Any]

Return non-secret provider inputs to pin before the first mutation.

Cayu persists the returned mapping in the allocation intent before create_or_recover_runner may dispatch, then passes the same mapping to every create, recovery, and reap attempt. Recovery must therefore use these pinned inputs instead of re-resolving mutable configuration. The default pins nothing.

reap_allocation (method)

async SandboxEgressAdapter.reap_allocation(request: VirtualEgressAllocationReap) -> None

Positively dispose one unpublished intent-owned allocation or raise.

Cayu calls this only after it holds the durable cleanup fence for a dispatched intent. Return only when the exact provider resource is proven terminal; raise when the outcome is ambiguous so the runtime retains retryable ownership. Never create a replacement allocation, attach guest work, or infer absence from an empty lookup.

prepare_reconnect (method)

async SandboxEgressAdapter.prepare_reconnect(*, session_id: str, environment_name: str, grants: Sequence[VirtualCredentialGrant], broker: TransparentEgressBroker, reconnect_metadata: Mapping[str, Any]) -> EgressBinding

Re-establish enforcement for an existing sandbox or fail closed.

cutover_authority (method)

async SandboxEgressAdapter.cutover_authority(request: EgressAuthorityCutoverRequest) -> EgressAuthorityCutoverResult

Replace active enforcement at a quiescent boundary or fail closed.

renew_authority (method)

async SandboxEgressAdapter.renew_authority(request: EgressAuthorityRenewalRequest) -> str

Verify renewed grants and routes on an unchanged parked allocation.

egress_environment_fingerprint (method)

async SandboxEgressAdapter.egress_environment_fingerprint(runner: Runner) -> str

Return the exact backend allocation identity used by cutover receipts.

reconcile_authority_cutover (method)

async SandboxEgressAdapter.reconcile_authority_cutover(request: EgressAuthorityCutoverRequest) -> EgressAuthorityCutoverReceipt | None

Read back one exact cutover without trusting caller-produced proof.

complete_runner_admission (method)

SandboxEgressAdapter.complete_runner_admission(runner: Runner) -> None

Mark completion of factory admission before retained workloads may resume.

Adapters may keep retained guest work frozen while capability/workspace probes run. This hook grants no independent dispatch authority.

is_allocation_disposed (method)

async SandboxEgressAdapter.is_allocation_disposed(reconnect_metadata: Mapping[str, Any]) -> bool

Prove exact terminal disposal without mutating provider resources.

Missing or uncertain ownership never authorizes replacement. Adapters without a durable disposal proof preserve normal reconnect behavior.

reconnect_metadata (method)

SandboxEgressAdapter.reconnect_metadata(runner: Runner) -> dict[str, Any]

Return durable identity required to reattach to runner.

observe_writer_isolation (method)

SandboxEgressAdapter.observe_writer_isolation(runner: Runner) -> WorkspaceWriterIsolationEvidence

Report writer isolation for a workspace held inside runner’s sandbox.

Called only when the environment’s workspace targets the managed sandbox directly. EXCLUSIVE must name a real mechanism that keeps every other writer out for the whole mutation window. The default is unknown.

capability_evidence (method)

SandboxEgressAdapter.capability_evidence(runner: Runner) -> EgressCapabilityEvidence

Return typed runtime evidence for capabilities proven by runner.

execution_capability_evidence (method)

SandboxEgressAdapter.execution_capability_evidence(runner: Runner | None=None) -> ExecutionCapabilityEvidence

Return admission evidence before creation or before runner exposure.

Implementations must remain side-effect free when runner is None so the first admission gate cannot create provider resources while gathering evidence.

execution_admission_evidence_for (method)

SandboxEgressAdapter.execution_admission_evidence_for(requirements: ExecutionRequirements) -> ExecutionCapabilityEvidence

Declare configured admission support before allocation.

The default adds no executable claims. An adapter with a production probe owner may declare its planned checks; final live evidence is still required and declarations never prove executable availability.

configuration_metadata (method)

SandboxEgressAdapter.configuration_metadata() -> dict[str, Any]

Return JSON-safe configured intent without claiming runtime proof.

validate_reconnect_metadata (method)

SandboxEgressAdapter.validate_reconnect_metadata(reconnect_metadata: Mapping[str, Any]) -> dict[str, Any]

Allowlist and normalize this adapter’s non-secret durable identity.

finalize_runner (method)

async SandboxEgressAdapter.finalize_runner(runner: Runner, *, outcome: str | None) -> RunnerFinalizationResult

Map an outcome to lifecycle cleanup without inferring remote quiescence.

finalize_runner_for_binding (method)

async SandboxEgressAdapter.finalize_runner_for_binding(runner: Runner, *, outcome: str | None) -> RunnerFinalizationResult

Finalize a runner while positively quiescing workspace mutation.

Reconnectable adapters should override this when they can stop or suspend an allocation without destroying its durable identity. The default fails closed by using terminal cleanup.

park_runner_for_authority_adoption (method)

async SandboxEgressAdapter.park_runner_for_authority_adoption(runner: Runner) -> RunnerFinalizationResult

Fence workload execution while retaining the exact live allocation.

Release source · Runtime guarantees · Capability guides

`UnsupportedEgressAdapter`

from cayu.egress import UnsupportedEgressAdapter

Fail-closed adapter for runners that cannot enforce egress.

prepare always raises UnsupportedEgressError. This is what makes the absence of a real adapter safe: virtual egress can never proceed without enforcement.

Bases: SandboxEgressAdapter.

Fields and attributes

Name	Type	Default
`runner_kind`	`str`	`required`
`process_external_allocation`	`class attribute`	`False`
`allocation_provider`	`str \| None`	`None`
`allocation_adapter_generation`	`str \| None`	`None`
`supports_reconnect`	`bool`	`False`
`supports_allocation_fingerprint`	`bool`	`False`
`egress_authority_cutover_strategy`	`EgressAuthorityCutoverStrategy`	`EgressAuthorityCutoverStrategy.UNSUPPORTED`

prepare (method)

async UnsupportedEgressAdapter.prepare(*, session_id: str, grants: Sequence[VirtualCredentialGrant], broker: TransparentEgressBroker) -> EgressBinding

create_runner (method)

async UnsupportedEgressAdapter.create_runner(request: VirtualEgressRunnerRequest) -> Runner

create_or_recover_runner (method)

async UnsupportedEgressAdapter.create_or_recover_runner(request: VirtualEgressRunnerRequest, *, allow_create: bool) -> Runner

Create once or recover the intent-owned external allocation.

declared_workload_authority (method)

UnsupportedEgressAdapter.declared_workload_authority(name: str, *, image: str) -> RunnerWorkloadAuthority | None

Declare a workload every runner created for image will prove.

prepare_allocation_metadata (method)

async UnsupportedEgressAdapter.prepare_allocation_metadata(request: VirtualEgressAllocationPreparation) -> dict[str, Any]

Return non-secret provider inputs to pin before the first mutation.

reap_allocation (method)

async UnsupportedEgressAdapter.reap_allocation(request: VirtualEgressAllocationReap) -> None

Positively dispose one unpublished intent-owned allocation or raise.

prepare_reconnect (method)

async UnsupportedEgressAdapter.prepare_reconnect(*, session_id: str, environment_name: str, grants: Sequence[VirtualCredentialGrant], broker: TransparentEgressBroker, reconnect_metadata: Mapping[str, Any]) -> EgressBinding

Re-establish enforcement for an existing sandbox or fail closed.

cutover_authority (method)

async UnsupportedEgressAdapter.cutover_authority(request: EgressAuthorityCutoverRequest) -> EgressAuthorityCutoverResult

Replace active enforcement at a quiescent boundary or fail closed.

renew_authority (method)

async UnsupportedEgressAdapter.renew_authority(request: EgressAuthorityRenewalRequest) -> str

Verify renewed grants and routes on an unchanged parked allocation.

egress_environment_fingerprint (method)

async UnsupportedEgressAdapter.egress_environment_fingerprint(runner: Runner) -> str

Return the exact backend allocation identity used by cutover receipts.

reconcile_authority_cutover (method)

async UnsupportedEgressAdapter.reconcile_authority_cutover(request: EgressAuthorityCutoverRequest) -> EgressAuthorityCutoverReceipt | None

Read back one exact cutover without trusting caller-produced proof.

complete_runner_admission (method)

UnsupportedEgressAdapter.complete_runner_admission(runner: Runner) -> None

Mark completion of factory admission before retained workloads may resume.

Adapters may keep retained guest work frozen while capability/workspace probes run. This hook grants no independent dispatch authority.

is_allocation_disposed (method)

async UnsupportedEgressAdapter.is_allocation_disposed(reconnect_metadata: Mapping[str, Any]) -> bool

Prove exact terminal disposal without mutating provider resources.

Missing or uncertain ownership never authorizes replacement. Adapters without a durable disposal proof preserve normal reconnect behavior.

reconnect_metadata (method)

UnsupportedEgressAdapter.reconnect_metadata(runner: Runner) -> dict[str, Any]

Return durable identity required to reattach to runner.

observe_writer_isolation (method)

UnsupportedEgressAdapter.observe_writer_isolation(runner: Runner) -> WorkspaceWriterIsolationEvidence

Report writer isolation for a workspace held inside runner’s sandbox.

capability_evidence (method)

UnsupportedEgressAdapter.capability_evidence(runner: Runner) -> EgressCapabilityEvidence

Return typed runtime evidence for capabilities proven by runner.

execution_capability_evidence (method)

UnsupportedEgressAdapter.execution_capability_evidence(runner: Runner | None=None) -> ExecutionCapabilityEvidence

Return admission evidence before creation or before runner exposure.

Implementations must remain side-effect free when runner is None so the first admission gate cannot create provider resources while gathering evidence.

execution_admission_evidence_for (method)

UnsupportedEgressAdapter.execution_admission_evidence_for(requirements: ExecutionRequirements) -> ExecutionCapabilityEvidence

Declare configured admission support before allocation.

configuration_metadata (method)

UnsupportedEgressAdapter.configuration_metadata() -> dict[str, Any]

Return JSON-safe configured intent without claiming runtime proof.

validate_reconnect_metadata (method)

UnsupportedEgressAdapter.validate_reconnect_metadata(reconnect_metadata: Mapping[str, Any]) -> dict[str, Any]

Allowlist and normalize this adapter’s non-secret durable identity.

finalize_runner (method)

async UnsupportedEgressAdapter.finalize_runner(runner: Runner, *, outcome: str | None) -> RunnerFinalizationResult

Map an outcome to lifecycle cleanup without inferring remote quiescence.

finalize_runner_for_binding (method)

async UnsupportedEgressAdapter.finalize_runner_for_binding(runner: Runner, *, outcome: str | None) -> RunnerFinalizationResult

Finalize a runner while positively quiescing workspace mutation.

Reconnectable adapters should override this when they can stop or suspend an allocation without destroying its durable identity. The default fails closed by using terminal cleanup.

park_runner_for_authority_adoption (method)

async UnsupportedEgressAdapter.park_runner_for_authority_adoption(runner: Runner) -> RunnerFinalizationResult

Fence workload execution while retaining the exact live allocation.

init (method)

UnsupportedEgressAdapter.__init__(runner_kind: str, *, reason: str | None=None) -> None

Release source · Runtime guarantees · Capability guides

`virtual_egress_execution_capability_evidence`

from cayu.extensions.egress import virtual_egress_execution_capability_evidence

Build execution admission evidence for one enforced virtual-egress runner.

Experimental extension seam (see docs/build-a-runner.md). This is the builder used by Cayu’s own virtual-egress adapters, with strict input types. Supported claims stay declared until runner_ready is true. Network, brokered-egress, and "live_verified" posture claims become live-verified only with a timezone-aware preflight_observed_at from a successful enforcement preflight on a ready runner, and expire after the admission live-evidence TTL. Each posture is one of "available", "live_verified", "unverified", or "unsupported".

virtual_egress_execution_capability_evidence(*, runner_kind: str, runner_ready: bool, preflight_observed_at: datetime | None, untrusted_isolation: bool, credential_non_possession_posture: _ExecutionCapabilityPosture, guest_privilege: _ExecutionCapabilityPosture, unprivileged_guest: _ExecutionCapabilityPosture, host_filesystem_isolation: bool, reconnect: bool, network_unverified: bool=False, cancellation_confirmed: bool=True) -> ExecutionCapabilityEvidence

Release source · Runtime guarantees · Capability guides

`VirtualEgressAllocationPreparation`

from cayu.egress import VirtualEgressAllocationPreparation

Trusted inputs available before one recoverable provider mutation.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`allocation_id`	`str`	`required`
`session_id`	`str`	`required`
`environment_name`	`str`	`required`
`image`	`str`	`required`
`predecessor_identity`	`Mapping[str, Any] \| None`	`None`

Release source · Runtime guarantees · Capability guides

`VirtualEgressAllocationReap`

from cayu.egress import VirtualEgressAllocationReap

Exact durable authority for disposing one unpublished allocation.

allocation_metadata is the adapter-owned mapping pinned at preparation. acknowledged_identity is the adapter’s reconnect identity when the provider result was durably acknowledged, otherwise None.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`allocation_id`	`str`	`required`
`session_id`	`str`	`required`
`environment_name`	`str`	`required`
`image`	`str`	`required`
`allocation_metadata`	`Mapping[str, Any]`	`required`
`acknowledged_identity`	`Mapping[str, Any] \| None`	`None`

Release source · Runtime guarantees · Capability guides

`VirtualEgressRunnerRequest`

from cayu.egress import VirtualEgressRunnerRequest

Inputs an egress adapter needs to start its enforced runner.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`name`	`str`	`required`
`runner_kind`	`str`	`required`
`image`	`str`	`required`
`binding`	`EgressBinding`	`required`
`env_overlay`	`Mapping[str, str]`	`required`
`ca_cert_host_path`	`str`	`required`
`guest_ca_path`	`str`	`required`
`setup_commands`	`tuple[str, ...]`	`required`
`egress_destinations`	`tuple[str, ...]`	`required`
`session_id`	`str \| None`	`None`
`parent_session_id`	`str \| None`	`None`
`reconnect_metadata`	`Mapping[str, Any]`	`field(default_factory=dict)`
`environment_name`	`str \| None`	`None`
`env_overlay_secret_values_present`	`bool \| None`	`None`
`allocation_id`	`str \| None`	`None`
`host_workspace_path`	`str \| None`	`None`
`allocation_metadata`	`Mapping[str, Any]`	`field(default_factory=dict)`

Release source · Runtime guarantees · Capability guides