cayu.environments.docker_coding

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.

DOCKER_CODING_PROTECTED_DIRECTORY_NAMES

from cayu.environments import DOCKER_CODING_PROTECTED_DIRECTORY_NAMES

DOCKER_CODING_PROTECTED_DIRECTORY_NAMES = ('.cayu', '.git', '.runtime')

Release source · Runtime guarantees · Capability guides

DockerCodingEnvironmentFactory

from cayu.environments import DockerCodingEnvironmentFactory

Create exact, non-networked Docker environments for explicitly trusted code.

git_baseline=False drops the ephemeral guest Git baseline, so the image needs no git. Use it for sandboxes that only sync files in and out; keep the default for coding products that publish Git changes.

Bases: EnvironmentFactory.

secret_resolution_scope (property)

DockerCodingEnvironmentFactory.secret_resolution_scope() -> Literal['static']

Every native Docker coding result is credential-free.

execution_profile_identity (property)

DockerCodingEnvironmentFactory.execution_profile_identity() -> ExecutionProfileBehaviorIdentity

egress_authority_identity (property)

DockerCodingEnvironmentFactory.egress_authority_identity() -> EgressAuthorityIdentity | None

Return the immutable egress authority proposed for future invocations.

execution_admission_candidate (method)

DockerCodingEnvironmentFactory.execution_admission_candidate(request: EnvironmentFactoryRequest) -> ExecutionAdmissionCandidate

construction_admission_candidate (method)

DockerCodingEnvironmentFactory.construction_admission_candidate() -> ExecutionAdmissionCandidate

execution_environment_authority (method)

DockerCodingEnvironmentFactory.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact authority every runner from this factory preserves.

workload_authority (method)

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

Return configured authority for a workload every result must preserve.

configured_artifact_store (property)

DockerCodingEnvironmentFactory.configured_artifact_store() -> ArtifactStore | None

Host-side store shared by results; its lifetime belongs to the application.

allocation_scope (method)

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

create_recoverable (method)

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

reap_allocation (method)

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

recover_finalization_disposal (method)

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

is_allocation_disposed (method)

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

Prove that a finished session’s exact container is gone.

Full Docker container IDs are never reused, so absence after a successful daemon lookup proves disposal and lets the next invocation of a completed session start a fresh container. A failed lookup raises instead of answering. Configuration is not compared: an image re-pin must not strand completed sessions. Factories with immutable inputs keep exact reconnect, since their attachments have their own disposal state.

deferred_materialization (property)

DockerCodingEnvironmentFactory.deferred_materialization() -> bool

Whether sessions create their container on first runner use.

release_deferred_materialization (method)

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

Remove the container a crashed run created under this allocation’s name.

release_idle_resources (method)

async DockerCodingEnvironmentFactory.release_idle_resources() -> None

Remove idle warm spares; the next materialization refills the pool.

close_idle_resources (method)

async DockerCodingEnvironmentFactory.close_idle_resources() -> None

Close the warm spare pool at shutdown; later sessions start cold.

create (method)

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

init (method)

DockerCodingEnvironmentFactory.__init__(*, source_workspace: LocalWorkspace, toolchain_profile: DockerCodingToolchainProfile, artifact_store: ArtifactStore | None=None, transfer_limits: DockerWorkspaceTransferLimits | None=None, runtime: str | None=None, seccomp_profile: str | None=None, docker_path: str | None=None, immutable_inputs: Sequence[LocalImmutableInput]=(), immutable_input_store: ImmutableInputStore | None=None, immutable_input_runtime_compatibility_fingerprint: str | None=None, git_baseline: bool=True, knowledge_store: KnowledgeStore | None=None, knowledge_access_scope: KnowledgeAccessScope | None=None, deferred: bool=False, warm_spares: int=0) -> None

warm_spare_pool (property)

DockerCodingEnvironmentFactory.warm_spare_pool() -> WarmSparePool[Any] | None

The warm spare pool behind warm_spares, or None without one.

immutable_input_capability (property)

DockerCodingEnvironmentFactory.immutable_input_capability() -> ImmutableInputAdapterCapability

Describe the concrete read-only projection mechanism used by this factory.

observe_command_receipt (method)

async DockerCodingEnvironmentFactory.observe_command_receipt(identity: dict[str, Any], receipt: dict[str, Any])

Read authenticated command evidence without allocating or attaching.

create_workspace_binding (method)

DockerCodingEnvironmentFactory.create_workspace_binding(request: EnvironmentFactoryRequest, *, target_workspace: RunnerWorkspace, immutable_input_attachments: Sequence[ImmutableInputAttachment]=()) -> DockerCodingWorkspaceBinding

Construct the exact request-bound publication seam for an admitted runner.

Release source · Runtime guarantees · Capability guides

DockerCodingWorkspaceBinding

from cayu.environments import DockerCodingWorkspaceBinding

Sync a projected host tree, optionally with an ephemeral guest Git baseline.

With git_baseline=False the guest needs no git executable: copy-in, copy-back, recovery and disposal are unchanged, but no Git evidence is captured and coding-product source-copy authority is unavailable.

Bases: SyncBinding.

bind (method)

async DockerCodingWorkspaceBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async DockerCodingWorkspaceBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async DockerCodingWorkspaceBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe the bounded guest file tree, excluding protected runtime paths.

input_capability (method)

DockerCodingWorkspaceBinding.input_capability() -> ImmutableInputAdapterCapability

observe_writer_isolation (method)

DockerCodingWorkspaceBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

The compatibility default is deliberately unknown. Serial tool dispatch, a process-local lock, or a stable workspace identity does not prove that users, sibling processes, or background services cannot mutate the same resource.

abandon (method)

DockerCodingWorkspaceBinding.abandon(bound: BoundWorkspace) -> bool

init (method)

DockerCodingWorkspaceBinding.__init__(*, target_workspace: RunnerWorkspace, limits: DockerWorkspaceTransferLimits, source_copy_authority: CodingProductSourceCopyAuthority | None=None, immutable_input_store: ImmutableInputStore | None=None, immutable_input_attachments: Sequence[ImmutableInputAttachment]=(), path: str='/workspace', git_baseline: bool=True) -> None

staging_snapshot (method)

DockerCodingWorkspaceBinding.staging_snapshot() -> SyncBindingStagingSnapshot

Return content-free process-local staging capacity state.

Release source · Runtime guarantees · Capability guides

DockerWorkspaceTransferLimits

from cayu.environments import DockerWorkspaceTransferLimits

Finite copy-in/copy-back limits for one coding container.

Bases: BaseModel.

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
max_files	int	Field(default=10000, ge=1, le=100000)
max_file_bytes	int	Field(default=8 * 1024 * 1024, ge=1, le=64 * 1024 * 1024)
max_total_bytes	int	Field(default=64 * 1024 * 1024, ge=1, le=1024 * 1024 * 1024)
max_archive_bytes	int	Field(default=128 * 1024 * 1024, ge=1024, le=2 * 1024 * 1024 * 1024)

Release source · Runtime guarantees · Capability guides