cayu.egress.runtime

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.

VIRTUAL_EGRESS_EVENT_TYPES

from cayu.egress import VIRTUAL_EGRESS_EVENT_TYPES

VIRTUAL_EGRESS_EVENT_TYPES = (EventType.CREDENTIAL_MODE_SELECTED, EventType.EGRESS_GRANT_MINTED, EventType.EGRESS_REQUEST_AUTHORIZED, EventType.EGRESS_REQUEST_DENIED, EventType.EGRESS_GRANT_REVOKED)

Release source · Runtime guarantees · Capability guides

VIRTUAL_EGRESS_RECONNECT_VERSION

from cayu.egress import VIRTUAL_EGRESS_RECONNECT_VERSION

VIRTUAL_EGRESS_RECONNECT_VERSION = 1

Release source · Runtime guarantees · Capability guides

VirtualCredentialSpec

from cayu.egress import VirtualCredentialSpec

Declares one virtual credential the runner workload should present.

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
env_name	str	required
secret	SecretRef	required
destination	str	required
policy_name	str	required
credential_kind	CredentialKind	'stripe_bearer'
ttl_seconds	float | None	None

Release source · Runtime guarantees · Capability guides

VirtualEgressEnvironmentFactory

from cayu.egress import VirtualEgressEnvironmentFactory

Per-session environment factory that enforces virtual egress.

create mints grants, builds a broker (wired to emit audit events), prepares the explicitly selected egress adapter, and returns an Environment whose runner is on the enforced network and whose binding tears everything down at session end. Omitted and unsupported selections fail at construction before per-session resources exist.

Scope: virtual egress governs the runner process credential — the value the executed app can read. It does not govern MCP servers: McpServerSpec secret_env/secret_headers are resolved host-side (into the MCP server subprocess or the host HTTP client), never injected into the runner, so they sit at the trusted_tool boundary and are outside this factory.

Bases: EnvironmentFactory.

secret_resolution_scope (property)

VirtualEgressEnvironmentFactory.secret_resolution_scope() -> Literal['static', 'dynamic']

Declare the immutable secret capability of every CREATE/RECONNECT result.

Static factories must never expose a vault or credential proxy. Runtime snapshots this declaration at registration, fingerprints it for recovery, and rejects violating results before binding or tool dispatch. Undeclared factories remain dynamic, even when one result has no secret resolvers.

execution_profile_identity (property)

VirtualEgressEnvironmentFactory.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the application declaration for this configured egress factory.

egress_authority_identity (property)

VirtualEgressEnvironmentFactory.egress_authority_identity() -> EgressAuthorityIdentity

Return the secret-free authority proposed for the next invocation.

execution_admission_candidate (method)

VirtualEgressEnvironmentFactory.execution_admission_candidate(request: EnvironmentFactoryRequest) -> ExecutionAdmissionCandidate

Publish adapter-owned declarations without creating provider resources.

construction_admission_candidate (method)

VirtualEgressEnvironmentFactory.construction_admission_candidate() -> ExecutionAdmissionCandidate

Declare the selected adapter’s pre-create capabilities at app setup.

execution_environment_authority (method)

VirtualEgressEnvironmentFactory.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact factory authority every managed runner preserves.

workload_authority (method)

VirtualEgressEnvironmentFactory.workload_authority(name: str)

Bind the factory to the exact workload its runners are proven to carry.

Docker binds by the exact selected image. Other runner kinds bind only when their adapter declares a workload that runner creation verifies.

configured_artifact_store (property)

VirtualEgressEnvironmentFactory.configured_artifact_store() -> ArtifactStore | None

Return the stable store copied into every materialized environment.

allocation_scope (method)

VirtualEgressEnvironmentFactory.allocation_scope(request: EnvironmentFactoryRequest) -> EnvironmentAllocationScope | None

create_recoverable (method)

async VirtualEgressEnvironmentFactory.create_recoverable(request: EnvironmentFactoryRequest, allocation: EnvironmentAllocationContext) -> EnvironmentFactoryResult

reap_allocation (method)

async VirtualEgressEnvironmentFactory.reap_allocation(request: EnvironmentFactoryRequest, allocation: EnvironmentAllocationContext) -> None

recover_finalization_disposal (method)

async VirtualEgressEnvironmentFactory.recover_finalization_disposal(request: EnvironmentFactoryRequest, state: dict[str, Any]) -> None

Idempotently dispose an allocation whose publication durably finished.

This cleanup-only hook must validate the exact reconnect identity and disposal state, tolerate an already absent allocation, and never create a replacement or access/publish guest output. Factory wrappers must forward this hook when forwarding a factory that supports disposal.

is_allocation_disposed (method)

async VirtualEgressEnvironmentFactory.is_allocation_disposed(request: EnvironmentFactoryRequest) -> bool

deferred_materialization (property)

VirtualEgressEnvironmentFactory.deferred_materialization() -> bool

Whether results defer runner creation to first use.

A deferred factory returns an environment built from a cayu.environments.deferred.DeferredMaterialization: session start binds nothing, and the first runner use creates and binds the runner. Manifests and cayu inspect report this declaration.

release_deferred_materialization (method)

async VirtualEgressEnvironmentFactory.release_deferred_materialization(request: EnvironmentFactoryRequest) -> bool

Remove a resource a crashed run materialized for this exact allocation.

Called by recover_incomplete_session with RECONNECT authority for a recovered session that has no pending completion finalization, so the resource holds no output the runtime still has to publish. The session keeps its allocation and materializes again on its next use. Return whether a resource was removed. Absence is not an error. The default manages nothing.

release_idle_resources (method)

async VirtualEgressEnvironmentFactory.release_idle_resources() -> None

Trim factory-held idle resources, such as warm spares.

Called by CayuApp.drain_environment_cleanups, which applications may also call while idle. A later session may create such resources again. It must never touch a resource a session owns. The default holds nothing.

close_idle_resources (method)

async VirtualEgressEnvironmentFactory.close_idle_resources() -> None

Release factory-held idle resources for good, at application shutdown.

Called by CayuApp.close_idle_environment_resources (the server calls it after its shutdown drain). Afterwards the factory creates no new idle resources, and sessions that still materialize must work without them (for example by starting cold). The default trims like release_idle_resources.

create (method)

async VirtualEgressEnvironmentFactory.create(request: EnvironmentFactoryRequest) -> EnvironmentFactoryResult

init (method)

VirtualEgressEnvironmentFactory.__init__(*, policies: Mapping[str, EgressPolicy], credentials: Sequence[VirtualCredentialSpec]=(), approved_destinations: Sequence[ApprovedEgressDestination]=(), public_web_policy: str | None=None, resolver: SecretResolver | None=None, image: str=DEFAULT_SANDBOX_IMAGE, setup_commands: Sequence[str]=(), adapter: SandboxEgressAdapter | None=None, adapter_registry: EgressAdapterRegistry | None=None, runner_kind: str | None=None, inner_binding: WorkspaceBinding | None=None, workspace_factory: VirtualEgressWorkspaceFactory | None=None, host_workspace_path: str | None=None, host_workspace_path_factory: VirtualEgressHostWorkspacePathFactory | None=None, artifact_store: ArtifactStore | None=None, knowledge_store: KnowledgeStore | None=None, knowledge_access_scope_factory: VirtualEgressKnowledgeAccessScopeFactory | None=None, event_emitter: EventEmitter | None=None, upstream: EgressUpstream | None=None, require_test_mode_credentials: bool=True, browser_max_response_bytes: int | None=None, response_buffer_budget: EgressResponseBufferBudget | None=None, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None, egress_authority_generation: int=1, egress_authority_source: str | None=None, egress_authority_scope: str='session', egress_policy_version: str | None=None) -> None

adopt_authority (method)

async VirtualEgressEnvironmentFactory.adopt_authority(*, factory_result: EnvironmentFactoryResult, authorized: EgressAuthorityTransitionRecord, coordinator: EgressAuthorityTransitionCoordinator, owner_token: str, agent_name: str='agent', execution_profile_fingerprint: str | None=None) -> EgressAuthorityAdoptionResult

Install this factory’s target authority on one parked live environment.

The caller supplies the trusted profile decision converted to authorized and a coordinator backed by the logical session’s durable SessionStore. This method owns target credentials, fences all new runner work, rotates the backend path, transfers cleanup ownership, and reopens work only after the exact active receipt is durable.

renew_parked_authority (method)

async VirtualEgressEnvironmentFactory.renew_parked_authority(*, factory_result: EnvironmentFactoryResult, expected_authority: EgressAuthorityIdentity, session_id: str, environment_name: str, agent_name: str, execution_profile_fingerprint: str | None) -> None

Renew revoked grants and verify an unchanged parked authority in place.

Release source · Runtime guarantees · Capability guides

VirtualEgressWorkspaceFactory

from cayu.egress import VirtualEgressWorkspaceFactory

VirtualEgressWorkspaceFactory = Callable[[Runner], Workspace | Awaitable[Workspace]]

Release source · Runtime guarantees · Capability guides