cayu.runners.docker

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_DOCKER_CWD

from cayu.runners import DEFAULT_DOCKER_CWD

DEFAULT_DOCKER_CWD = '/workspace'

Release source · Runtime guarantees · Capability guides

DEFAULT_DOCKER_IMAGE

from cayu.runners import DEFAULT_DOCKER_IMAGE

DEFAULT_DOCKER_IMAGE = 'debian:stable-slim'

Release source · Runtime guarantees · Capability guides

DockerCloseAction

from cayu.runners import DockerCloseAction

DockerCloseAction = Literal['remove', 'stop', 'none']

Release source · Runtime guarantees · Capability guides

DockerContainerOwnershipError

from cayu.runners import DockerContainerOwnershipError

Docker allocation did not yield an exact owned container identity.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

DockerRunner

from cayu.runners import DockerRunner

Executes commands inside a plain Docker container via the docker CLI.

Isolation is a parameter: pass runtime="runsc" (gVisor) or "kata" (microVM) to create for a hardened boundary; the default (runc) is a convenience tier for trusted development, CI, conformance, and packaging, not a security boundary. Cayu never selects it implicitly for untrusted code. The host docker process receives only an explicit operational allowlist; the containerized command receives only the explicit per-call env plus declared secret_env, carried through a private --env-file so values are never in host-visible argv or the Docker CLI’s own process environment. secret_env entries are resolved through secret_resolver at exec time and redacted from captured output. Private-registry credential helpers that need additional host variables must receive their names explicitly through docker_cli_env_allowlist; those trusted grants reach only the host-side Docker CLI and its helpers, never the container command.

Bases: Runner, RunnerBinaryStreamCapability, DurableCommandRunner.

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	'docker'
default_cwd	str	'/'
system_execution_mode	RunnerSystemExecutionMode	'shared'

workload_authority (method)

DockerRunner.workload_authority(name: str)

Declare a shipped workload only for its exact selected image.

execution_environment_authority (method)

DockerRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

DockerRunner.output_secret_values_present() -> bool

Declare whether Docker resolves runner-owned secret environment values.

browser_control_endpoint_reachable (method)

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

DockerRunner.browser_recording_supported() -> bool

Docker samples the active page and finalizes recordings before disposal.

execution_profile_identity (property)

DockerRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

preflight_exec (method)

DockerRunner.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 Docker’s exact transport contract without side effects.

exec (method)

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

await_pending_command_settlement (method)

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

Revalidate one exact strict container without extending stale claims.

execution_admission_candidate (method)

DockerRunner.execution_admission_candidate()

Return capability evidence for this exact Docker execution target.

collect_execution_admission_candidate (method)

async DockerRunner.collect_execution_admission_candidate()

Re-observe the exact strict container after lifecycle-owned setup.

execution_admission_candidate_for (method)

DockerRunner.execution_admission_candidate_for(requirements)

execution_admission_observer (method)

DockerRunner.execution_admission_observer(requirements)

collect_execution_admission_candidate_for (method)

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

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

is_closed (property)

DockerRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

DockerRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

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

binary_stream_capability (method)

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

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

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

aexit (method)

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

exec_stream (method)

async DockerRunner.exec_stream(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: BinaryIO | None=None, stdout: BinaryIO | None=None, stdout_limit_bytes: int | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

prepare_command_receipt (method)

DockerRunner.prepare_command_receipt(identity: dict[str, Any], *, command: ExecCommand, cwd: str | None, env: dict[str, str] | None, timeout_s: int, output_limit_bytes: int) -> dict[str, Any] | None

exec_with_receipt (method)

async DockerRunner.exec_with_receipt(command: ExecCommand, *, receipt: dict[str, Any], redactor: SecretRedactor, cwd: str | None, env: dict[str, str] | None, env_remove: tuple[str, ...]=(), timeout_s: int | None, stdin: str | None, output_limit_bytes: int | None) -> ExecResult

observe_command_receipt (method)

async DockerRunner.observe_command_receipt(identity: dict[str, Any], receipt: dict[str, Any]) -> ExecResult | None

container_reference (property)

DockerRunner.container_reference() -> str

Return the exact ID when Cayu owns one, otherwise the legacy name.

container_removed (property)

DockerRunner.container_removed() -> bool

Whether this owner has positively completed removal of its container.

Closed execution alone is insufficient: stopping or detaching a runner does not prove that its workspace has been destroyed.

init (method)

DockerRunner.__init__(name: str, *, default_cwd: str=DEFAULT_DOCKER_CWD, close_action: DockerCloseAction='none', docker_path: str | None=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, secret_env: Sequence[SecretEnv] | Mapping[str, SecretRef]=(), secret_resolver: SecretResolver | None=None, credential_mode: CredentialModeInput=CredentialMode.RAW_ENV, allow_raw_secret_env: bool=True, env_overlay: Mapping[str, str] | None=None, _env_overlay_secret_values_present: bool | None=None, docker_cli_env_allowlist: Sequence[str]=(), image: str | None=None, _container_id: str | None=None, _runtime_evidence: _DockerRuntimeEvidence | None=None, _strict_seccomp_profile: str | None=None, _strict_immutable_input_mounts: Sequence[DockerImmutableInputMount]=(), _execution_environment_authority: ExecutionEnvironmentAuthority | None=None) -> None

resolve_container_id (method)

async DockerRunner.resolve_container_id(name: str, *, docker_path: str | None=None) -> str | None

Resolve one exact Docker name without authorizing replacement.

require_allocation_identity (method)

async DockerRunner.require_allocation_identity(container_id: str, *, allocation_identity: str, docker_path: str | None=None) -> None

Validate immutable creation metadata by exact ID without guest execution.

container_exists (method)

async DockerRunner.container_exists(container_id: str, *, docker_path: str | None=None) -> bool

Return exact presence only after a successful daemon lookup.

create (method)

async DockerRunner.create(name: str, *, image: str=DEFAULT_DOCKER_IMAGE, runtime: str | None=None, mount_path: str | None=None, default_cwd: str | None=None, close_action: DockerCloseAction='remove', setup_commands: tuple[str, ...]=(), docker_path: str | None=None, replace: bool=True, 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, secret_env: Sequence[SecretEnv] | Mapping[str, SecretRef]=(), secret_resolver: SecretResolver | None=None, credential_mode: CredentialModeInput=CredentialMode.RAW_ENV, allow_raw_secret_env: bool=True, network: str | None=None, extra_hosts: Sequence[str]=(), env_overlay: Mapping[str, str] | None=None, _env_overlay_secret_values_present: bool | None=None, ca_mount: tuple[str, str] | None=None, seccomp_profile: str | None=None, docker_cli_env_allowlist: Sequence[str]=(), image_identity: DockerImageIdentity | None=None, workload_restrictions: DockerWorkloadRestrictions | None=None, required_executables: Sequence[str]=(), executable_probes: Sequence[ToolExecutableRequirement]=(), toolchain_profile_fingerprint: str | None=None, immutable_input_mounts: Sequence[DockerImmutableInputMount]=(), allocation_identity: str | None=None, _execution_environment_authority: ExecutionEnvironmentAuthority | None=None) -> DockerRunner

Start a long-lived container and return a runner bound to it.

With mount_path the host dir is bind-mounted at the same absolute path (convenience; pair with LocalWorkspace). Without it, an in-container default_cwd is created (hardened; pair with RunnerWorkspace, which needs python3 — install it via setup_commands). runtime is passed to docker run --runtime (e.g. runsc/kata). setup_commands run as root.

For virtual egress, network attaches the container to a Docker network (e.g. an --internal one that blocks direct internet), extra_hosts adds --add-host entries, ca_mount bind-mounts a (host_path, guest_path) CA read-only, and env_overlay is applied to every exec’s environment (after model env, so it cannot be unset).

seccomp_profile applies an explicit host-side Docker seccomp profile to the container. docker_cli_env_allowlist explicitly grants named host environment variables to the trusted Docker CLI and its credential helpers. It is for registry or daemon authentication only and never enters the guest. Managed containers always use Docker’s minimal init as PID 1 so cleanup descendants orphaned by a worker exit are reaped after they finish.

image_identity plus workload_restrictions selects the strict, evidence-bearing path. It requires an exact no-network, no-writable-host-mount, credential-free container and replace=False; manager-issued immutable input mounts are the only supported host projections. The resulting runner retains the full container ID and verifies the live Docker inspection and root write refusal before it can be exposed.

reconnect_strict (method)

async DockerRunner.reconnect_strict(name: str, *, container_id: str, image_identity: DockerImageIdentity, workload_restrictions: DockerWorkloadRestrictions, default_cwd: str=DEFAULT_DOCKER_CWD, runtime: str | None=None, seccomp_profile: str | None=None, docker_path: str | None=None, required_executables: Sequence[str]=(), executable_probes: Sequence[ToolExecutableRequirement]=(), toolchain_profile_fingerprint: str | None=None, immutable_input_mounts: Sequence[DockerImmutableInputMount]=(), _execution_environment_authority: ExecutionEnvironmentAuthority | None=None) -> DockerRunner

Reattach to one exact strict container after re-verifying live evidence.

execution_capability_evidence (method)

DockerRunner.execution_capability_evidence()

Describe Docker honestly and bind strict evidence to the exact container.

drain_failed_creations (method)

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

Join or retry retained constructor rollback without reallocating.

drain_failed_attachments (method)

async DockerRunner.drain_failed_attachments(*, timeout_s: float=DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS) -> int

Retry exact retained admission-probe cleanup without reconnecting.

fence_guest_processes_for_egress_cutover (method)

async DockerRunner.fence_guest_processes_for_egress_cutover() -> None

Terminate detached guest work while retaining container/workspace identity.

kill (method)

async DockerRunner.kill() -> bool

Remove the Docker container for shared runner cleanup diagnostics.

Release source · Runtime guarantees · Capability guides

DockerRuntimeConfigurationError

from cayu.runners import DockerRuntimeConfigurationError

The exact created container does not match its declared restrictions.

Bases: RuntimeError.

init (method)

DockerRuntimeConfigurationError.__init__(code: str) -> None

Release source · Runtime guarantees · Capability guides