cayu.runners.docker_workload

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.

DockerImageIdentity

from cayu.runners import DockerImageIdentity

Trusted immutable image selection admitted before a coding session.

Registry images use a digest-pinned reference. A trusted locally built image may use a tag only when content_digest names the exact Docker image ID expected after allocation.

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
reference	str	Field(max_length=512)
content_digest	str | None	Field(default=None, pattern='^sha256:[0-9a-f]{64}$')

validate_reference (method)

DockerImageIdentity.validate_reference(value: str) -> str

validate_immutable_identity (method)

DockerImageIdentity.validate_immutable_identity() -> Self

fingerprint (property)

DockerImageIdentity.fingerprint() -> str

Return the stable non-secret identity used by admission evidence.

Release source · Runtime guarantees · Capability guides

DockerTmpfsMount

from cayu.runners import DockerTmpfsMount

One bounded guest-writable tmpfs mount.

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
target	str	Field(max_length=4096)
size_bytes	StrictInt	Field(ge=1024 * 1024, le=16 * 1024 * 1024 * 1024)
mode	StrictInt	Field(default=448, ge=0, le=4095)
noexec	StrictBool	True

validate_target (method)

DockerTmpfsMount.validate_target(value: str) -> str

Release source · Runtime guarantees · Capability guides

DockerWorkloadRestrictions

from cayu.runners import DockerWorkloadRestrictions

Normalized Docker controls for one explicitly trusted workload.

The value intentionally has no raw docker run argument escape hatch. Capability drop is unconditional; capability_add is the explicit, empty-by-default add-back set.

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
home_directory	str	Field(default='/tmp/cayu-home', max_length=4000)
uid	StrictInt	Field(default=1000, ge=1, le=2 ** 31 - 1)
gid	StrictInt	Field(default=1000, ge=1, le=2 ** 31 - 1)
read_only_root	StrictBool	True
no_new_privileges	StrictBool	True
capability_add	tuple[str, ...]	()
pids_limit	StrictInt	Field(default=128, ge=1, le=32768)
memory_bytes	StrictInt	Field(default=512 * 1024 * 1024, ge=16 * 1024 * 1024, le=1024 * 1024 * 1024 * 1024)
memory_swap_bytes	StrictInt	Field(default=512 * 1024 * 1024, ge=16 * 1024 * 1024, le=1024 * 1024 * 1024 * 1024)
cpu_period_us	StrictInt	Field(default=100000, ge=1000, le=1000000)
cpu_quota_us	StrictInt	Field(default=100000, ge=1000, le=2 ** 53 - 1)
shm_size_bytes	StrictInt	Field(default=64 * 1024 * 1024, ge=1024 * 1024, le=16 * 1024 * 1024 * 1024)
tmpfs	tuple[DockerTmpfsMount, ...]	(DockerTmpfsMount(target='/tmp', size_bytes=64 * 1024 * 1024, mode=1023, noexec=False), DockerTmpfsMount(target='/workspace', size_bytes=256 * 1024 * 1024, mode=488, noexec=False))

validate_capability_add (method)

DockerWorkloadRestrictions.validate_capability_add(value: tuple[str, ...]) -> tuple[str, ...]

validate_tmpfs (method)

DockerWorkloadRestrictions.validate_tmpfs(value: tuple[DockerTmpfsMount, ...]) -> tuple[DockerTmpfsMount, ...]

validate_resource_relationships (method)

DockerWorkloadRestrictions.validate_resource_relationships() -> Self

validate_home_directory (method)

DockerWorkloadRestrictions.validate_home_directory(value: str) -> str

home_environment (property)

DockerWorkloadRestrictions.home_environment() -> dict[str, str]

Non-secret, versioned by the restrictions identity, disposable tool state.

user (property)

DockerWorkloadRestrictions.user() -> str

Return Docker’s canonical numeric user/group selector.

supports_strict_privilege_evidence (property)

DockerWorkloadRestrictions.supports_strict_privilege_evidence() -> bool

Return whether the controls support Cayu’s strict privilege claims.

run_args (method)

DockerWorkloadRestrictions.run_args() -> tuple[str, ...]

Project the typed value into deterministic docker run arguments.

fingerprint (property)

DockerWorkloadRestrictions.fingerprint() -> str

Return the stable non-secret identity of all normalized controls.

Release source · Runtime guarantees · Capability guides