CIP-10: Runner Container Runtime
Status: Draft
Type: Standards Track
Category: Core
Created: 2026-03-07
Requires: CIP-2, CIP-9
Type: Standards Track
Category: Core
Created: 2026-03-07
Requires: CIP-2, CIP-9
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.
Neocloud operator authority and economics
amends persistent workloads from the separate B, G, H and I per-network
heights: operator Stop and reason-bearing removal/termination, owner-consented
capacity pricing, and pool membership events. Below each height the existing
rule remains unchanged. From B2’s height, legacy
DeregisterWorkload accepts
the unreserved controller or a reserved-workload deployer; other deployer
removals of tenant workloads must use the reason-bearing operator verb.
Reserved workloads keep deployer registration and are not capacity-billed.1. Background
CIP-2 defines off-chain job dispatch, runner selection, and result submission. CIP-9 defines durable storage and runner access to volumes. Containers isolate dependencies from the host and bound resource use. They mount authorized volumes and report compute usage for on-chain settlement. Task containers execute a bounded job and are destroyed at exit. Persistent workloads keep a process warm across requests, with identity, ownership, health, and route eligibility controlled by an on-chain record. Both use the Container Registry at0x13.
2. Goal
Define one container execution contract covering image identity, runtime configuration, isolation, storage, lifecycle, and billing. The contract supports scripts, compiled binaries, local models, and model execution tools without prescribing application logic.3. Definitions
- Task container: An isolated process environment created for a CIP-2 job, subject to a wall-clock bound and destroyed after completion.
- Persistent workload: A container governed by a workload registry record (§17).
- OCI runtime bundle: A root filesystem and OCI runtime configuration used to launch a container. The filesystem is constructed from a registered image under §5.8; OCI manifest and layer pulls are outside that path (§16.3).
- Image reference: A protocol base-image enum or registered 32-byte rootfs digest (§5).
- Runtime configuration: The image, command, resource tier, network policy, and minimum isolation tier carried by a container job (§11.1).
- Scratch filesystem: Writable, ephemeral container storage. Durable state belongs in authorized CIP-9 volumes.
- Base image: A whole-rootfs image registered under §5.5 with a reserved name (§5.11). Protocol
BaseImageenum keys resolve through those names; application deltas pin their base by digest. - Registry name: A human-readable name in the Container Registry: an image name, a resource-class name, or a workload name. All follow the grammar in §5.11.
- Reserved name: A registry name beginning with
cby-. Only agenesis.system_deployerssender may bind one (§5.11).
4. Design Overview
4.1 Architecture
A Runner node is a machine (physical or virtual) that runs an OCI-compatible container runtime. When a Runner is selected for a CIP-2 task, it:- Resolves the registered image, fetches and composes it on a cache miss, and verifies its digest (§5).
- Creates a container with the specified resource limits and network policy.
- Mounts CIP-9 volumes as FUSE filesystems inside the container.
- Starts the container entrypoint.
- Monitors execution until completion, timeout, or crash.
- Commits storage manifests and submits results onchain.
- Destroys the container.
4.2 Relationship to Existing CIPs
- CIP-2 (Off-Chain Compute): Container jobs carry
JobType::Container { runtime: RuntimeConfig }(§11.1). Runner selection and result handling follow CIP-2 with the container capability filter (§7.4). - CIP-9 (Runner Attached Storage): CIP-9 volumes specified in
volume_attachmentsare mounted inside the container as FUSE filesystems at/mnt/volumes/{name}/. The FUSE daemon and sync daemon (CIP-9 §12.1) run as sidecar processes alongside the container. - CIP-3 (Fee Model): Container resource usage (CPU-seconds, memory-seconds, GPU-seconds) uses attestation-based billing, metered externally by Runner cgroup counters, settled onchain via
BillingAttestation(§12.3). This is distinct from CIP-3 Cycles/Cells, which are metered directly by the VM during transaction execution.
5. Container Images
5.1 Image Distribution
Image registration is permissionless and CBFS-backed. A publisher registers the composed rootfs digest and a locator in a public CBFS volume they own and fund, following §5.6’s registration-before-publication order. Runners fetch, compose, verify, and cache the tree on demand. A delta pins a whole-rootfs base by digest; protocol base names are reserved forsystem_deployers (§5.5).
5.2 Artifact Identity and Digest
A registered image combines a base and a delta.- The registered digest MUST be the blake3 rootfs digest of the composed tree, computed with the recipe below. No second identity is introduced;
ImageRef::Digestcontinues to carry it. - The delta is the archive specified in §5.3. It carries the installed off-chain dependency group and the project source and nothing else.
- The base is a complete rootfs, itself a registered image.
base = Noneregisters a whole-rootfs image: the archive is the complete tree and composition is the identity function. Protocol base images MUST be registered through this same instruction withbase = None; there is no separate provisioning path. - Composition is one level deep. A delta MUST NOT be composed onto another delta image. Deeper chains are deferred.
blake3(walk(root, root)) where walk is the following:
- Sorting is per directory, by
file_name(), not a global sort over full paths. A directory’s subtree is emitted inline between its ownpath ‖ NUL ‖ mode ‖ NULprefix and its trailingNUL; there is no separate directory terminator or depth marker. - The mode is the full
st_modeas a u32 in little-endian byte order, not an octal string and not masked to permission bits. - Paths and symlink targets are hashed via
to_string_lossy(), so a non-UTF-8 name hashes as its replacement-character rendering. Publishers MUST NOT rely on this; §5.8 rejects non-UTF-8 archive members outright. - Entries that are neither a regular file, a directory, nor a symlink contribute path, mode, and the trailing NUL only. This case cannot arise in a composed image because both the CLI assembler and the runner’s extractor refuse such entries, but the recipe defines it.
- The rootfs root directory’s own mode is not hashed. The walk emits entries under the root, never the root itself.
runner-node image-digest <rootfs> prints this digest for a tree.
5.3 Delta and Composition
The delta archive format is consensus-relevant: two publishers composing the same base with the same logical contents MUST arrive at the same digest, or the digest stops being a shared identity. The delta MUST be a gzip-compressed tar archive. (proposed: GNU-format headers, not POSIX ustar.)- Every member path MUST be relative and MUST be under
app/. Absolute paths,..components, and members outsideapp/are invalid. - The archive MUST contain the
app/directory entry itself, so that a delta contributing no files still creates the mount point. An archive with no members at all is invalid. (proposed: a delta consisting only ofapp/is valid.) uid,gid,mtime,atime,ctime, device major and minor, and owner and group names MUST all be normalized to0/ empty. The gzip header’s mtime MUST be0and its OS byte255(unknown). None of these fields participate in the digest. The digest hashes only relative path, mode, and content or link target (§5.2). Normalizing the archive fields makes the archive byte-reproducible.- Members MUST be emitted in a total order over archive path bytes.
- setuid, setgid, and sticky bits MUST be stripped at packaging time.
- Symlink modes MUST be normalized to
0o777and directory modes created by the assembler to0o755. This is not cosmetic: Linux reports symlink modes as0o777while macOS applies the process umask, and the recipe hashes the mode, so an unnormalized symlink digests differently on the two platforms.
- regular files MUST be
0o644, or0o755when any execute bit was set on the source; - directories MUST be
0o755; - symlinks MUST be
0o777; and - setuid, setgid, and sticky bits MUST be stripped.
umask 022 and umask 077 yields two different digests for one logical input.
Python installers leave builder-specific residue. Before installed-package output enters the delta:
- a
*.dist-info/directory MUST contain onlyMETADATA,WHEEL,top_level.txt,entry_points.txt,namespace_packages.txt,INSTALLER,REQUESTED, and license or notice files; - installer-created
bin/,RECORD,direct_url.json,uv_cache.json,.lock, and__pycache__entries MUST be removed; and - bytecode MUST NOT be compiled into that output.
/app entry. The delta would replace the base’s /app, making the composed digest depend on which version takes precedence. The trees would no longer form a union.
Composition MUST clone the base into a fresh tree preserving every mode bit, symlink target, and hardlink structure, then extract the delta at <root>/app. Extraction MUST preserve member modes exactly as recorded. An implementation that hardlinks regular files out of the base to avoid copying MUST unlink a destination before writing over it, or the write lands on the base’s inode and corrupts the pinned base for every other image composed from it.
5.4 Storage and Availability
The delta object MUST live in a CBFS volume, and the on-chainStorageCommitment for that volume is the sole availability signal for the image. No new storage service, index, or pinning service is introduced.
- The volume MUST be
Visibility::Public(proposed, a private volume’s DEK is not releasable to an arbitrary drawn runner, so a private locator would register an image nobody can fetch). Visibility is fixed at volume creation and is not mutable thereafter, so it is checked once at registration and admission need not re-check it. - Rent is the hosting fee. There is no separate image-hosting charge, no protocol-funded mirror, and no expiry timer independent of rent. A volume that rots takes its images with it:
statusleavesActive, and §5.7 stops admitting jobs that reference it. - The publisher MUST keep the volume funded for as long as any actor pins one of its digests. Escrow top-up is the existing CIP-9 deposit path; nothing in this section changes it.
- A publisher who keeps paying rent may still overwrite or delete the object at
object_path, or commit a manifest that no longer contains it, while the volume staysActiveand the registration stays admissible. Admission cannot detect this; a cold runner fails to fetch the image. Runners MUST treat it as a fetch failure (§5.8) and MUST NOT treat it as a job failure. Publishers MUST NOT mutate or remove an object that any live registration points at; making the object immutable for the life of the registration is the publisher’s obligation, unenforced by the chain in this specification.
5.5 Image Registration
RegisterImage (160) and DeregisterImage (161) are the only image registration instructions. Base and application images share the same registry object and registration path, because a second path would be a second trust path to the same digest index (proposed, opcodes 160/161 rather than a fresh pair at 219/220).
162–163 (resource classes) are
system_deployers-gated; 160–161 are permissionless, except that binding a reserved name (§5.11) requires a system_deployers sender. Settlement configuration and disputes follow §11.4. The opcode-uniqueness test MUST cover 160–165.
Wire encoding follows the codec’s existing container-instruction conventions: the opcode byte precedes the fields in declaration order. Reads bound the length of Vec<u8> and read [u8; 32] at its fixed width (proposed, in full):
digest equal to zero; base_digest present and equal to zero; a non-empty name outside the §5.11 grammar; object_path longer than 256 bytes; an Option tag other than 0 or 1; non-canonical varint lengths; trailing bytes; and any payload layout for opcode 160 or 161 other than the shapes in this section. All other checks in this section run at execution. Decode tests MUST show that the previous name/digest/size and name-only RegisterImage layouts fail to decode.
base_digest carries the base’s own registered digest. It does not carry a BaseImage enum value. The BaseImage enum key is resolved to a digest exactly once, by the publishing tool, at registration time, and the locator then pins that digest forever. A runner composing an image MUST use base_digest from the locator and MUST NOT perform a name lookup at fetch time. Without this, rebinding a protocol base name would silently change the composed tree of every image built on it, and every such image’s registered digest would stop matching what a runner reconstructs.
A name is a mutable pointer; the pin is the digest. Rebinding a name (§5.11) moves only the name entry: every locator already registered keeps its own base_digest, so images composed on an earlier base release still reconstruct the same tree, and that earlier base cannot be deregistered while anything references it.
object_hash is the CBFS plaintext content hash. It MUST equal the ObjectDescriptor.content_hash CBFS records for the object: BLAKE3 over the plaintext object bytes. For a delta object these are the compressed archive bytes before CBFS encryption. An assembler’s SHA-256 build-cache value, if any, is not the registry hash.
The name-to-digest index lets clients resolve an image by name, including the protocol BaseImage enum keys (§5.10).
- An empty
namegives an ordinary registration addressed by digest. The empty case MUST bypass the name grammar, which rejects an empty name; no name entry is written. - If
nameis non-empty, it MUST satisfy §5.11 and its binding rules: a reserved name requires asystem_deployerssender, and any other name is bound first-come to its first registrant. An account that bindscby-runner-pythoncontrols everyImageRef::Base(RunnerPython)job on the chain.
RegisterImage MUST reject unless all hold:
digestis non-zero, the signer holds no locator for it, live or tombstoned, and the digest has fewer thanMAX_LOCATORS_PER_DIGEST = 4locators. Each publisher’s locator is create-only. Several publishers may register the same digest; each locator is another source for the same composed tree, which the digest commits to, and may point at a different delta object. Tombstoned locators count toward the cap until reaped.- The
StorageCommitmentforvolume_idexists at the Storage Manager (0x0A) under its volume key, the same read the registry performs for workload mounts (§17.5). commitment.status == VolumeStatus::Active. Registering into a volume already in grace is refused; grace only extends an existing registration (§5.7).commitment.visibility == Visibility::Public(proposed, §5.4).commitment.ownerequals the transaction signer.object_pathis non-empty, valid UTF-8, and within its cap;object_hashis non-zero.delta_bytes <= MAX_IMAGE_DELTA_BYTESandrootfs_bytes <= MAX_COMPOSED_ROOTFS_BYTES(§5.9).- If
base_digest = Some(d),dhas a live (non-tombstoned) locator whose ownnameis reserved, whose ownbase_digestisNone(one-level composition), and whose volume is live under §5.7. Base status comes from that locator’sname. The name entry does not confer base status. Composition bases are platform images: a first-come name confers no base status (proposed, a composed image whose base is unreachable is unrunnable on a cold runner; checking it at registration converts a run-time failure into a submit-time one). - If
nameis non-empty, the §5.11 grammar and binding rules: a name undercby-example-rejects; a reserved name requires asystem_deployerssender; any other name is unbound or controlled by the signer. A registration under a reserved name MUST be a whole-rootfs image (base_digest = None); an unreserved name MAY name a composed image. - The volume’s live registration count is below
MAX_REGISTRATIONS_PER_VOLUME(§5.9). A registration is live for this purpose until its locator record is reaped: a tombstoned-but-unreaped locator still occupies its slot, because its bytes are still on chain.
- the index mapping digests to names at
system:container_registry:digest:<digest>, which §5.7 admission and name-by-digest lookups read. For an unnamed image the indexed value MUST be the lowercase hex of the digest (proposed, the index value is a JSON string and admission only tests presence, so an empty string would be indistinguishable from a corrupt entry; hex gives clients a stable display name). Note that 64 hex characters is exactlyCONTAINER_NAME_MAX_LEN, so the hex form fits that bound with no slack. The index value is written directly and is not validated as a registry name; - for a named registration, the name entry at
system:container_registry:image:<name>(§11.2), withsize_bytes = rootfs_bytesandcontrollerset under §5.11; - for a composed registration, an increment of the base’s composed reference count at
system:container_registry:composed_ref:<base_digest>(raw digest bytes), au64JSON-decimal count of the unreaped composed images that pin that base; it is decremented when the composed image is reaped, and a base’s last live locator cannot be tombstoned while it is nonzero (ComposedReferenceInUse). A named composed registration, which check 9 allows only under an unreserved name, writes both the name entry and this count; - the locator list at
system:container_registry:image_locator:<digest>, the suffix being the raw 32 digest bytes: a serde-JSON array of at mostMAX_LOCATORS_PER_DIGESTImageLocatorvalues, kept sorted byregistered_at, then publisher address bytes, with one entry per publisher. Readers MUST reject a list that is longer, unsorted, repeats a publisher, or holds another digest. Every registry mutation rewrites the digest index from it: thenameof the first live locator that has one, otherwise the digest’s lowercase hex; - the per-volume registration counter at
system:container_registry:image_count:<volume_id>(proposed), au64JSON-decimal count in the same style as the workload reference counts, incremented here and decremented when the locator is reaped, not when it is tombstoned; and - the image listing index entry
il:‖ digest (§5.6), when this registration is the digest’s first locator.
base_digest is promoted on chain, because it is the only one composition depends on. The rest stay in the off-chain descriptor; if the chain later needs to reject an image built for the wrong platform, platform is the field to add.)
DeregisterImage { digest } acts on the sender’s own locator and MUST reject when the sender holds none; a locator registered under a reserved name additionally requires a system_deployers sender. It MUST refuse to tombstone the digest’s last live locator while the image is referenced by a persistent workload, reusing the existing reference count at system:container_registry:workload_ref:image:<digest>. A nonzero count rejects with WorkloadReferenceInUse. A mirror may be tombstoned while another locator stays live.
Deregistration is two-phase, both phases submitted under the same opcode by the same publisher.
In phase 1, the first successful DeregisterImage sets tombstoned = true and tombstoned_at = current_block on the sender’s own locator, and recomputes the digest index; when the digest has no other live locator, the index entry is deleted and admission stops. It does not delete the locator, does not decrement the per-volume count, and never deletes a name entry (§5.11). The locator is retained so that a job admitted before deregistration can still be resolved by the runner that draws it. The sender cannot re-register a digest it has tombstoned (check 1).
In phase 2, a second DeregisterImage for the same digest MUST delete the sender’s locator, decrement the per-volume count, decrement the base’s composed reference count when base_digest is Some, and delete the image listing index entry (§5.6) when the reaped locator was the digest’s last, freeing the slot. It MUST reject unless current_block >= saturating_add(tombstoned_at, IMAGE_TOMBSTONE_GRACE_BLOCKS), inclusive at the exact boundary, the same comparison shape the registry uses for persistent-workload stale cleanup. IMAGE_TOMBSTONE_GRACE_BLOCKS = 600 (proposed) is the grace period. Its sizing assumes a LIVENESS_TIMEOUT_BLOCKS = 100 redraw and a 300-block billing-dispute window, with headroom for one additional redraw. The dispute window is job-configured (§12.3), so this is a sizing assumption, not a bound on every in-flight reference. A job admitted before the last locator of its digest is reaped, and still unfetched afterwards, fails to fetch on every cold Runner and is recovered only through the liveness redraw path (§5.8). Reference counting in-flight jobs per digest was rejected: it would add a write to every container job’s submit and settle path to save a bounded, self-clearing record.
Reaping is never automatic. The publisher explicitly reaps the locator to reclaim its slot. Until then, the slot stays occupied.
Deregistration does not revoke images already cached by runners; it only stops new admissions.
5.6 Resolution and Publication
Registry records are read by exact key: any key length, through the exact-key storage read RPC (GET /actors/{addr}/storage/value?key=) or the proof route. An actor-storage key of at most 64 bytes is stored verbatim in key order and is prefix-scannable; a longer key is stored as the keccak256 of the key and is reachable only by an exact read. Most registry record keys are longer than 64 bytes, so every listing this CIP requires is served by a dedicated index key of at most 64 bytes, never by scanning record keys; the Runner hints wr: and wp: (§17.3) follow the same rule. Resolution is by digest: a client holding a digest reads system:container_registry:image_locator:<digest> directly. A client holding a name reads system:container_registry:image:<name> for the digest the name points at, then resolves that digest. Composed images and ImageRef::Digest jobs pin digests. A client that resolves an unreserved name MUST show the name’s controller and the digest it resolved, and MUST record that digest, never the name, in whatever it submits, such as a workload record or a job. A name is read once, when it is resolved, and is never authority afterwards. The only execution-time name lookup is an ImageRef::Base job, whose enum key resolves through its reserved name (§5.10).
cowboy container register-image submits RegisterImage with the locator fields, and cowboy container deregister-image selects the sender’s locator by --digest. cowboy container images lists registrations with each volume’s status, so a rotted image is visible before a job is submitted.
The Container Registry keeps one binary index key per registered digest: ASCII il: followed by the 32 raw digest bytes (35 bytes), whose value is the 32-byte digest. It is written when a digest gains its first locator and deleted when its last locator is reaped (§5.5), not at tombstone, so a tombstoned digest stays listed until it is reaped and its locator list shows the tombstone. Clients list images by scanning the prefix il: with a cursor and exact-reading each digest’s locator list.
The publishing tool MUST, in this order:
- submit
RegisterImageand observe its commitment on chain; then - make the delta object publicly readable; and only then
- disclose the digest.
MAX_LOCATORS_PER_DIGEST = 4 locators per digest, one per publisher. Admission accepts a job if any locator serves, and a runner tries them in a fixed total order: registered_at ascending, then publisher address bytes ascending. Ordering by the name controller was rejected because the name a digest shows is itself first-come. A front-runner that registers under its own name would still go first. Because a second publisher only adds a source, registering a digest first cannot deny its real publisher unless all MAX_LOCATORS_PER_DIGEST slots are taken before it registers (§14.2). The locator cap bounds storage; K unusable locators can delay fetching by K fetch timeouts.
5.7 Admission
A job whoseImageRef is a Digest is admissible iff both hold, evaluated at submit, before dispatch commits:
- the digest resolves through the digest index (§5.5), checked inside the container escrow handler; and
- some locator in the list is live and its volume commitment loads with
statusexactlyActiveor exactlyGracePeriod.
VolumeStatus is the chain’s, which has six variants: PendingMpkSetup, MpkSetupFailed, Active, GracePeriod, Deleted, GarbageCollecting. The CBFS client’s mirror has only four variants. A blacklist written against the four-variant mirror would admit PendingMpkSetup and MpkSetupFailed volumes, and would admit every variant added in the future by default. Every status other than Active and GracePeriod, present or future, MUST reject; so MUST a missing commitment, an unreadable locator, and a tombstoned locator.
As in the gateway’s public-volume policy, the manifest root stays immutable during grace, so committed bytes remain fetchable. A publisher has the grace window to resume rent payments before serving stops.
For a composed image, the base digest MUST also have a serving locator under the same whitelist that carries a reserved name and no base_digest (§5.5 check 8, §5.11): a first-come name never makes an image a base.
Rejection MUST fail the whole submit transaction, matching the surrounding escrow handler’s atomicity contract: no partial escrow may survive an inadmissible image.
5.8 Fetch, Compose, Verify, and Cache
On a digest job for which<image_root>/<hex-digest>/rootfs is absent, the runner MUST, in order:
- Read the locator list for the digest from the Container Registry, proof-checked, and try its live locators on serving volumes in §5.6 order until one installs; when fetching a base, skip locators without a reserved name or with a
base_digest. The steps below apply to each candidate; the digest is written off only after every candidate fails. - Resolve the base from
base_digest, never from a name. Ifbase_digest = Some(d), ensuredis installed locally, fetching it by this same procedure first. Bases are pinned once installed. - Fetch the object at
object_pathfrom the public volume using the CBFS SDK client used for runner storage. The fetch MUST be subject toIMAGE_PULL_TIMEOUT_SEC(§13) and MUST abort as soon as the streamed byte count exceedsmin(delta_bytes, MAX_IMAGE_DELTA_BYTES). A publisher who under-declaresdelta_bytescannot make a runner stream more than it agreed to. - Verify the object hash against
object_hashbefore anything is extracted. A mismatch aborts; the bytes MUST NOT be written into the image root. - Extract with a hardened extractor into a private temporary directory on the same filesystem as the image root, under an unprivileged uid. The extractor MUST reject, and abort the whole fetch on, any of: an absolute member path; any
..component; a member not underapp/; a symlink or hardlink whose resolved target escapes the extraction root; a device, FIFO, or socket member; a member with setuid, setgid, or sticky bits; a member path that is not valid UTF-8; a duplicate member path; and a cumulative uncompressed size exceedingmin(rootfs_bytes, MAX_COMPOSED_ROOTFS_BYTES). Sizes MUST be enforced during streaming, not from archive-declared headers. Member modes MUST otherwise be preserved exactly (§5.3). - Compose the extracted tree onto a mode-, symlink- and hardlink-preserving copy of the pinned base at
/app, per §5.3. Composition MUST NOT let the delta replace or shadow any path outside/app. - Recompute the §5.2 rootfs digest over the composed tree and compare with the registered digest. Any mismatch MUST abort and delete the temporary tree.
- Install atomically by renaming the verified tree into
<image_root>/<hex-digest>/rootfs. A partially fetched or unverified tree MUST never be observable at that path. The rootfs is mounted read-only into every sandbox. Successful digest verification is cached for the runner process lifetime; operators MUST protect installed verified trees against host-side mutation while they are in use. Read-only sandbox mounts do not prevent host edits, and the cached check is not continuous integrity monitoring. - Record the fetch in the cache index for LRU accounting.
RUNNER_IMAGE_CACHE_BYTES, §5.9), LRU eviction by last use, registered protocol base images never evicted, a per-digest lock so concurrent jobs on one digest fetch once, and at most one concurrent fetch per runner. Prefetch is demand-driven, never registration-driven: a runner MUST NOT fetch an image merely because it was registered, since registration is permissionless and a registration that no job uses must cost the fleet nothing. A runner MAY prefetch the image of a job it observes admitted on chain (a JobSubmit carrying a digest ref is visible before the draw resolves) so that a replacement draw after a liveness timeout finds a warm cache, subject to a per-runner budget (IMAGE_PREFETCH_BUDGET_BYTES_PER_HOUR, §5.9) and skipping digests already cached or in the negative cache. Prefetch MUST yield to the fetch for the runner’s own assignment and MUST respect the same quota and concurrency bound. Under this rule every byte a runner downloads corresponds to a job whose submitter paid escrow, and a popular image spreads through the fleet at the rate it is actually used.
Runners MUST also keep a per-digest negative cache:
- A digest whose fetch failed for a transient reason (timeout, relay unavailable, object temporarily missing) MUST NOT be retried until an exponential backoff has passed, starting at one fetch-timeout interval and doubling to a cap, so that a rotted or unpublished image cannot be re-fetched once per job assignment.
- A digest that failed verification because of an object-hash mismatch, hostile archive, or composed-digest mismatch MUST NOT be retried for the process lifetime. Verification failure is a deterministic property of the registered bytes, independent of transient conditions. Retrying it repeats the same work and lets an attacker consume runner bandwidth repeatedly with one registration.
timeout_blocks validation cap of MAX_JOB_TIMEOUT_BLOCKS = 1,000,000 service blocks; a larger value MUST be refused at submission. Expiry/retry/reap deadlines use the job-trio pause clock and admission-owned capacity described in CIP-2. Container billing and dispute deadlines keep their real-height semantics.
If any step above fails, the runner does not run the job. It MUST NOT submit a failed result for a fetch failure, because a fetch failure is a property of the runner’s attempt, not of the job. Before E3, the job is recovered by the chain-side liveness timeout: after LIVENESS_TIMEOUT_BLOCKS = 100 blocks with no result, the dispatcher draws a replacement committee excluding the original assignee and writes a JobTimeoutRecord. CancelReason::Reassigned on the CIP-11 wire is validator-initiated and is not a runner-side decline.
An unfetchable image costs the job a full 100-block timeout per drawn runner before redraw. The height-gated runner-initiated decline in §16.1 removes that timeout when active; before its height the timeout remains the required fallback.
5.9 Image Limits
The two byte caps are open values (proposed), to be set against measured cold-start latency.
5.10 Protocol Base Images
The protocol definesBaseImage::RunnerBase and BaseImage::RunnerPython (wire tags 0 and 1), with keys cby-runner-base and cby-runner-python. Both MUST be registered as whole-rootfs images under those reserved names through §5.5 before any job uses their enum keys. Other platform bases, such as cby-runner-node and cby-runner-rust, are reserved names without enum variants: projects reach them by digest, resolved from the name when they build. ML and agent-specific images use a registered digest rather than additional enum variants.
Application code and dependencies belong in the delta under
/app; the base is shared and cached across projects. Rust’s compiler and build tools are not needed in the runtime image. Image sizes depend on the recipe and MUST respect §5.9’s caps.
Applications pin their base by digest. Rebinding a base name does not modify existing composed images. Changing base or application bytes requires a new image digest and an authorized update of the caller’s image reference.
An agent image SHOULD provide the Unix tools required by its harness, such as a shell, file utilities, Python, and search tools. ML images require the model’s dependencies and, when GPU execution is supported, the matching device runtime (§8).
5.11 Registry Names
Image names, resource-class names, and workload names share one grammar. A registry name MUST:- be 3 to 63 bytes long;
- contain only lowercase ASCII letters
a-z, digits0-9, and hyphens-; - begin and end with a letter or digit; and
- contain no two consecutive hyphens.
xn--) look-alikes. The grammar is checked at decode for every instruction field that carries a name, so two implementations agree on which blocks decode.
A name beginning with cby- is reserved for the platform. Binding or rebinding a reserved name requires a genesis.system_deployers sender, in every name space. Clients MAY present a reserved name as an official platform object; an unreserved name carries no such claim. Documentation and examples MUST use names under cby-example-, which no sender may bind, system_deployers included, so a name copied from the docs never resolves to anyone’s object.
No registry name contains --. The form <registry name>--<suffix>, at most 63 bytes, is therefore free for identifiers the protocol or its tools generate in future, in fields defined for them, and can never collide with a name a person chose. No field defined by this CIP accepts it.
Binding.
Image names are permanent. An unreserved name’s
controller is fixed at first binding and never transfers to another party; only that controller can rebind it to another digest. A rebind is a named RegisterImage that adds the signer’s locator for the new digest, so a controller cannot point its name at a digest for which it already holds a locator, live or tombstoned (§5.5 check 1). A reserved name is controlled by whichever system_deployers sender last bound it, and any system_deployers sender may rebind it. Names cannot be released or deleted. Other publishers can mirror a digest but cannot re-point or delete its name, which belongs to its controller. Binding a name requires a registration that passes §5.5, in an Active, public volume (checks 3 and 4); holding it requires nothing. A name whose digest no longer serves, because every locator is tombstoned or on a volume outside Active and GracePeriod, still belongs to its controller and still resolves to that digest until the controller rebinds it. Trusting an unreserved name means trusting its controller for the name’s lifetime. Execution never depends on a name, because jobs, workloads, and composed images pin digests (§5.6), so the residual risk is the controller re-pointing its own name, which clients surface by showing the controller and the digest at resolution (§5.6). A workload name is unique only within its owning actor; the workload ID derives from both (§17.3).
The grammar, the reserved prefix, the cby-runner-* base keys, and the record layouts in this section and §17.3 take effect at genesis, together with the workload layout in §17.3.2. BaseImage::key() is also the submission string an SDK or CLI passes as image=, so the image= strings are cby-runner-base and cby-runner-python.
6. Runtime Environment
6.1 Filesystem
The image root is read-only and the process working directory is/. /tmp and /dev are writable tmpfs mounts, each capped at 65536k; /proc is a procfs mount. No /workspace directory is created by the runtime. Writable scratch storage is ephemeral; authorized CIP-9 mounts appear at /mnt/volumes/{name}. Mount access follows the volume’s authorization. It grants no general host-filesystem access. The host-side storage process prepares mounts before the container starts; the container uses ordinary file I/O.
6.2 Environment
The executor constructs the container environment withCOWBOY_JOB_ID (lowercase hexadecimal), COWBOY_VOLUME_ROOT=/mnt/volumes, and COWBOY_VOLUME_{NAME_UPPERCASE}=/mnt/volumes/{name} for each supplied mount. It MUST NOT inherit arbitrary host environment variables or expose host credentials. The COWBOY_ namespace is reserved for runtime metadata.
RuntimeConfig has no arbitrary env field. The one application-controlled entry into the environment is secret_env: a strictly ascending list of CIP-24 secret names (at most 8, each a plain CBSS key name [A-Z][A-Z0-9_]* of 1 to 128 bytes, never COWBOY_-prefixed) that the runner resolves through the job’s secret_refs and exposes as NAME=<plaintext> in the sandbox process environment. secret_env is the container form of an Http job’s runner.secret() slot (CIP-24 §5.2): the plaintext name rides in the runtime config, the {account, key_hash} authorization rides in secret_refs, and the runner MUST refuse a name that does not resolve in the authorized set (CIP-24 §3.8 step 1). The released value never enters the JobSpec, the result, or the image; it travels in-process from the release pipeline to the executor and is wiped when the run ends (CIP-24 §3.9, subprocess path). A job that names secrets without authorizing any is rejected at admission. A name that collides with a constructed COWBOY_* variable refuses the job.
A signing bundle reads a venue key from its environment, builds and signs the venue request offline, and prints the signed request. The actor then sends it with runner.http. Runner code contains no venue signing schemes, and the container needs no network. §18.3 shows the shape.
6.3 Command
A container job MUST provide a non-empty command vector. The wire format permits at most 256 arguments of at most 4,096 UTF-8 bytes each. The executor runs that command; it does not resolve an OCI image’sENTRYPOINT or CMD. RuntimeConfig has no working-directory override.
A model harness MAY run as the command and expose filesystem tools against authorized mounts. Model selection, prompts, tool behavior, and provider authentication belong to the harness. External model APIs additionally require the egress allowlist in §9.2.
6.4 User and Permissions
The OCI process uses UID/GID 0 inside the container. For rootless runc these IDs map to the invoking unprivileged host UID/GID. Container UID 0 does not grant host root privileges. All Linux capabilities are dropped andno_new_privileges is set. There is no allow_root option in RuntimeConfig.
Persistent workloads run as UID/GID 1000 under the user model in §17.2.1.
6.5 Offchain Functions
Python, Node and Rust function adapters expose the same actor-facing boundary: an awaitable call with one serializable input and one result, or an application error. The common CBOR value domain includes null, booleans, integers from-2^63 through 2^64-1, finite binary64 floats, text, bytes, lists and text-keyed maps. Bytes remain distinct from lists. Adapters MUST enforce common limits on encoded size, nesting and value count; arbitrary language objects do not cross this boundary.
The CLI supplies the language adapter; application projects need not contain Cowboy runtime source. Python and Node execute through their interpreters, while Rust’s adapter is compiled with the application. Every profile MUST follow the same image verification, environment (§6.2), isolation, resource, network and authorized-volume rules. Actor-side awaiting is independent of whether a function implementation is synchronous or asynchronous. Async execution does not grant network access or extend work beyond the invocation’s lifetime.
7. Resource Limits
7.1 Resource Declaration
Jobs select a resource class by name (RuntimeConfig.resource_tier); the Container Registry stores named resource classes for admission and pricing. A class contains:
ResourceLimits object is not part of RuntimeConfig. Resource-class registration is operational and restricted to system_deployers (§11.4). The class name is a registry name (§5.11).
7.2 Enforcement
The Standard sandbox uses cgroups v2 for CPU, memory, and PID limits: CPU excess is throttled and memory excess can trigger an OOM kill. The runner enforces a wall-clock timeout. Writable scratch MUST be bounded; durable volume limits follow CIP-9 authorization and quotas. A sandbox that runs without host-cgroup enforcement, such as the unsafe no-cgroups fallback, reportsmetered = false (§15). An unmetered bill is not evidence that resource limits were enforced.
7.3 Executable Tiers
The executor’s tier limits are:
A shorter job wall-time limit further bounds execution. Registered class values drive the compute escrow (§12.1), while these executor limits are local runtime policy. Operators MUST align advertised tiers, registered classes, and actual enforced capacity; changing a registry entry does not reconfigure the runner sandbox. For persistent workloads, §17.2 says what that alignment requires of a host that overcommits CPU.
Larger and GPU tiers require corresponding execution support. The resource fields in the registry do not establish such support by themselves (§8, §16.2).
7.4 Capabilities and Selection
Container capability filtering MUST enforce requested isolation and resource capacity. Among compatible runners, selection follows CIP-2. The executor selects the lowest supported isolation tier meetingmin_isolation_tier and MUST reject a job when it cannot provide its requested execution capability.
serves_registered_images means “this host can fetch a registered image from CBFS, verify it, and cache it”. A runner MUST advertise it whenever the container executor is enabled and its cache directory is writable with the configured quota available, and MUST NOT advertise it otherwise. Capability advertising fails closed: a host that cannot enforce resource caps advertises no container capability at all.
Dispatcher Filter 3.5 MUST match both ImageRef::Base and ImageRef::Digest jobs on serves_registered_images alone. A cache-inventory filter would exclude capable runners that have not fetched the base yet, including every newly started runner. Base images use the same registration and fetch process as other images.
base_images informs operators and warm-start scheduling heuristics. Dispatcher matching ignores it. It keeps its place in the capability record; a runner that advertises it SHOULD populate it from its cache.
The runner-side capability record carries serves_registered_images as the node’s does. That record round-trips through bincode into sled positionally, without skipped fields, and #[serde(default)] does not make bincode self-describing, so a persisted registration store of another record shape MUST be recreated, not read. Integration coverage MUST exercise that replacement as well as a fresh runner.
Advertising a container capability requires qualifying the host: actual sandbox launch, cgroup delegation, and resource capacity (§15.1). Registration, whether automatic or through the CLI, MUST NOT advertise a container capability the host has not qualified, and MUST NOT advertise a network policy or resource tier it does not enforce. The unsafe no-cgroups path (§15.2) cannot enforce caps and so falls under the fail-closed rule; at execution it also rejects jobs above Small.
8. GPU Passthrough
The following request and device descriptions specify GPU passthrough semantics; they are not fields of theRuntimeConfig wire schema (§11.1). A runner MUST satisfy these requirements before advertising GPU execution.
8.1 GPU Request
Tasks requiring GPU access specify aGpuRequest:
8.2 Device Exposure
GPU devices are exposed to the container via the OCI runtime’s device mapping:- NVIDIA GPUs: Exposed via
nvidia-container-runtime(CDI). The container sees/dev/nvidia*devices and CUDA libraries. - AMD GPUs: Exposed via ROCm device mapping. The container sees
/dev/kfdand/dev/dri/render*.
8.3 GPU Capability in Runner Registry
Runners with GPUs advertise them:8.4 Capability Filtering
Runner selection for a GPU job MUST filter for the requested GPU count, memory, vendor/driver compatibility, and available capacity. An empty eligible set MUST fail admission through the CIP-2 capability checks. GPU indices and an execution-time capacity check are required; this CIP does not define a second VRF formula or askip_task() instruction.
9. Network Policy
9.1 Default: Isolated
NetworkPolicy::None (wire tag 0) is the only network-policy variant. Under it the executor disables network access for every container. This is the safest posture and sufficient for pure computation tasks that read from CIP-9 volumes and write results. Allowlisted egress (§9.2) requires a further NetworkPolicy variant that carries its rules.
9.2 Egress Allowlist
The rules below specify egress enforcement. A runner MUST NOT advertise a network policy it does not enforce. An allowlist carries at most 32 rules (proposed). Tasks that need external network access (API calls, web scraping, model API endpoints) declare an egress allowlist:- No wildcards: Each allowed host must be explicitly listed.
*.example.comis not valid. - DNS resolution and IP pinning: DNS resolution is performed by a host-side DNS proxy (not inside the container) that enforces the allowlist. The proxy resolves each allowlisted hostname at container startup, pins the resolved IP(s), and configures iptables rules to permit traffic only to those pinned IPs on the specified ports. This prevents DNS rebinding attacks (where an attacker changes a DNS record mid-session to redirect traffic to an internal IP). The container’s
/etc/resolv.confpoints to the host proxy, which rejects queries for non-allowlisted domains.- TLS SNI verification: For TLS connections (port 443), the Runner’s network filter verifies that the TLS ClientHello SNI matches the allowlisted hostname. This prevents an attacker from using an allowlisted IP to tunnel traffic to a different hostname.
- DNS TTL refresh: Pinned IPs are refreshed at DNS TTL expiry (minimum 60s, maximum 300s) to handle legitimate IP rotations (CDNs, load balancers). New IPs are verified against the allowlist hostname before being permitted.
- No task ingress: Task containers cannot accept external inbound connections. Persistent workloads expose the registry-controlled endpoint in §17; that exception does not grant ingress to task containers.
- No inter-container networking: Containers from different tasks cannot communicate directly, even if they run on the same Runner node. Communication between tasks happens through CIP-9 shared volumes.
9.3 Model API Access
For LLM tool-calling workloads, the model API endpoint must be in the egress allowlist. The Runner operator’s model harness handles authentication with the model provider. For example, a harness callingapi.anthropic.com requires an explicit TCP port 443 rule plus an authorized credential-delivery mechanism. Under NetworkPolicy::None the call cannot be made.
For Runners that host models locally (on-device inference), no egress is needed because the model runs inside the container.
10. Container Lifecycle
10.1 Execution Flow
10.2 Setup and Teardown
Setup resolves the registered image and fetches, composes, and verifies it on a cache miss (§5.8), checks execution capability, prepares namespaces and limits, obtains authorized storage material through CIP-9, mounts volumes, injects runtime metadata, and starts the command. An image mismatch or failed mount MUST prevent execution. Failure and reassignment follow CIP-2; this CIP adds noskip_task() instruction.
During execution, the runner monitors the process and samples resource accounting (§15.2). Storage synchronization follows CIP-9. On completion it MUST attempt final synchronization and submit the required storage commitment before claiming durable output. Container and scratch cleanup also applies to failure paths.
The final-sync target is a bounded 30-second teardown window. Successful storage integration requires proof that writes survive teardown; an exited process alone does not prove the storage lifecycle completed.
10.3 Failures
10.4 Exit Evidence
Exit zero indicates command success; a nonzero exit indicates failure. The runner MUST distinguish its own timeout decision, a signal termination, and observed OOM evidence. Exit 137 alone does not prove OOM, and exit 143 alone does not prove a timeout. Result encoding and verification follow CIP-2. This CIP defines no container-specific job status enums.11. On-chain Interface
11.1 Container Jobs
A container job usesJobType::Container { runtime }, whose job-kind tag is 0x06:
RuntimeConfig and its nested types inside JobType tag 0x06). image is a base image selected by tag or a composed-rootfs digest. resource_tier is the name of a registered resource class (§7.1, §11.2) and decodes against the §5.11 registry-name grammar; the decoder does not check that the class exists, and admission refuses a job whose class is not registered. secret_env lists CIP-24 secret names in strictly ascending byte order, each a plain CBSS key name ([A-Z][A-Z0-9_]*, 1 to 128 bytes) outside the reserved COWBOY_ namespace (§6.2); the decoder rejects any other name, a duplicate, or an unsorted list. Serde defaults are NetworkPolicy::None, IsolationTier::Standard, and an empty secret_env; a request that names no resource class is priced at small-ephemeral. Volume attachments belong to the surrounding job’s storage configuration. Arbitrary environment overrides, working directory, arbitrary resource limits, and a GPU request object are not fields in this runtime schema; secret_env (§6.2) is the only application-controlled environment entry.
11.2 Container Registry
CONTAINER_REGISTRY = 0x13 is the Council-pausable system actor for image locators and name bindings, resource classes, compute locks, pending container settlements, and workload records. The whitepaper §9.1 owns the cross-CIP address allocation.
controller, which never changes (§5.11). A rebind of a reserved name may come from any system_deployers sender and records that sender as controller.
Image locators use §5.5 and resource-class records use §7.1. These records do not contain an architecture manifest. Workload records are defined in §17.3.
11.3 Storage
Records are JSON values in actor storage. Image and class keys are the literal prefix concatenated with the name bytes:system:container_registry:digest:<digest>), the locator lists (system:container_registry:image_locator:<digest>), the composed reference counts (system:container_registry:composed_ref:<base_digest>), and the per-volume registration counts (system:container_registry:image_count:<volume_id>) defined in §5.5, and the 35-byte image listing index il: ‖ digest defined in §5.6; admission follows §5.7. These record keys are read by exact key; il: is the scan index (§5.6). Clients MUST use the actual actor storage key, not a locally invented RLP encoding or a hash of an alternative logical schema. Workload keys, JSON encoding, and reverse references are specified in §17.3.
11.4 Instructions
Container settlement config changes use
SubmitContainerSettlementConfigProposal followed by ExecuteProposal after the proposal passes. Direct opcode 164 execution is unauthorized; a transaction from 0x09 is not a substitute for the proposal path. Operational deployer authorization covers reserved names, resource-class administration, grants in reserved cby- Runner pools (§17.3), and the emergency workload stop and removal (§17.3.2). Image publication is otherwise permissionless, and workload registration needs only the owning actor’s controller.
The protocol codec, node, runner, and CLI MUST share one encoding of these instructions at an exact pinned protocol revision.
The whitepaper §9.2 owns the cross-CIP instruction allocation.
11.5 Image Access Weights
The rows and additions below preserve the historical table-24 image-access audit. The current access table is 43. The historical rows are:
Both rows are fixed, reserved in full before any store operation, and priced at the maximal shape. A registration that is unnamed or unbased still reserves nine reads, matching this family’s fixed reservations without input-dependent branches.
Admission (§5.7) adds reads to the container path of job submission, reserved at the maximal shape because the list size and base pin are stored state: 12 for a
Digest ref (digest index, locator list and up to four volume commitments; the base’s locator list and up to four of its volume commitments; the cold-fetch rate) and 7 for a Base ref (the historical table-version-24 audit constants JOB_SUBMIT_CONTAINER_ADMISSION_DIGEST_READS and JOB_SUBMIT_CONTAINER_ADMISSION_BASE_READS). These reads are charged to the submitting transaction, not amortized, because they gate its acceptance.
Registry names (§5.11), the image listing index (§5.6), and controller-authorized workloads (§17.3.2) add accesses that the schedule MUST price, at their maximal shape, in the table-version change that introduces them, on top of the version-24 rows above:
RegisterWorkload and every update to Running also write the claim hint; a Stop removes it.
12. Billing and Fees
12.1 Compute Escrow
Container compute is an additional charge alongside CIP-2 job payment. At admission the dispatcher resolves the registered class for the runtime tier and locks the maximum compute cost from the submitter at0x13:
u128 multiplication and addition with integer division in the order shown; division MUST NOT precede multiplication. The duration is the registered class’s max_duration_sec.
The three rates are read once at escrow creation and stored in JobComputeLock with amount and submitter. Settlement uses that snapshot; a subsequent governance-rate change MUST NOT reprice an in-flight job. The parameter paths and fallback rates are in §13.
12.2 Metered Charge
MIN_BILLABLE_DURATION_MS = 100.
The node uses the supplied meter only when billing data parses and metered = true. Missing, malformed, or unmetered billing falls back to the full compute escrow. The flag is not cryptographic proof that the values came from real cgroups.
bytes_egressed is carried as evidence but is not charged by this formula. Cold-fetch fees are a separate reservation and settlement component under §12.6. There is no per-byte egress charge in the compute formula.
12.3 Attestation and Disputes
tee_attestation carries an encoded Composite Attestation Envelope (CAE), serialized in JSON as an optional lowercase hexadecimal string without 0x. Job and runner identities are bound by the enclosing submission and verification context, not additional fields in this struct. CAE requirements and meter binding follow CIP-23 §3.12. An attestation’s presence MUST NOT make it authoritative.
Exactly one runner, metered = true, and successful bound billing-CAE verification make settlement eligible at result height H + 1, with cae_final = true. Result verification does not transfer compute funds; this final settlement rejects billing disputes. Every other case retains the ordinary dispute window. A runner attaches a billing CAE to a TEE-required container job when a Nitro attestor is available.
Here “authoritative” means final for the billing dispute rule. A billing CAE proves service-key custody and signs host-measured cgroup fields, not independently verified meter integrity under host compromise. A verified CAE therefore does not prove the measurements truthful against a malicious host; the charge remains capped by the locked escrow.
The ordinary path records a pending settlement at 0x13 with the escrow, actual charge, dispute status, and due height H + max(dispute_window_blocks, 1). Result verification moves no compute funds. Finalization processes eligible records subject to Council pause state and bounded block processing, so the due height is an eligibility threshold, not a guaranteed payout block.
Before the due height the job’s submitter MAY file DisputeContainerBilling { job_id }. A first valid dispute marks the pending record and applies a score-zero EMA reputation update to the runner; repeated disputes are idempotent. This does not increment a tasks_failed counter or adjudicate the true resource usage. Tests MUST exercise dispute rejection for authoritative settlement, and pending-settlement finalization, through the actual job submission path.
The settlement split in §12.5 applies to compute in every case; the separate cold-fetch component follows §12.6. A dispute can increase the runner’s cash share by raising the charge to full escrow, despite its reputation cost. The mechanism bounds the submitter’s exposure; it does not prove truthful reporting is economically dominant.
12.4 Separate Accounting
CIP-2 job payment, CIP-9 storage rent, and CIP-10 container compute are independent accounting flows. Container compute locks at0x13 do not borrow from job-payment escrow or a volume’s storage balance. Their governance configuration and settlement rules remain scoped to their owning CIPs.
CIP-3 Cycles and Cells still apply to on-chain submission, verification, and storage operations. Container resource usage is measured off-chain; it is not VM instruction or state metering.
12.5 Settlement Split
The containerSettlementConfig is stored at governance actor 0x09 under system:container_settlement_config:
u8 percentages that MUST sum to 100, not basis points. Passed-proposal enactment updates this configuration (§11.4). Eligible runners share the runner portion; the treasury receives the rounding remainder after runner and burn amounts are calculated. A disputed settlement pays this split on the full compute escrow, not the entire compute escrow to a runner. Cold-fetch reimbursement is separate (§12.6).
Finalization pays the charge, refunds unused escrow when applicable, and clears the compute lock and pending settlement. Persistent workloads use the separate billing scope in §17.6.
12.6 Cold-Fetch Fee
A runner drawn for a job whose image it does not hold pays the bandwidth. The cold-fetch fee is a separate governance parameter alongside the compute rates in §13.- The parameter
cip10.container.cold_fetch_fee_per_mibis in wei per MiB ofdelta_bytesand is registered alongside the three existing container paths. Its default is0, so the fee is inert until cold-start cost is measured. - The charge is
fee = ceil(delta_bytes / 1 MiB) * rate, computed from the smallestdelta_bytesdeclared by any serving locator of the digest (§5.7), not from anything the runner reports, so a front-runner’s locator cannot raise the fee (proposed). The rounding is proposed too. - The fee is reserved from the submitter at
submit_taskin the same handler that escrowsmax_compute_cost, on top of it (proposed, charging on top, rather than carving the fee out ofmax_compute_cost, keeps the compute escrow’s meaning intact and makes the submitter’s total explicit, at the cost of raising the balance a submitter must hold). - Both the rate and the computed fee amount and
delta_bytesMUST be snapshotted into theJobComputeLockat submit, not the rate alone. The amount is what settlement pays; recomputing it at settlement from a locator that may since have been tombstoned, or from a governance value that may since have changed, would reprice an in-flight job. Snapshottingdelta_bytesalongside makes the lock self-describing for audit. - The lock MUST be written whenever
max_compute_cost + cold_fetch_fee > 0. A handler that returned early on a zero compute cost would drop the cold-fetch-only lock of a job whose resource class prices to zero. - The fee is paid only when the job’s billing attestation reports a cold fetch, and otherwise refunded to the submitter with the compute remainder. Payment goes whole to the runner and is NOT split through
ContainerSettlementConfig(proposed). It reimburses bandwidth a specific runner spent; it is not protocol revenue. It settles on the same schedule as the compute settlement it rides on (§12.3), including the dispute window. - A
DisputeContainerBillingaffects the compute component only. The cold-fetch component is paid whole to the runner if and only if the attestation reports the cold fetch, and refunded whole to the submitter otherwise, in both cases independent of the dispute and independent of the §12.5 split. A dispute is an assertion about metering, and the cold fetch is not metered; letting a dispute claw back a bandwidth reimbursement would let a submitter dispute purely to recover it. BillingAttestation(§12.3) MUST carryimage_cold_fetch: bool. Likemetered, it is self-reported; unlikemetered, it has no cgroup evidence behind it (§14.2).
13. Parameters
Image caps and cache limits are in §5.9, executor limits in §7.3, and workload health/lease constants in §17.4. No per-byte egress fee is defined, and the dispute bond is deferred (§16.4). Design ceilings for larger resource envelopes are in §16.2; they are not chain constants.
14. Security Considerations
14.1 Container Escape
A container escape lets a process break out of namespaces/cgroups into the host. The runtime applies these mitigations:- Namespace isolation: The Standard bundle isolates PID, mount, network, user, UTS, IPC, and cgroup namespaces. Strong omits the OCI user namespace and uses the gVisor sentry boundary (§15.1).
- Seccomp profile: A restrictive seccomp profile blocks dangerous syscalls (
mount,reboot,kexec_load, etc.). - Capabilities dropped: All Linux capabilities are dropped without exceptions.
- Read-only root: The image filesystem is mounted read-only. Writable tmpfs paths and authorized CIP-9 mounts are described in §6.1.
- No privileged mode:
--privilegedis never allowed. Container UID 0 does not grant host root privileges. - Isolation requirement: Standard uses runc; Strong uses gVisor runsc. The executor MUST meet the job’s minimum isolation tier (§15.1). Kata is not an isolation tier.
14.2 Image Supply Chain
Runners unpack archives supplied by arbitrary accounts. The §5.8 step-5 rules are the whole of the defense and MUST be enforced by the extractor itself. A post-extraction scan cannot enforce them. A scan races with symlink-directed writes. The extractor MUST run unprivileged, into a private temporary directory, and MUST be covered by a hostile fixture set (path escape, symlink escape, hardlink escape, device node, setuid bit, declared-vs-actual size mismatch, duplicate members, deep nesting, zip-bomb expansion ratio) that is refused before anything reaches the image root. Registration binds a digest to a locator; the locator remains untrusted. A tree that does not hash to its registered digest never runs. The publisher’s key, the volume owner, and the object hash help locate the bytes. None grants execution. A registration writes up to six state entries for one transaction fee, even if nobody fetches the image. Unbounded registrations would permit cheap permanent-state spam.MAX_REGISTRATIONS_PER_VOLUME = 64 limits registrations: an attacker must fund and keep renting a fresh volume per sixty-four concurrent registrations, so state growth requires CIP-9 rent.
The cap counts only registrations that are still live, registered and unreaped. It bounds concurrent state without limiting lifetime publishing volume. Image name entries are the exception: they are permanent and outlive reap (§5.11), so for names the cap limits the rate of binding, at most MAX_REGISTRATIONS_PER_VOLUME new names per IMAGE_TOMBSTONE_GRACE_BLOCKS per volume, not the total. A project reclaims slots by deregistering superseded images it no longer runs: phase 1 stops admission immediately, and phase 2 frees the slot once the grace window has passed (§5.5). Retiring superseded images frees slots; sixty-four concurrent images fill a volume. The cap charges no per-registration fee, so an attacker can still buy state linearly by paying rent. A refundable per-image registration deposit, released at reap, should be added once a fee market can price it. It needs separate escrow accounting and a policy for deposits stranded behind unreaped tombstones, which this specification omits.
“Register many large images, submit cheap jobs” is capped by MAX_IMAGE_DELTA_BYTES, by single-fetch concurrency, by the cache quota, by the negative cache (§5.8), and priced by §12.6. With the default rate at 0 the fee is inactive, so until the rate is set the structural caps are the only defense. A network with untrusted submitters and non-trivial runner bandwidth costs MUST set the rate deliberately.
The publisher declares delta_bytes; registration does not compare it with the object CBFS holds. First, over-declaring inflates the cold-fetch fee a submitter pays: exposure is bounded by MAX_IMAGE_DELTA_BYTES * cold_fetch_fee_per_mib per job, which is why the cap and the rate must be chosen together and why the default rate is 0. Second, under-declaring cannot make a runner stream more than it agreed to, because §5.8 step 3 aborts at min(delta_bytes, MAX_IMAGE_DELTA_BYTES). The under-declared image never fetches. Clients MUST surface delta_bytes and the fee it implies before the submitter signs, not after.
An attacker who observes a digest before its publisher registers it can add a locator pointing at garbage; a runner skips it after verification fails and tries the next (§5.8), so one bad locator only delays fetches. To deny the publisher outright the attacker must fill all MAX_LOCATORS_PER_DIGEST slots first, from four accounts with four rented public volumes. Because locators are tried in registration order, a front-runner’s garbage locator is tried first and costs each cold runner up to one IMAGE_PULL_TIMEOUT_SEC before the next; it cannot raise the cold-fetch fee, which is computed from the smallest serving delta_bytes (§12.6). The §5.6 publication order closes the window in the normal case, and the publisher can always rebuild to a new digest, so the attack delays the publisher without taking control of its image.
The names the protocol resolves implicitly are reserved cby- names, which only a system_deployers key may bind (§5.11), and only a reserved-name image can serve as a composition base (§5.5 check 8, §5.7). Pinning the base by digest (§5.5) closes the related attack in which rebinding a base name would change the composed contents of every image built on it.
Image availability depends on continued volume rent and the publisher retaining the object (§5.4). The protocol makes no durability promise, runs no mirror, and admits no job against a dead volume (§5.7). Actors pinning a digest whose publisher stops paying lose the ability to run, with one grace window of warning; actors pinning a digest whose publisher deletes the object lose it with none.
image_cold_fetch is self-reported with no cgroup analogue and no evidence digest behind it, and a dispute does not help. §12.3’s optimistic fallback charges the submitter the full escrow, and §12.6 deliberately puts the cold-fetch component outside the dispute entirely. The claim is bounded only by delta_bytes and by the governance rate. Keeping the default at 0 keeps the exposure at zero until the rate is deliberately set.
Two jobs pinning the same digest share one cached tree. The runner verifies the tree against its content digest before installation and mounts it read-only. Changing either property permits cross-job contamination.
The volume MUST be public. An image is code that the drawn runner unpacks to a plain directory, executes, and caches, so no image is confidential from runners by construction; a private volume could hide it only from non-runners. Image registration requires Visibility::Public because (1) the reader set is open and unknown at registration time. It includes any runner drawn for a job on the digest, replacements after a liveness timeout, and runners that join later. A private volume’s DEK is releasable only through a per-job grant to a drawn runner; (2) cross-job caching and demand-driven prefetch need reads with no job to attach a grant to; (3) N-of-M verification draws several runners that MUST fetch identical bytes; (4) public volumes are the path for gateway-served content and for protocol base images. Integrity is independent of visibility: the rootfs digest (§5.2) is recomputed by every runner before use. What a public volume exposes is the delta, the project’s off-chain source and installed dependencies, never job data, and never credentials (the only secret path into a container is the per-job secret_env of §6.2, which is released at run time and is not part of any image). Private images are a bounded extension: treat the image volume as an implicit read-only CIP-9 attachment of every job that uses it, so the drawn runner receives a grant-scoped read token (CIP-9 §7.7.1) and fetches through the same path; such images would have no prefetch, a grant-dependent cold fetch, and an explicit cache-retention rule. That extension is deferred and does not change the digest, the locator, or the compose-and-verify steps.
Permissionless registration and low rent would let one account force every serving runner to download unused images without paying job fees if registration triggered fetching. §5.8 forbids registration-driven prefetch: a runner fetches only for its own assignment or, within IMAGE_PREFETCH_BUDGET_BYTES_PER_HOUR, for a job it observed admitted on chain. Every download corresponds to a JobSubmit with escrowed payment. Unused registrations cost runners nothing. An image spreads through use and stays cached while used.
14.3 Network Exfiltration
NetworkPolicy::None disables networking (§9.1). Egress, where allowed, is subject to the following requirements together with §9.2:
- Default deny: No network access unless explicitly allowlisted.
- No wildcards: Allowlist entries must be specific hostnames.
- No DNS exfiltration: The host-side DNS proxy MUST reject queries for non-allowlisted domains.
- Bandwidth limits: A configured and enforced per-job bandwidth limit (value open) MUST prevent a container from saturating the Runner’s network.
14.4 Resource Exhaustion
These are required protections; the unmetered paths are qualified in §7 and §15.- Mandatory limits: Tasks without resource limits are rejected at the Dispatcher.
- cgroups enforcement: CPU throttling and memory OOM-kill prevent runaway containers.
- Disk quotas: Scratch disk is bounded by overlayfs/tmpfs limits.
- Open workload registration: Only a Runner in the workload’s host pool can claim it: the platform’s reserved pool by default, or another pool the controller names (§17.1). An outside Runner therefore cannot take over a workload and receive its traffic, and a claimant’s own endpoint is checked as in §17.3.4. Pool membership must be granted directly by the pool’s owner; a delegated entitlement admits no host, so a vetted host cannot pass hosting to one nobody vetted. A claimant that never begins loses the claim on a fixed clock, and the controller can release any claim by a Stop and restart (§17.3.3).
MAX_WORKLOADS_PER_ACTORbounds what one actor adds to each claim index, the registration deposit prices every entry against many throwaway actors, and a Runner scans only the indexes of pools it belongs to, bounded per pass. A claimant’s accountable registration (§17.3.5), its own or its host Runner’s, must also be staked and name the host its claimed endpoint uses, so the Gateway never relays to an unaccountable server (§17.3.3). - Name squatting and front-running: Unreserved image names are first-come and permanent (§5.11), so name squatting is an accepted cost. Squatting is rate-limited, not bounded: binding a name needs a registration in an
Active, rent-paying public volume (§5.5), so one volume binds at mostMAX_REGISTRATIONS_PER_VOLUMEnames perIMAGE_TOMBSTONE_GRACE_BLOCKS(§14.2), and holding a name afterwards costs nothing. Reservedcby-names are unavailable to squatters. First-come also means aRegisterImageseen in the mempool can be front-run for its name. This is accepted for unreserved names: jobs and composed images pin digests (§5.6), so a squatted or front-run name misleads only a tool that resolves the name, and the name never changes hands afterwards. A client that resolves a name MUST show its controller and pin the digest it resolved (§5.6). The names the protocol itself resolves are reservedcby-names, which cannot be front-run. - CIP-9 quotas: Volume write quotas are enforced by CapToken
max_bytes.
14.5 Secret Leakage
These are secret-handling requirements. A container sandbox or the optional billing CAE field alone does not establish a verified TEE or secret-delivery path.- No host env inheritance: The container environment contains only explicitly constructed runtime metadata and approved application values.
- Secret delivery is
secret_envonly: a released value reaches the sandbox solely as a process environment variable named by the job’ssecret_env(§6.2), authorized bysecret_refs. The runner MUST NOT write it into theJobSpec, the OCI bundle it retains, logs, or the result, and MUST wipe its copy when the run ends. The sandbox’s own environment is observable by everything inside the sandbox (/proc/self/environ, child processes), so a signing bundle is a small, single-purpose image, not a general application. - No host filesystem: The container has no access to the Runner’s host filesystem, Docker socket, or metadata services.
- TEE attestation: For sensitive workloads, Runners must attest via TEE (CIP-2
tee_required=true). The volume key (CIP-9) and any task secrets are sealed to the enclave. - Scratch destruction: Container scratch filesystem is destroyed immediately after teardown.
14.6 GPU Side Channels
These requirements apply to GPU execution (§8).- MIG isolation (NVIDIA): For multi-tenant GPU sharing, Runners SHOULD use Multi-Instance GPU (MIG) to provide hardware-level isolation between containers.
- Memory clearing: GPU memory is cleared between container executions to prevent cross-job data leakage.
- Single-tenant default: A GPU device is assigned to at most one container at a time (no sharing).
15. Runtime Implementation
15.1 Isolation
Standard uses rootless runc and is restricted to trusted/internal development-network workloads. Public or adversarial jobs MUST request Strong isolation. This restriction applies even when Standard has enforced cgroups; resource caps do not establish an adversarial isolation boundary. The enforced-cgroup path invokes--systemd-cgroup, sets OCI cgroupsPath = user.slice:cowboy:<id>, and defaults XDG_RUNTIME_DIR to /run/user/<uid>. The user slice needs systemd Delegate=yes for CPU, memory, and PID enforcement.
Strong uses gVisor runsc through the OCI driver with --network=none, --ignore-cgroups, and --rootless for an unprivileged caller. Its OCI bundle omits the user namespace because the sentry supplies the isolation boundary. A tier that runs without host-cgroup enforcement reports metered = false, and its billing falls back to full escrow (§7.2, §12.2).
A runsc --version availability probe does not prove that a sandbox can launch on that host. Capability qualification MUST include successful execution and the requested enforcement properties before operators advertise the tier.
15.2 Cgroup Metering
Systemd can remove a transient cgroup as soon as the process exits, so the runner samplescpu.stat and memory.peak while the process is live and retains the last readings. It derives average millicores as cpu_usec / duration_ms, records the memory high-watermark in MiB, and binds the raw snapshot as:
RUNNER_CONTAINER_UNSAFE_NO_CGROUPS=1 disables resource caps while retaining the sandbox’s other isolation. That path reports reserved tier limits with metered = false; it is an operator-trusted development fallback. Its advertising and execution guards are in §7.4.
15.3 Startup and Logs
A verified cached image avoids fetch latency. A container-ready target of five seconds is a performance objective, not a measured service guarantee; image hashing, mount/key delivery, and manifest retrieval belong in that measurement. The executor captures stdout/stderr. Output capture MUST be bounded and cleaned up with the container; the log buffer is limited to 10 MiB (proposed). Durable application logs belong in an authorized CIP-9 volume. An application exit MUST NOT imply that its logs or storage output were committed successfully.16. Deferred Design
16.1 Assignment Decline
At and afterRUNNER_ASSIGNMENT_RELEASE_ACTIVATION_HEIGHT under
CIP-50, DeclineAssignment
(SYS_DECLINE_ASSIGNMENT = 25) permits a current single-runner task
assignee to return an assignment before the committed start predicate below.
Before E3 it is refused in block scanning and every execution entry; fetch
failure uses §5.8’s timeout. Committee jobs (M > 1) cannot use this verb:
they retain today’s timeout/whole-committee replacement rules. E3 does not
replace a committee seat or disturb another member’s accepted work.
The ordered payload is { job_id: [u8; 32], assignment_height: u64, reason: RunnerAssignmentReleaseReasonV1 }. The reason is ImageFetchFailed
(tag 0x00), NoCapacity (0x01) or MissingCapability (0x02).
Require job.assigned_runners == [sender], M == 1, and a live task
assignment (Assigned, or a private task’s PendingKeyDelivery).
The sender is the runner’s account address, authorized by its current account
signing policy with ordinary chain-id and nonce replay protection.
assignment_height MUST equal the committed JobTimeoutRecord.assigned_at
when that record exists, otherwise the job’s submitted_at. It is not
CIP-11’s connection-bound transport assignment_hash; execution need not
know connection keys. No new assignment hash, generation counter or hash
preimage is part of either E3 instruction.
“Not started” requires the absence of a JobResultCommit, JobResultSubmit,
crash attestation, existing delivered-volume row and E3 CBSS-start marker for
(job_id, sender). These are committed-state checks, not the runner’s claim
about its local process. At and above E3’s gate, the first accepted
SubmitReleaseReceipt for a current live assignment writes that assignment’s
CBSS-start marker; replacement and reaping retire it.
A task with nonempty secret_refs whose current assignment predates the
network’s E3 activation height MUST also be refused: historical CIP-24 release
receipts have no bounded per-job lookup that can prove the assignment unstarted.
A missing/nonlive job, stale height, committee assignment, recorded start or
such a pre-gate assignment with declared secrets
is refused as InvalidData (1213). For a live single-runner assignment,
a sender other than that runner uses Unauthorized (1211). Check job
shape/liveness, then sender, then height and committed-start predicates,
then the decline cap, in that order. Malformed state is a deterministic refusal;
failed infrastructure reads propagate. Native sessions use the separately
bound ReleaseRouteSession,
not task decline.
A decline MUST be refused with InvalidData (1213) once the ordinary
service height reaches the reservation’s assigned_clock + timeout_blocks;
only the staged timeout transition may classify the assignment then
(expiry guard). A sender already present in the job’s
decliner row MUST also be refused with InvalidData (1213)
(duplicate-decliner guard).
While any job-trio actor (Runner Registry, Job Dispatcher or Result Verifier)
is Council-paused, DeclineAssignment MUST be refused deterministically
with the existing ActorPaused error before any mutation. Preserve the
assignment and lifecycle calendar so the runner can retry after the pause.
E3 redraw and terminal disposition
An accepted decline atomically consumes the outgoing assignment, releases its runner job-index entry, records the reduced reputation effect and epoch usage, and emitsjob.assignment.declined (TOPIC_JOB_ASSIGNMENT_DECLINED)
with the job, runner, assignment height and closed reason. D’s class counter
decrements only when its assignment marker exists; an unmarked legacy
assignment releases only its total index entry. A repeated consumed
assignment cannot repeat the penalty, decrement, refund or event.
A private-volume task follows the existing no-retry path: terminal
Failed with refund through fail_timed_out_job_with_refund, retiring the
outgoing attachment/key-delivery obligations under that path. No new runner
or replacement CapTokens/CBSS bundle is issued. The accepted decline’s
reduced penalty replaces the timeout penalty; it does not invoke timeout
probation, jail or a stake penalty. This is also the disposition for an
otherwise eligible private task still in PendingKeyDelivery before any
CBSS release. CIP-2’s private-volume no-retry rule is unchanged.
For other single-runner tasks, redraw in the same transaction using the
admission-owned ordinary lifecycle calendar, not just the legacy timeout
index. Read its reservation, remove the old Kind::Expiry entry and reserve
the replacement’s entry before exposing the replacement. Use the existing
move_expiry(..., servicing=false) semantics: a transaction is not currently
servicing that bucket, so the old entry must be removed even when both
entries use the same bucket. Preserve the admission-owned Reap obligation.
A replacement’s deadline is assigned_service_height + timeout_blocks, in
the existing pause-aware ordinary service clock; its assignment record uses
the actual replacement block height. Set its existing
original_disposition = OperationalFailure, so a later replacement success
cannot trigger a stake-funded rescue penalty on the decliner. Update the
reservation’s expiry bucket
and assigned service clock atomically. A legacy timeout index, where still
maintained, mirrors this transition and is not the authority for it.
Let c be the committed retry count before this redraw attempt. If
c >= MAX_JOB_RETRIES, fail terminally. Otherwise use exactly the existing
timeout seed Keccak256(original_seed || b"retry:" || u32_le(c)) and record
retry_count = c + 1 for this attempt, bounded by MAX_JOB_RETRIES (baseline
3). Selection uses the existing timeout candidate/draw rules plus every prior
decliner in an additive per-job exclusion row. Add the current decliner only
when a retry is permitted; a terminal fourth decline needs no new entry.
Retain that row across
subsequent declines and timeouts, union it with the ordinary timeout and
protocol exclusion sets, and bound it by MAX_JOB_RETRIES distinct runner
addresses, encoded in ascending raw address-byte order without duplicates.
Thus same-block redraws cannot return an assignment to a prior
decliner even though their heights match. No field is added to an old strict
job record merely to hold that set.
On retry exhaustion, a deadline/service allowance beyond the admission
horizon, inability to reserve the replacement calendar entry, or no eligible
and exposable runner, transition to terminal Failed with refund using the
existing timeout-failure path, release Expiry exactly once and retain the
normal Reap/failure-callback obligation. A private task also takes that
terminal path directly. No timeout penalty is applied on top of the decline
penalty. A shared-selection-budget refusal is distinct from an empty pool:
it refuses and rolls back the whole decline transaction for retry in a later
block under A; the original assignment/Expiry stays live. It does not leave
a partially declined job in an invented pending state. OS/store/PVM faults
propagate without committing a fabricated terminal result.
The separate exclusion row and every new check/decode/hash/store operation
are additive, gated and charged before work. Existing lifecycle capacity and
selection checks are prepaid before assignment changes. Counter, calendar,
attachment, reputation, escrow and event effects commit or roll back together.
The three E3 rows live under the Job Dispatcher system actor 0x02 with these
exact keys (+ denotes raw-byte concatenation):
E3 governance and reputation
cip10.assignment.decline_cap_per_storage_epoch
(RUNNER_DECLINE_CAP_PER_STORAGE_EPOCH_GOV_PARAM) has compiled default
DEFAULT_RUNNER_DECLINE_CAP_PER_STORAGE_EPOCH = 32 per runner per committed
storage epoch. Production epochs are 86,400 blocks; derive them through
StorageEpochBlocks, including short rehearsal epochs. Account lazily at
admission, with no epoch sweep. Beyond the cap, refuse with InvalidData
(1213) and no A site, checked after the committed-start predicates.
The refusal leaves assignment, epoch counter and reputation unchanged;
the runner’s assignment then times out as today.
cip10.assignment.decline_liveness_timeout_divisor
(RUNNER_DECLINE_LIVENESS_TIMEOUT_DIVISOR_GOV_PARAM) has compiled default
DEFAULT_RUNNER_DECLINE_LIVENESS_TIMEOUT_DIVISOR = 5. Its numerator is one.
The exact per-component transition and four normative vectors are in
CIP-2 §6.1’s decline rule.
It increments assignments, applies ceil(timeout_EMA_decrement / divisor)
from the same prior and decay basis, and leaves timeouts, consecutive
timeouts, probation and jail unchanged. There is no money penalty before
work starts. Do not call the full timeout-failure reputation helper and
then try to undo its unrelated effects.
Both parameters use validated positive decimal scalars; missing values read
the compiled defaults. Gate their allowlist entries at proposal submission
and enactment. Operators MUST leave defaults until the network’s Tier-0 drill
passes; this is an operator rollout rule, not an extra chain predicate.
E3 wire and assignment binding
The System module byte is0x00; opcode 25 is 0x19 and opcode 26 is 0x1a.
The complete fixed-width encodings are:
"ImageFetchFailed", "NoCapacity" and "MissingCapability" for binary tags
0, 1 and 2. Reject tags 3–255, unknown enum strings, integer JSON reasons,
missing required fields and unknown object members; there is no Other.
Use the existing externally tagged JSON forms:
{"System":{"DeclineAssignment":{"job_id":B32,"assignment_height":H,"reason":"NoCapacity"}}}
and
{"System":{"ReleaseRouteSession":{"session_id":B32,"job_id":B32,"assignment_epoch":E}}}.
Here each B32 denotes an array of exactly 32 JSON integer byte values, and
H/E denote u64 integers; they are notation, not literal JSON. Neither
instruction carries a separate sender address, signature, transport hash or
metering-key proof. Release authorization and pinned-epoch equality follow
CIP-39 E3.
Conformance MUST test the three decline reason encodings and the reason-free
session release, stale heights/epochs, wrong signer, each committed-start
predicate, service height at or past the assignment deadline, an already
recorded decliner, a committee member declining after a peer has
committed/revealed (refused), a pre-gate assignment with nonempty secret_refs
(refused),
CBSS-start marker creation at the gate and retirement on replacement/reaping,
private-task decline/refund, all retry/horizon/no-runner terminal
branches, repeated decline and timeout exclusion, shared-budget rollback,
calendar moves in the same/different bucket, D legacy/class releases, epoch
cap/rollover, the over-cap 1213 refusal with no A site and its position after
the committed-start checks, and both sides of E3. A refused instruction preserves all
preexisting assignment, lifecycle and peer state.
The merged E3 decline entry checks and
atomic reputation/counter/redraw transition enforce
these rules. The wire encoder preserves the field order
above; the accepted-receipt marker records the current
assignment’s committed start fact.
Existing behavior anchors at core 734db73a7c712d0efa2d0fa16f17ca891d5a5879:
assignment/timeout records,
JobTimeoutRecord;
timeout replacement,
private-issued-attachment guard, retry seed/count and
fail_timed_out_job_with_refund; and
lifecycle reservation moves,
move_expiry / release_expiry. They supply E3’s existing mechanics rather
than a transport-derived assignment hash.
16.2 Larger Resource Envelopes
The design ceilings per task are 16,000 millicores, 65,536 MiB memory, 204,800 MiB scratch, 7,200 seconds, and eight GPUs. A class within them requires executor, admission, and pricing coverage before use; custom limit overrides are not in the wire schema. The larger-class presets below are design targets; a job can select one only after it is registered as a resource class:16.3 Other Image Paths
OCI 1.1 image and Docker distribution manifests, architecture selection, and public or private OCI registries are deferred, with a 10 GiB ceiling for a non-registered image path. Private-registry pull credentials MUST be encrypted to the runner’s TEE attestation key, scoped to the job, and never persisted. None of these is a second provisioning path for the registered images in §5.16.4 Dispute Bond
A refundable dispute bond is deferred. It requires a valid-dispute criterion and a refund rule before it is introduced; §12.3 uses full-escrow fallback without adjudication or a bond.16.5 Exclusions
Container-to-container networking, multi-container pods, non-OCI execution models, decentralized image building, trusted builder attestation, and spot/preemptible pricing are outside the defined task execution path. A harness can manage subprocesses inside one image. Persistent workloads are in scope under §17; their separate exclusions are listed in §17.7.17. Persistent Workloads
17.1 Scope
Task containers are dispatched by a job, bounded bymax_duration_sec, and destroyed at exit. Serving inference requires a process that loads weights once, stays warm, holds streaming connections, and outlives any individual request.
This section defines the bounded persistent-workload class: its registry record, lifecycle, restart policy, volume mounts, health reporting, and inbound serving endpoint. The controller of an actor registers and manages that actor’s workloads. Live migration of a running process, third-party isolation guarantees, and billing remain deferred.
A Runner claims a workload; its owner never names an endpoint. Each record names a host pool, a CIP-2 Runner pool (CIP-2 §7.3) whose members may claim it: by default the platform’s reserved pool cby-workload-hosts, whose membership only system_deployers grant, or another pool the controller names, such as its own or a hosting provider’s. A workload is registered unclaimed, and a member Runner takes it with ClaimWorkload (§17.3.2), which records that Runner’s reporter and serving endpoint. A claim lapses on a clock the claimant cannot refresh by reporting, or when its pool entitlement is revoked or expires, and the workload is then claimable again by another member, which moves it off a host that has died (§17.3.3). An unclaimed workload waits, costing nothing beyond its refundable deposit (§17.3.2), until a Runner claims it or its controller stops and deregisters it; registration obliges no host. A Runner also applies its own operator policy before claiming. Until host billing (§17.6) exists, workloads run on platform Runners or on Runners whose operators the owner arranged with. A Runner begins or continues an attempt only for a workload whose current, unlapsed claim it holds (§17.3.3); a record that still names it as reporter after its claim lapsed confers nothing.
17.2 Workload model
A persistent workload is a container whose lifetime is governed by its registry record:- It has no
max_duration_secbound. Its resource class still limits CPU, memory, scratch storage, and GPU resources. - It starts and stops according to
desired_state, not per-request dispatch. - It exposes one serving endpoint for CIP-15 gateway routes and authorized first-party callers.
- It MUST load required weights and mounts before reporting
Running. - Its egress behavior follows the network policy in §9.
cpu_millicores is a CPU ceiling, not a reservation: the
sandbox sets a CPU quota at that rate and nothing else, so a workload’s share
under contention depends on what else its host runs.
A workload host MAY carry more workload ceilings than its CPUs cover. It
declares an overcommit ratio R, at most MAX_CPU_OVERCOMMIT = 8, and each
workload on it then has a floor of ceil(cpu_millicores / R) millicores. The
host MUST refuse a slot pool whose floors, plus its reserve for its own serving
path, exceed its CPUs, and MUST set each slot’s cgroup cpu.weight to that
slot’s floor (proposed).
Every workload, including a platform one, has a registry record and reaches its host through a claim (§17.3.3).
17.2.1 User and permissions
Postgres refuses to start as root.initdb exits with cannot be run as root, and other services make the same check. A persistent workload therefore runs as UID/GID 1000 inside its container. §6.4’s UID 0 applies only to task containers.
runc refuses a user namespace that has no mapping for container UID 0, so the persistent OCI spec maps two IDs, each with size 1:
The operator’s slot template carries all four host IDs. Each MUST be nonzero and MUST differ from the Runner’s own UID and GID, and each root ID MUST differ from its workload ID. The root IDs SHOULD come from the Runner user’s
/etc/subuid and /etc/subgid ranges and own nothing on the host.
On the host, container_uid/container_gid own everything the workload writes: the persistent state directory (mode 0700) and the writable CBFS mounts, which the workload sees as owned by UID 1000. /tmp is a fresh mode-1777 tmpfs. Private runtime files (§17.4.2) stay Runner-owned at mode 0400 and reach the workload through a one-file ID-mapped mount; the Runner never changes their owner or mode. Capabilities and no_new_privileges follow §6.4.
Persistent hosts run root runc. Rootless runc cannot provide this mapping. It changes the owner of its exec FIFO to the container-root host ID, which an unprivileged caller can do only for its own UID. Under rootless runc, container root must therefore be the Runner’s UID, and UID 1000 would land on a subordinate ID that cannot write the Runner-owned volumes. We measured each case under runc 1.5.1:
- mapping only container UID 1000 fails with
no mapping found for uid 0; - rootless runc with a subordinate ID as container root fails with
fchown fd 7: operation not permitted; and - root runc with both mappings runs the process as UID 1000, and its writes land on the host as
container_uid.
getrusage, preadv, pwritev, setitimer, setsid, shmat, shmctl, shmdt, shmget, signalfd4 and sync_file_range. Nine of them are the calls Postgres 18 made under strace -f through initdb, start, inserts, a checkpoint and a fast stop, with no /dev/shm as in the runner, less the calls the job profile already allows. The names are the same on arm64 and x86_64. Without signalfd4, initdb fails at signalfd() failed. Without sync_file_range, the first checkpoint PANICs with could not flush dirty data. The other two came from a running workload: Postgres CREATE DATABASE failed without preadv, and Node’s process.cpuUsage threw EPERM without getrusage. A call joins this list only when a real workload or an strace capture shows a service making it, never from reading a program’s source.
17.3 Registry record
The Container Registry actor at0x13 stores persistent workloads under:
key parameter is the hex encoding of the whole key, or through the proof route with key_encoding=hex. The stored JSON record has this schema:
workload_id, name, and owning_actor are immutable. name is a registry name (§5.11), unique within its owning actor. The workload ID is derived, never chosen:
keccak256 is Ethereum Keccak-256, the tag is its 18 ASCII bytes, owning_actor is its 20 address bytes, and name is its bytes, last. The tag and actor are fixed-length, so the concatenation is unambiguous. The codec MUST pin the derivation with a golden vector. Registration MUST reject a record whose workload_id differs from this derivation, so one actor’s names cannot be claimed under another actor and an ID cannot be taken before its owner registers it. generation is assigned from the next chain-wide high-water value (1 on a fresh chain) and advances to a fresh chain-wide value on every successful update except a pure graceful Stop. attempt begins at zero for each generation and is advanced by an accepted BeginWorkloadAttempt; attempt_phase is None, Prepared, Running, or Ended. prepared_until_block bounds pre-start reads. drain_until_block bounds final host-held storage effects for the exact Running attempt after Stop or Degraded. An expired nonzero deadline may remain stored until a later transition clears it. attempt_recipients binds each distinct declared volume to that attempt’s release and commit keys. observed_at is the consensus-written freshness anchor: registration, Begin, any generation-advancing update, and an accepted status report set it to the executing block height, except a repeated Stopped report for an Ended attempt (§17.3.3).
For bounded Runner discovery the registry also writes a 31-byte binary hint key: ASCII wr:, the 20-byte reporter address, then the chain-wide generation as an eight-byte big-endian integer. Its value is the 32-byte workload ID. The hint is maintained on registration, update, claim, and deregistration, including Stopped records, and is absent while a record is unclaimed. A claim hint indexes every workload whose desired state is Running under its host pool, so a Runner scans only the pools it belongs to: a 31-byte key, ASCII wp:, the first 20 bytes of Keccak-256 over the raw host_pool bytes, and the generation as an eight-byte big-endian integer. Its value is the workload ID. It is written on registration and on any update to Running, rewritten under the new generation by a claim, and removed by a Stop or deregistration. A claim lapses without a transaction, so a claimed workload stays indexed and is found again once its claim lapses. A Runner scans its keys with a cursor, bounded per pass; like every listing in this CIP, the hints are index keys of at most 64 bytes (§5.6). All hint keys are only scan indexes: a Runner MUST prove the referenced workload record at a finalized checkpoint before claiming it or treating it as authority to begin or continue an attempt.
reporter is the zero address, serving_endpoint is empty, and claimed_at is zero while a workload is unclaimed; claimed_at is the height of the current claim. host_pool defaults to cby-workload-hosts, is set at registration, and is changed only by a generation-advancing update; changing it clears any claim. A host pool is identified by its owner, so no account can take another’s pool id: a reserved cby- pool id is owned by the platform, and its membership is granted and revoked only by system_deployers senders; any other pool id is the 20-byte address of its owner followed by a registry name, and only that owner grants or revokes its membership. Membership is the CIP-2 entitlement Scope::RunnerPool(host_pool) with Action::RunnerJoinPool(host_pool), granted only by the pool’s owner (CIP-2 §7.3). It admits a Runner only when it passes CIP-2’s entitlement check at the executing block (not before valid_from, not after valid_until, uses not exhausted, not revoked), is direct (parent_id = None), and is revocable; a delegated entitlement, or membership through a role, MUST NOT admit a host. A pool is chosen, not owned, by the workload’s controller: it may name its own pool or another’s, such as a hosting provider’s, and naming a pool trusts that pool’s owner to choose its members. An ownership transfer of the actor leaves host_pool unchanged until the new controller updates it. The registry writes no wr: hint for an unclaimed record.
The mutable update envelope is:
name and resource_class against the §5.11 grammar, and bound volume_mounts to 32 entries, each mount path to 256 bytes, and serving_endpoint to 256 bytes.
On registration and every update that changes either field, resource_class MUST be non-empty UTF-8 naming an existing Container Registry resource class, and a digest-form image MUST resolve through the registry’s digest index. Protocol base-image enum values are valid by construction. A registered digest or resource class MUST NOT be removed while any workload record references it. The Container Registry stores u64 JSON-decimal reverse reference counts at system:container_registry:workload_ref:image:<digest> and system:container_registry:workload_ref:class:<name>; the image suffix is the 32-byte digest in lowercase hex and the class suffix is the validated UTF-8 name. Registration increments the new references, deregistration decrements the old references, and a process-changing update atomically decrements each changed old reference before incrementing its replacement. A zero count deletes the key. The transaction rejects count overflow, underflow, or removal of an image or class while its count is nonzero.
The stored JSON encoding is consensus state and MUST be covered by a golden-vector test. Struct fields are emitted in the order shown above without insignificant whitespace. Integers, including deposit: u128, are JSON decimal numbers; fixed and variable byte sequences are JSON arrays of decimal integers in 0..=255; addresses use the canonical Cowboy address string; enum values use the exact variant names in §17.3.1; ImageRef uses Serde’s externally tagged form ({"Base":"RunnerBase"} or {"Digest":[...]}); options use either null or the encoded value; and lists are JSON arrays. Readers MUST reject records whose decoded workload_id differs from the storage-key suffix.
17.3.1 Enum tags
The commonware wire tags are:
Unknown tags MUST be rejected.
17.3.2 Instructions
Persistent workloads use these system opcodes:
The protocol opcode-uniqueness test MUST cover all ten values. Opcode 229’s payload is
workload_id: [u8; 32], expected_generation: u64, then serving_endpoint bounded to 256 bytes; the claiming reporter is the transaction signer. host_pool is bounded to 83 bytes. Decode classifies it as reserved when it begins with cby- and is then a registry name, otherwise as a non-zero 20-byte address followed by a registry name; anything else, and any id under cby-example-, rejects.
An actor’s controller is the owner in its protocol ActorOwner record (CIP-37 §7.1.1), read at execution. Missing or malformed ownership metadata means the actor has no controller. The chain sets the record when it creates the actor, to the verified deployer for a directly signed deployment, and only a TransferActorOwnership transaction signed by the current owner changes it; actor code cannot set or transfer it, and the application __OWNER__ key has no authority. Workload authority follows the controller. Opcodes 196–198 compare the controller with the transaction signer, so an actor whose controller is another actor’s address cannot manage workloads; a controller is an externally owned account. Authorization is evaluated at execution, so an ownership transfer moves control of every unreserved workload the actor owns.
A reserved-name workload is managed only by system_deployers senders; the actor’s controller cannot change or remove it. A system_deployers sender MAY also submit a pure Stop for any workload and MAY deregister any workload that is stopped and not live (§17.4.3), the platform’s emergency brake. Deregistration releases the workload’s image and resource-class references, so a stopped hostile record cannot hold an image or class against retirement. A system_deployers sender MUST NOT otherwise change an unreserved workload.
An actor MAY own at most MAX_WORKLOADS_PER_ACTOR = 16 unreserved workload records; reserved-name workloads do not count. The registry keeps a u64 JSON-decimal count at system:container_registry:workload_count:<owning_actor>, the suffix being the 20-byte actor address in lowercase hex, incremented by registration and decremented by deregistration of an unreserved workload. The limit bounds both the state an actor can create and the hint entries (§17.3) a Runner’s reporter scan must skip.
Registering an unreserved workload moves the registration deposit from the sender to the Container Registry and records it in deposit; registration rejects a sender who cannot pay it. Below WORKLOAD_REGISTRATION_DEPOSIT_PARAM_ACTIVATION_HEIGHT (CIP-50) the deposit is the compiled WORKLOAD_REGISTRATION_DEPOSIT (10 CBY) and registration reads no governance state. From that per-network height it is the governance parameter cip10.workload.registration_deposit_wei at 0x09, a positive decimal wei amount set through the ordinary CIP-12 parameter proposal, or 500_000_000 wei (0.5 CBY) when unset; that read is one committed access. The path is not a known governance path below the height, and a zero or non-decimal value rejects at submit and at enactment. A change to the parameter applies only to later registrations: the refund and forfeit below always move the workload’s recorded deposit. GET /chain-parameters publishes workload_registration_deposit_wei, the decimal wei a registration at the next height escrows, and omits it when the committed value is unreadable; clients quote that figure. They do not use a constant. Deregistration by the controller refunds deposit to the controller, even when the controller is also a system_deployers sender; deregistration by any other system_deployers sender forfeits it to the treasury (SystemActorAddresses::TREASURY, the account that receives the settlement treasury share in §12). Reserved-name workloads carry no deposit. The deposit prices the claim index (§17.3): a spammer pays for every record it adds to the queue platform Runners scan, and recovers nothing if the platform removes it.
Opcode 196 uses the WorkloadRecord layout below, with name immediately
after workload_id and drain_until_block immediately after
prepared_until_block. Networks adopting
this layout start from a new genesis. Operators MUST verify the new genesis
identity before accepting workload transactions; historical workload blocks
MUST NOT be replayed under this codec or transition.
All fields below use the protocol’s commonware codec in the stated order;
[u8; 32], u64, u128, Address, bounded Vec, and nested RAS/CIP-9 types retain
their existing codec encodings. The opcode precedes the listed payload.
WorkloadRecord uses the field order in §17.3, including the new drain field.
BeginWorkloadAttempt.recipients contains 0–32
WorkloadAttemptRecipient values, each encoded as volume_id: [u8; 32],
recipient_id: [u8; 32], release_pubkey: SigningPublicKey, then
commit_pubkey: SigningPublicKey (CIP-40 §7.7 wire form, Ed25519 only). There is at most one recipient per declared volume.
The opcode 227 payload is SignedWorkloadMountPolicyV1: a
WorkloadMountPolicyV1 then its signature slot. The policy encodes
owner: Address, volume_id: [u8; 32], workload_id: [u8; 32],
image: ImageRef, host_pool (decoded as in WorkloadRecord),
mode: WorkloadMountMode, chain_id: u64, chain_instance_id: [u8; 32],
valid_until_epoch: u64, and revision: u64, in that order; a zero owner or
an invalid chain identity rejects at decode. The signature is a secp256k1
CIP-40 §7.6 signature slot over object_signing_preimage with domain
cowboy.workload-mount-policy.v1, the running ChainIdentity and the policy
bytes; the policy hash is keccak256 of that preimage, independent of the
slot. The opcode 228 payload is workload_id: [u8; 32],
volume_id: [u8; 32], then up_to_revision: u64.
The registry stores the signed policy, binary, under
system:container_registry:workload_mount_policy:<workload_id>:<volume_id>,
and one revision floor per owner, an 8-byte big-endian u64 (absent means
0), under
system:container_registry:workload_mount_policy_floor:<owner>:<workload_id>:<volume_id>,
each identifier as lowercase hex (the owner as its 20 address bytes). Each
owner’s floor is their own replay protection: a former owner can never raise a
new owner’s floor, and a new owner starts at 0. Publication MUST reject a
policy whose chain_id and chain_instance_id are not the running chain
identity (CIP-40 §16), an expired one, one whose signature does not recover to the
volume’s current owner, and one whose revision is not above that owner’s
floor or is u64::MAX; an accepted policy replaces the row and sets the
signer’s floor to its revision. Publishing a policy with the stored row’s
hash, under any valid signature, is a no-op. Revocation MUST reject an
up_to_revision of u64::MAX; otherwise it always deletes the row and sets
the sender’s own floor to max(floor + 1, up_to_revision), saturating, so a
revocation can never fail for want of floor space and no publishable revision
is irrevocable. The stored row’s signer already has a floor at its revision,
so a current owner deleting a former owner’s row needs no write to the former
owner’s floor. Owner tooling signs floor + 1, so a revocation also voids any
policy the sender signed but never published, and up_to_revision voids one
signed above it. A signature withheld from the chain therefore can never
restore consent the owner replaced or withdrew, and a former owner’s withheld
signatures stay void because only the current owner’s signature publishes. A
stored row is always the owner’s live consent, and consumers read only the row.
The mounted volume_id is the immutable ID assigned at creation. A RAS
ownership transfer changes the current owner without changing this ID, so
Runner and owner tools MUST read the finalized commitment at that ID and MUST
NOT rederive the ID from the current owner and volume name. A policy MUST be
checked against the commitment’s current owner.
A transfer therefore suspends the former owner’s stored policy; it does not
delete it. While someone else owns the volume the row authorizes nothing. If
the volume returns to the signer while the policy is unexpired and unrevoked,
the same row authorizes again with no new signature. An owner who does not
want that revokes before transferring, or signs a short valid_until_epoch.
17.3.3 Registration and updates
RegisterWorkload is create-only. It MUST reject an existing workload_id, an owning_actor that does not exist, a workload_id that does not match its derivation (§17.3), a sender not authorized under §17.3.2, and an actor already at MAX_WORKLOADS_PER_ACTOR. Registration MUST ignore submitted readiness values and store:
generation = next chain-wide generation(1 if no generation has been assigned)observed_status = Provisioningobserved_at = current_blockdeposit= the registration deposit in force at this height (§17.3.2) for an unreserved name,0for a reserved one; a submitted non-zerodepositrejects
cby-example- rejects. A workload MUST be registered unclaimed: a non-zero reporter, a non-empty serving_endpoint, or a non-zero claimed_at rejects. host_pool defaults to cby-workload-hosts. WorkloadChanges carries no reporter or serving_endpoint; only a claim sets them. Every generation-advancing update clears the claim (reporter zero, serving_endpoint empty, claimed_at zero), so a controller can always release a workload from its claimant by a Stop and an update back to Running.
ClaimWorkload MUST reject unless all hold:
expected_generationequals the stored generation, anddesired_state = Running;- the signer holds the record’s host-pool entitlement (§17.3), granted directly by the pool’s owner, unexpired and unrevoked; and its accountable registration (§17.3.5) is a CIP-2
RunnerRegistrationstaked at leastMIN_STAKE_CBY_WEI(10,000 CBY) and carrying aroute_serving_endpoint(CIP-15 §8.14), the same accountability every other Gateway-dialed Runner endpoint carries; - the workload is unclaimed, or its claim has lapsed (below); and
serving_endpointpasses §17.3.4, and its host equals the host of theroute_serving_endpointin the signer’s accountable registration, so a claimant can only point the Gateway at the server registered and staked for it. Hosts are compared after parsing both URLs and lowercasing ASCII; scheme, port, and path may differ. A platform host may therefore claim with a private-network endpoint only when it registered that private host.
attempt = 0andcurrent_block >= claimed_at + MAX_WORKLOAD_PREPARED_LEASE_BLOCKS, whatever the claimant has reported since;attempt_phase = Preparedandcurrent_block > prepared_until_block;attempt_phase = Runningandcurrent_block >= observed_at + WORKLOAD_CLAIM_LAPSE_BLOCKS, outside a live drain; orattempt_phase = Ended,observed_status = Stopped,restart_policy = Always, andcurrent_block >= observed_at + WORKLOAD_CLAIM_LAPSE_BLOCKS, whereobserved_atis fixed when the attempt ended: once an attempt isEnded, furtherStoppedreports for it are accepted but MUST NOT changeobserved_at; or- the claimant’s host-pool entitlement has been revoked or has expired; or
- the claimant no longer meets check 2’s registration condition, or the
route_serving_endpointhost in its accountable registration no longer equals the record’s endpoint host. For a bound slot this includes its host being slashed belowMIN_STAKE_CBY_WEIand the slot being unbound (§17.3.5). From that height the registry also rejects the claimant’s Begin, and the Gateway stops routing to it (§17.4.1).
BeginWorkloadAttempt and ReportWorkloadStatus other than Stopped from that Runner for those workloads, and storage effects and DEK releases for its attempts fail the membership check of §17.5, so a retired or compromised host cannot start or keep serving one while another Runner claims it. Losing membership deliberately fences a live drain: the Gateway stops opening connections to the old host at once (§17.4.1), its reports are refused, and it may lose final writes it could not commit before the attempt’s drain deadline. That is the intended trade-off for a revocation, an emergency removal. Expiry is routine, so a Runner MUST NOT Begin an attempt for a workload when its entitlement’s valid_until falls within WORKLOAD_CLAIM_LAPSE_BLOCKS of the executing block, and a pool owner renews a host’s membership before it expires.
An accepted Stopped report alone never lapses a claim: a host reports Stopped before every same-generation restart. A workload that ended under Never or OnFailure may have finished deliberately (an exit code of zero under OnFailure is terminal, §17.4.2), so it stays with its claimant until its controller restarts it; only an Always workload whose host has not restarted it within WORKLOAD_CLAIM_LAPSE_BLOCKS moves. The chain sees no exit codes, so an OnFailure workload that crashed and was reported Stopped by a host that then failed also stays with that claimant until its controller restarts it. WORKLOAD_CLAIM_LAPSE_BLOCKS = 720 equals the first-party host’s last-report limit (§17.4.2), so a platform host partitioned from the chain has stopped its process before another Runner can claim the workload. A host in a pool the controller named is chosen by that pool’s owner, whom the controller trusts to admit hosts that observe the same limit.
A lapse is evaluated against the record at execution, not recorded: from the height a claim lapses, the registry MUST also reject BeginWorkloadAttempt from that claimant for the workload, so a late Begin cannot revive a lapsed claim.
A claim sets reporter to the signer, serving_endpoint as given, and claimed_at = current_block, and advances the record like a generation-advancing update: a fresh chain-wide generation, attempt = 0, attempt_phase = None, observed_status = Provisioning, and observed_at = current_block. A claim is the one generation-advancing transition that requires desired_state = Running. It does not require Stopped; the lapse rules above stand in for the not-live wait. Like every generation-advancing update, a claim deletes the previous reporter’s wr: hint and the workload’s service-release slots, and rewrites the claim hints under the new generation; the prior attempt is fenced. A claim leaves the volume owners’ mount policies in place: they name the pool. They do not name a host. Two claims of one generation cannot both succeed: the first advances the generation and the second fails expected_generation.
UpdateWorkload MUST compare expected_generation with the stored generation and reject a mismatch. A pure Stop update sets desired_state = Stopped, leaves generation, attempt, recipients, and process configuration unchanged, and may set the fixed drain_until_block. On the first transition from Running to Stopped, it sets drain_until_block = current_block + MAX_WORKLOAD_DRAIN_LEASE_BLOCKS (300) for a Prepared attempt, or for a Running attempt whose existing drain is still live or whose last accepted Running report is at most 60 blocks old. It MUST NOT create a drain from an expired Running report. A live Degraded drain may be replaced by this one deadline; an expired nonzero deadline MUST remain expired. A repeated Stop or later status report MUST NOT extend the deadline. A deadline recorded for a Prepared attempt does not authorize storage effects after Stop; a late Running report MUST NOT promote that Prepared attempt. Route eligibility closes immediately. Every other successful update assigns a fresh chain-wide generation, resets attempt = 0, attempt_phase = None, observed_status = Provisioning, and observed_at = current_block, and fences the prior attempt.
A generation-advancing update MUST reject if the chain-wide generation high-water mark is u64::MAX; a pure Stop does not advance it.
Every generation-advancing update other than a claim requires desired_state = Stopped. If an attempt has begun, the workload must also be not live under §17.4.3. This applies to updates that change only restart_policy, host_pool, or desired_state. An attempt-zero workload has no writer and needs no not-live wait. The normal update sequence for a begun attempt is pure Stop, final publication and an accepted Stopped report, then the generation-advancing update. A generation-changing update MUST NOT fence a live writer merely because its changed fields describe policy instead of changing the process.
Reference, endpoint, and mount validation runs only when the corresponding field is registered or changed. In particular, an expired or revoked mount grant MUST NOT prevent an authorized update that stops the workload, changes its restart or host pool, or removes all mounts after the workload is stopped.
17.3.4 Endpoint validation
serving_endpoint is a control-plane trust boundary because the Gateway dials it. Every claim MUST enforce:
- UTF-8 encoding;
- an absolute
httporhttpsURL; - an explicit host and port;
- no userinfo, query, or fragment; and
- a maximum encoded length of 256 bytes.
cby- pool MAY claim with a private-network endpoint. Any other claimant’s endpoint MUST name a public address. Consensus cannot resolve DNS, so the claim check is on the host string: an IP literal that is loopback, link-local, private (RFC 1918, RFC 4193), carrier-grade NAT, unspecified, or a cloud metadata address rejects, and so does a hostname that is localhost or ends in .localhost, .local, .internal, or .home.arpa. Every other hostname is accepted at claim. The Gateway MUST resolve it and refuse to dial a non-public address before every dial, because DNS can change after the claim; to apply this only to claimants outside the reserved pools, the Gateway reads the record’s host_pool at the same proof point as the record. Platform deployments MAY use mutually authenticated transport. The Gateway MUST resolve the endpoint from the registry record and MUST NOT accept an endpoint from route configuration or request data.
17.3.5 Host slots
One host runs many workload slots. Each slot keeps its own reporter key, because reports, nonces, thewr: hints and pool membership belong to the signing account, but the slots share one accountable stake: the host’s.
A host Runner is an ordinary CIP-2 RunnerRegistration, staked at least MIN_STAKE_CBY_WEI and carrying the route_serving_endpoint of the machine its slots serve from. The host binds each slot key under it. The runner registry (0x01) keeps two rows:
A slot’s accountable registration is its host’s
RunnerRegistration when the slot is bound, and its own otherwise. Every check of §17.3.3 and §17.4.1 that asks for a staked registration and a registered route host reads the accountable registration of the record’s reporter or of the signer. A workload record’s reporter is always the slot key; binding changes no workload record.
RunnerBindSlot { slot } (opcode 245) MUST reject unless all hold:
- the transaction is directly signed, not deferred, and
slotis one of its signers besides the sender; - the sender holds a
RunnerRegistrationthat is not frozen by a pending slash, and is not itself a bound slot; slotdiffers from the sender, is not bound, and has no bound slots of its own; and- the sender has fewer than
MAX_RUNNER_SLOTS = 64bound slots.
RunnerRegistration may be bound. From the binding’s block its accountable registration is the host’s, so it can then deregister and take back its own stake without any of its claims lapsing. A bound slot cannot register: RunnerRegister MUST reject a bound sender. A host cannot leave while it vouches for slots: RunnerDeregister MUST reject a host with a bound slot.
RunnerUnbindSlot { slot } (opcode 246) MUST reject unless slot is bound and the sender is its host or the slot itself. It deletes the slot’s row and removes the slot from its host’s list, deleting the list when it empties. From that block the slot’s accountable registration is its own, if any, and its claims lapse unless that registration meets §17.3.3 check 2.
Slashing is unchanged and applies to the host. A slash of the host reduces the one stake every bound slot claims under; once that stake is below MIN_STAKE_CBY_WEI, every bound slot’s claims lapse in the same block under §17.3.3. One slot’s misbehavior therefore puts the whole host’s hosting at risk. That is intended: the slots of one host are one operator, not independent ones. Pool membership, cordon and reports stay per slot, so a pool owner can still revoke one slot without touching its siblings.
Host slots are gated by the not-before gate RUNNER_HOST_SLOTS_ACTIVATION_HEIGHT (CIP-50 §6). Below its activation height both opcodes reject, no binding row exists, and every check reads the signer’s own registration. The Runner and the Gateway read the slot binding and the accountable registration from finalized state at one proof point (CIP-15 §8.15); before activation that read finds no binding and returns the reporter’s own registration.
17.4 Lifecycle and health
desired_state is written by a sender authorized under §17.3.2. observed_status is written by the record’s reporter except for the consensus-controlled Provisioning initialization and generation reset in §17.3.3. observed_at is written only by those consensus paths, Begin, and accepted reporter updates; neither sender supplies its stored value directly.
ReportWorkloadStatus MUST reject the wrong reporter, a generation mismatch, or an attempt mismatch. Attempt zero MAY report Provisioning or Stopped while desired state is Running, but MUST NOT report Running or Degraded; Begin is required before readiness can make a route eligible. After Stop without a Running attempt and a nonzero recorded drain deadline (attempt_phase != Running or drain_until_block = 0), only Stopped reports are accepted. This prevents a reporter from refreshing observed_at indefinitely and blocking the owner’s stale cleanup or next generation. A nonterminal report MAY be accepted after Stop only for a Running attempt with a nonzero fixed drain deadline. Its acceptance cannot extend that deadline or prevent owner cleanup after it expires, regardless of when the report was signed or submitted. A Prepared attempt’s recorded deadline grants no storage effects and cannot keep refreshing stale cleanup. After an attempt reaches Ended, a report other than Stopped for that attempt MUST be rejected; a late Degraded or Running report cannot replace terminal status or refresh observed_at. Once an attempt reports Degraded, later Provisioning and Running reports for that same attempt MUST be rejected, even if no drain deadline was created; the reporter must reach an accepted Stopped report before another Begin. Every accepted report sets observed_at to the current block, except a repeated Stopped report for an attempt already Ended, which leaves it at the height the attempt ended (§17.3.3); stale cleanup is unaffected, because a Stopped record is removable at once. A Degraded report from a Running attempt starts a fixed 300-block drain only while desired_state = Running, the last accepted Running report is at most 60 blocks old, and no drain deadline is already stored. It MUST NOT create or recreate a drain after Stop.
BeginWorkloadAttempt requires desired_state = Running and the next attempt number within the current generation. If the generation already has an attempt, that attempt MUST have reached Ended through an accepted Stopped report before Begin can replace it. A new generation starts at attempt zero and can Begin attempt one without a predecessor report from the superseded generation.
17.4.1 Route eligibility
A Gateway MAY establish a new workload connection only when all six conditions hold:desired_state = Running;attempt > 0;- the attempt is serving or prepared: either
attempt_phase = Runningandobserved_status = Running, orattempt_phase = Prepared,observed_status = Provisioningandcurrent_block <= prepared_until_block; saturating_sub(current_block, observed_at) <= WORKLOAD_LEASE_TTL_BLOCKS; and- the record’s
reporterstill holds the record’s host-pool entitlement (direct, unexpired, unrevoked, §17.3); and - the
reporter’s accountable registration (§17.3.5) still meets §17.3.3 claim check 2, with aroute_serving_endpointhost equal to the record’s endpoint host.
WORKLOAD_LEASE_TTL_BLOCKS = 60. Eligibility is evaluated from a fresh proof-checked registry read when the connection is established. A later record change does not mutate an established connection.
A Prepared attempt is route-eligible so that a host can serve from the moment its process is ready, while its first Running report is still on its way to finality. A Prepared attempt is visible to the Gateway only after its Begin has finalized, so no route opens before Begin. Route eligibility is not admission: the host still admits a connection only under its own local readiness (§17.4.2), and a connection the host does not admit fails as at any unavailable backend (CIP-15 §8.15). A Prepared attempt stops being route-eligible at the first of: its accepted Running report, which moves it to the Running lease; an accepted Degraded or Stopped report; a Stop; 60 blocks after observed_at, which Begin sets and only an accepted report advances; or prepared_until_block, which bounds it whatever the host reports. An attempt that never obtains an accepted Running report is therefore unroutable no later than its preparation lease, at most MAX_WORKLOAD_PREPARED_LEASE_BLOCKS after Begin.
This 60-block bound governs new route eligibility. It does not require an operator host to terminate a process at block 60, and a host’s local process grace does not extend route eligibility. After launch, only a report accepted into consensus refreshes observed_at; an attempted submission, an HTTP success response, nonce retirement, or local watchdog renewal does not.
17.4.2 Supervisor behavior
The workload MUST exposeGET /_cowboy/health at the serving endpoint’s origin and return 200 only when it is ready to serve. The probe URL keeps the endpoint’s scheme, host, and explicit port, replaces any configured base path with /_cowboy/health, and carries no query or fragment. The first-party supervisor uses:
Three consecutive successful probes report
Running; three consecutive failed probes report Degraded. The reporter MUST submit a status-change report and MUST attempt to renew an unchanged status at least once every 60 blocks. Only acceptance into consensus renews the chain record.
For a Prepared attempt, the supervisor MAY open local admission once three consecutive probes pass on fresh, proof-checked authority that shows the exact attempt’s finalized Begin, and submit the Running report in parallel rather than first. Admission then closes on the first failed probe, a refused Running report, or the end of the attempt’s route eligibility (§17.4.1), whichever comes first. An attempt with a ReadWrite mount MUST keep admission closed until its Running report is accepted, because its manifest writes require the Running lease (§17.5). The first-party host keeps every mounted attempt closed until then.
A typed transient failure fetching authority, submitting or confirming a report, or checking application readiness is unavailable evidence and not a failed /_cowboy/health probe. An actual failed health probe still counts toward the threshold. The supervisor MUST close local admission on the first authority or readiness failure. After fresh, proof-checked authority, required dependency grants, and successful application readiness in the same tick, a report-only submission or confirmation failure MAY leave an existing admission grant in force until its original independent deadline. It MUST NOT open or renew admission on that failure; a host with no prior grant remains closed. The prior grant’s deadline MUST close both new and existing connections even if report transport remains unavailable. A fresh, proof-checked workload record and required dependency grants MAY keep the process under its independent watchdog during a bounded retry. An invalid proof, changed workload identity or generation, revoked or expired grant, or uncertain writer exit MUST fail closed without that grace. Without fresh authority the watchdog MUST expire rather than be renewed from a stale observation.
For first-party hosts, transient readiness and report-transport deferrals have independent clocks. Once a report has been accepted, either deferral MUST enter policy-governed stop and cleanup by the earlier of 240 seconds from its first unresolved attempt or 160 finalized blocks since the last accepted report. Replaying retained signed bytes or retiring a consumed nonce does not reset the report clock without authenticated acceptance. On observing a finalized-height jump to 360 blocks since the last accepted report, the supervisor MUST close admission and initiate cleanup without waiting for either deferral clock. The process MUST NOT continue under that report beyond the separately budgeted shutdown margin; before the first accepted report, an independent 120-second launch watchdog bounds an unready process. These local limits do not extend the 60-block route lease.
The local writer-stop inequality is one necessary admission condition for the first-party host, not a complete proof of workload safety. The host also requires exactly one active validator, operator-attested validator and Linux test artifacts, maximum clock skew of 10 seconds, tested writer termination within 10 seconds, and a minimum finalized block interval of 1 second. It rejects a profile unless the worst-case local writer-stop budget is strictly below the 360-block margin between its local service cutoff and its 720-block last-report limit:
This budget bounds local admission, watchdog expiry, and writer termination. Local process grace does not authorize storage effects; §17.5 governs mount and grant authorization. The budget does not prove that remote mount-material revocation finishes within 320 seconds.
Under unchanged, valid authority and desired state
Running, Never makes every classified process exit or health stop terminal, OnFailure restarts every such outcome except an explicit process exit code of zero, and Always restarts every such outcome. Signal termination, OOM kill, loss of the process without an exit status, nonzero exit codes, and supervisor health, readiness-stall, or report-stall stops are failures; an intentional supervisor termination after desired state becomes Stopped is not. Invalid proof, changed binding, revoked grant, or uncertain exit or cleanup MUST keep admission closed and MUST NOT enter the restart-policy retry loop. Every exit follows the local stop-and-revoke order in §17.4.3; a restart under the same generation also waits for an accepted Stopped report. Consecutive failure number n, starting at zero, waits min(2^n, 60) seconds with no jitter. The retry counter resets only after 300 seconds of continuous healthy operation; changing desired state to Stopped cancels any pending retry.
An operator-installed generic slot may include private runtime files only when its template pins a nonzero owning_actor. The Runner MUST NOT claim a workload owned by a different actor for that slot, preserve the operator-selected source and destination paths when binding the workload, and snapshot private file contents for the launch generation. An unpinned slot MUST have no private runtime files. Actor registry data cannot select or change these files. This local operator provision does not define a chain-level secret capability.
17.4.3 Stop and deregistration
A transition toStopped stops admission of new connections. Existing connections MAY drain for up to 30 seconds before termination. The supervisor MUST withdraw the exiting attempt’s mount access after proving process and writer exit. This does not revoke standing role enrollment merely because an ordinary attempt stopped (§17.4.4).
After any exit, the supervisor MUST prove process and writer termination and withdraw attempt-local mount access. Local access withdrawal and final attempt retirement are separate steps: retained credentials, signed submissions and recovery records MUST remain available until the acceptance or supersession conditions below are proved. If the registry still describes the exiting generation, the reporter MUST obtain an accepted observed_status = Stopped report for that exit, including a terminal exit. A restartable attempt MUST wait for that acceptance before relaunching under the same generation. If a later generation has superseded the exiting attempt, the supervisor MUST NOT report Stopped against that successor. It MAY complete old-attempt cleanup only after authenticating the successor and reconciling any pending old report or independently proving its nonce consumed; a new attempt requires fresh binding to the successor and its grants. A fresh finalized Stop without a Running attempt’s nonzero drain also permanently rejects pending nonterminal reports for that generation; after authenticating that exact binding, the reporter MAY retire those signed bytes without consuming their nonce, preserving the actual nonce floor so it can submit Stopped. An expired serving lease does not prevent proof-checked confirmation of an earlier accepted report needed to submit Stopped; it never reopens admission. While other report reconciliation is unresolved, admission stays closed, any signed submission remains durable, and a terminal attempt remains non-serving. An HTTP response or consumed nonce alone is not acceptance of a Stopped report. If no final report can be accepted, the record becomes removable only through the stale-cleanup path after desired state becomes Stopped.
If final CBFS publication cannot finish before the fixed 300-block storage deadline, chain effects are fenced. The host retains its mount handle and durable recovery journal, keeps admission closed, and requires operator recovery; the deadline does not renew automatically.
DeregisterWorkload requires desired_state = Stopped. An accepted observed_status = Stopped report makes it removable immediately, and so does an unclaimed record at attempt zero, which has no reporter and no writer. Otherwise it becomes removable at current_block >= saturating_add(observed_at, WORKLOAD_LEASE_TTL_BLOCKS + WORKLOAD_STALE_CLEANUP_GRACE_BLOCKS), except that a Running attempt with a nonzero drain_until_block remains live through that block and becomes removable only when current_block > drain_until_block. The same not-live rule applies to every generation-advancing update of a begun attempt. WORKLOAD_STALE_CLEANUP_GRACE_BLOCKS = 30; the ordinary stale comparison is inclusive at its boundary. A fresh Provisioning or Degraded record is not deregisterable.
17.4.4 Attempt admission and standing roles
A workload generation describes the approved process configuration. An attempt identifies one execution under that generation; a routine restart creates a new attempt, not a new standing enrollment. A standing role is a host’s release or commit key for one workload and volume, kept across attempts. A standing role needs no owner signature of its own: the volume owner’s standing mount policy (§17.5) authorizes whichever pool member holds the claim to record its roles at Begin. Retaining a role does not authorize an old process, mount handle or release request to keep working. The reporter MUST signBeginWorkloadAttempt for the exact workload, generation, next attempt, bounded preparation lease and per-volume recipient/key bindings. A mounted attempt MUST be covered, for each mount, by the volume owner’s current mount policy (§17.5) before Begin is accepted; no owner acts per attempt, so a restart, a lapsed claim and a move to another host of the pool need no owner signature. The host may durably prepare its local intent and credentials, but MUST NOT provision workload resources or launch the process until it verifies finalized acceptance of that exact Begin. An RPC acknowledgement or a consumed reporter nonce is insufficient. A prepared attempt is not evidence of Ready or of a Running report; it accepts traffic only once its host’s local readiness admits it (§17.4.2).
The exit sequence is:
- Close local service admission and prove that the process and all writers have exited. If launch never occurred, prove that from the durable launch journal; do not infer it from a missing in-memory handle.
- Withdraw the attempt’s local mount access and stop renewing its attempt-scoped authority. Persist the identities and pending report needed for recovery. A crash between these steps MUST resume cleanup rather than create an untracked replacement writer.
- For the still-current generation, obtain authenticated acceptance of the reporter’s
Stoppedreport for the exact exiting attempt. If a successor supersedes it, use the proof and pending-report reconciliation required by §17.4.3; never report the predecessor’s exit against its successor. - Only then retire the old attempt’s remaining local resources and recovery material. A routine restart MUST repeat Begin admission for its new attempt and reacquire valid attempt-scoped mount/release authority.
17.5 Volume mounts
- the volume MUST exist;
- each volume ID MUST occur at most once, even if two entries use different container paths;
mount_pathMUST be valid UTF-8, absolute, contain no NUL byte,.segment,..segment, repeated/, or trailing/except for the root path, and be no longer than 256 bytes;- mount paths MUST NOT overlap after trailing-slash normalization; and
principalMUST be the volume owner or hold a grant covering the requested access mode.
Running while any mount is unauthorized. Private volumes use the existing CIP-9 and CBSS key-release mechanisms; this section does not create a second key-custody path.
For each private declared volume, the current volume owner signs one standing WorkloadMountPolicyV1 (§17.3.2) naming the workload, the volume, the image, the host pool and the mount mode. The owner’s consent is to the pool: whichever member holds the claim may receive the volume’s DEK and commit to it while the record still runs that image in that pool with that mode. An owner who wants to choose hosts names a pool it owns. At Begin the claimant proposes one release key and one distinct commit key per volume, and BeginWorkloadAttempt MUST require for each mount that the policy row exists, is unexpired at the executing epoch, names the volume’s current owner, the record’s image, host pool and the mount’s mode, and the current chain identity; that the claimant holds the pool entitlement; and that any grantee principal holds a covering whole-volume grant. The recipient a host later presents for DEK release binds the release key, the volume owner, the policy hash, the attempt as its key id, and an X25519 key; release admission rederives it from the current policy, so a recipient bound to a replaced policy or another attempt is never served. The Runner keeps the private keys and opens one host-owned FUSE session per declared volume. A private-volume mount additionally requires a finalized, same-root Ready service release for the exact attempt and recipient, followed by DEK unsealing; a public mount does not require a DEK release.
Each storage effect and DEK release made with a host key is authorized from the same finalized state: the live attempt records the key for the volume, the current policy still covers the record, and the record’s reporter still holds its pool membership. Each of these fails closed, at the next Begin and DEK release, and () also at the next storage effect: the policy revoked () or expired; the volume’s ownership transferred (); a grantee’s grant revoked (); the image, host pool, mount set, mode or principal changed (each generation-advancing, so also () through the attempt binding); the reporter’s pool entitlement revoked (); an owner Stop; and a chain identity mismatch.
The finalized Prepared attempt may use its mount role for reads needed to open the volume, but not for manifest writes. Manifest writes require the finalized Running lease or the exact attempt’s bounded Stop/Degraded drain. Each mutating effect MUST recheck the current volume owner and any required whole-volume grant. A pure Stop on a Running attempt retains only that final host-held storage authority until the first of an accepted Stopped report or the fixed 300-block deadline; it does not reopen Gateway routing. A different generation or ended attempt fences the old keys immediately. The host MUST prove writer exit and durably flush before releasing its FUSE handle; a failed final publication retains the handle and recovery state.
17.6 Billing
Persistent workloads do not use the task-container escrow, compute-metering, or dispute path. Request-level payment is defined outside CIP-10. BelowWORKLOAD_PRICING_ACTIVATION_HEIGHT, persistent-workload host billing remains
absent, unchanged. From its per-network height,
neocloud H1
defines fixed class tariffs, owner-accepted maximum rates (default 2× the rate
card), pro-rata Running-report charges, start/stop/takeover boundaries, payees
and runway checks. A workload registered before the height is billed only once
its owner signs a maximum rate, with no pre-consent charge. Reserved workloads
remain unbilled. A later attempt starts its own cursor, never bills the idle
gap, and closure without a fresh report is capped at the last Running lease.
Billing metadata lives in separate workload-id rows; deregistration nets unpaid
obligations against the deposit and deletes that metadata. Each Runner still accepts only workloads
permitted by its own admission policy; no epoch sweep is introduced.
A Prepared attempt can serve before its first Running report is accepted (§17.4.1). From H1’s height, for a consented unreserved workload, the first fresh authenticated Running report bills the attempt from its Begin cursor through at most Begin’s prepared_until_block (H1 boundaries), so serving while Prepared is billed once that report lands. A funded report pays; an unfunded one freezes that bill as an obligation and withdraws serving eligibility (H1 funding). Serving while Prepared stays unbilled only when no Running report is ever authenticated for the attempt, or when the owner’s maximum falls below the captured tariff during preparation, which ends that interval with no bill. Either window ends with the attempt’s route eligibility, no later than its preparation lease, and the forgone charge belongs to the pool’s payee, the treasury for a cby- pool or the owner of an Account-owned pool, which chose the host.
17.7 Deferred capabilities
- hibernation and summon-on-message;
- live migration of a running process (a lapsed claim moves a workload by restarting it, §17.3.3);
- autoscaling;
- isolation guarantees for third-party hosts;
- persistent-workload host billing and disputes, and with them seeded claimant selection, as job dispatch selects runners, so block order does not decide which admitted Runner wins a paid claim;
- container-to-container networking and multi-container pods; and
- connectors, secret capabilities, and other fields beyond the registry record in §17.3.
17.8 Integration Acceptance
Lifecycle acceptance MUST cover: no provisioning before finalized Begin; a crash after Begin but before launch; proven writer exit with a delayed or lost Stopped response; restart only after the predecessor is safely retired; a routine restart preserving standing identities; and explicit role/grant revocation preventing reacquisition. Tests MUST distinguish transaction submission from authenticated acceptance and prove that late responses for an old attempt cannot authorize its successor. Registry records alone do not establish a working persistent service. Acceptance MUST exercise the supervisor and signed status reporter together with registry handlers and consensus validation. Local tests alone do not establish a working persistent service. The protocol, node, runner, and gateway MUST use the same workload schema and opcodes 196–199 and 226–229 from the core source tree. A separately released consumer MUST pin an exact immutable core revision containing those types and opcodes. Verify supervisor deployment, proof-checked gateway resolution, streaming routes, and workload registration before treating the service as ready. The end-to-end acceptance sequence is:- an old-generation status report rejects;
- a process-changing update rejects while desired state is
Running; - a successful process-changing update clears inherited readiness;
- a new
Provisioningrecord is not stale at its registration block; - stale cleanup rejects one block before its boundary and succeeds at the boundary;
- a fresh
Degradedworkload with desired stateStoppedis not deregisterable; - registration rejects a
workload_idthat does not match its derivation, a sender other than the owning actor’s controller, a reserved name from a non-deployer, and a name outside the §5.11 grammar; - after an ownership transfer, the previous controller can no longer update the workload and the new one can;
- a
system_deployerssender can stop and, once not live, deregister an unreserved workload, and cannot otherwise change it; - the controller cannot change or remove a reserved-name workload;
- a registration naming a reporter or endpoint rejects, and an unclaimed workload is claimable only by a Runner holding its host-pool entitlement, granted directly by the pool’s owner (a delegated entitlement rejects);
- a second claim of a live claim rejects, and a claim during a same-generation restart (after the host’s
Stoppedreport) rejects; - a finalized
Preparedattempt whose host reports local readiness is route-eligible before itsRunningreport lands; without an acceptedRunningreport it stops being eligible 60 blocks after its last accepted report or atprepared_until_block, whichever is first; an attempt whose Begin has not finalized is never eligible; - an attempt-zero claim lapses at
claimed_at + MAX_WORKLOAD_PREPARED_LEASE_BLOCKSeven while its claimant keeps reportingProvisioning; - a lapsed claim is claimable, the new claim fences the old attempt and clears its release slots, and the new claimant Begins a mounted attempt under the existing mount policy with no owner transaction;
- a restart of a mounted workload Begins its next attempt with no owner transaction;
- a mounted Begin rejects with no policy, a revoked, expired, or replaced policy, a policy signed by a previous volume owner, and a record whose image, host pool or mount mode differs from the policy;
- a replaced policy’s signature, any revision at or below the signer’s floor, a revision of
u64::MAX, and a policy signed but withheld before a revocation cannot be published, and a revoke from neither the volume owner nor the signer rejects; - after a transfer from A to B a mounted Begin under A’s unchanged policy rejects, and after a transfer from B to A it Begins again under the same row while that row is unexpired and unrevoked;
- a policy at revision
u64::MAX - 1is revocable and a revoke at the top of the floor still deletes the row; a former owner’s revoke after a transfer, even atup_to_revision = u64::MAX - 1, leaves the new owner’s floor at 0; - a workload ended under
NeverorOnFailureis not claimable, and anAlwaysworkload whose host keeps renewingStoppedlapsesWORKLOAD_CLAIM_LAPSE_BLOCKSafter the attempt ended; - a late Begin from a lapsed claimant rejects;
- a name under
cby-example-rejects for every sender,system_deployersincluded; - a claim through a pool outside the reserved
cby-pools with a.internalorlocalhosthostname rejects, and the Gateway refuses to dial a non-public resolved address for such a claimant; - revoking a Runner’s pool entitlement, or its expiry, makes the workloads it holds through that pool claimable at once and rejects its further Begin, storage effects, DEK releases, and non-
Stoppedreports for them; - a claim through a pool outside the reserved
cby-pools with a private, loopback, or metadata endpoint rejects; - a host-pool grant from anyone but the pool’s owner rejects, and
host_pooldecode rejects an 84-byte id, a zero owner address, an invalid name, and acby-example-id; - an image name whose digest no longer serves still belongs to its controller and still resolves to that digest, and only the controller can rebind it;
- a controller’s update back to
Runningclears the claim, and an unclaimed record can be deregistered immediately after Stop; - a digest’s
il:index entry is written with its first locator, stays while the digest is tombstoned, is deleted when its last locator is reaped, and is written again when the digest is registered again; - a second publisher adds a locator for an existing digest, a fifth is refused, and a mirror publisher can neither re-point nor delete the name;
- deregistration by the controller refunds the deposit, and deregistration by another
system_deployerssender forfeits it to the treasury; - a claim from a reporter without a staked accountable registration, or with an endpoint host other than the one that registration names, rejects;
- a bound slot with no
RunnerRegistrationof its own claims, Begins and stays route-eligible under its host’s stake and route host; - slashing a host below
MIN_STAKE_CBY_WEIlapses the claims of every slot bound to it in the same block, and unbinding a slot lapses that slot’s claims; RunnerBindSlotwithout the slot’s co-signature, for a slot already bound, atMAX_RUNNER_SLOTS, withslotequal to the sender, from a sender that is itself a bound slot, from an unregistered or slash-frozen sender, and in a deferred transaction rejects;RunnerUnbindSlotof an unbound slot, or from neither its host nor the slot, rejects;RunnerRegisterfrom a bound slot rejects, andRunnerDeregisterfrom a host with a bound slot rejects;- below
RUNNER_HOST_SLOTS_ACTIVATION_HEIGHTboth slot opcodes reject and every claim check reads the signer’s own registration; - binding a staked slot to its host and then deregistering the slot refunds the slot’s stake while its
Runningworkload stays claimed and route-eligible; - a repeated
Stoppedreport for anEndedattempt leavesobserved_atunchanged; and - registration rejects an actor at
MAX_WORKLOADS_PER_ACTOR, counting unreserved workloads only.
18. Examples
18.1 Isolated Script
The following shows the runtime portion of a container job; surrounding submission and storage fields follow CIP-2 and CIP-9:18.2 Model Harness
A research harness can read prior notes and write updated reports under/mnt/volumes/notes. A registered digest image supplies its tools and dependencies; a read/write volume attachment supplies persistence. Final synchronization and a storage commitment are required before claiming those notes are durable.
A hosted model such as Claude additionally needs §9.2 egress and an authorized credential-delivery mechanism (§6.2). Listing a hostname or putting an encrypted API key in a job does not make it executable under NetworkPolicy::None.
18.3 GPU Inference
A batch inference process can load a model from a read-onlymodels volume and write output to a scoped predictions volume. This scenario uses GPU execution and filtering under §8 and §14.6. No egress is necessary when the model and input are already mounted. An indefinitely warm inference process instead uses the workload lifecycle in §17.
18.4 Custom Tools
A financial-analysis application can bundle specialized tools in a delta over a pinned base, register its composed BLAKE3 digest and locator, then publish the archive following §5.6 and mount a prefix-scoped reports volume. Each analyst stages its reports; it cannot publish the root itself, so a full-volume holder such as the coordinator reviews and finalizes each stage (CIP-9 §7.3.1). The model sees ordinary files and commands. External data collection still depends on §9; tasks coordinate through authorized storage. They have no direct inter-container networking.18.3 Signing Bundle
A venue-signing image composed oncby-runner-python: its command reads the venue key from the environment, signs the order offline, and prints the request the actor should send. No network policy is needed, and no venue-specific code exists in the runner.
secrets= is the authorization (CIP-24 §5.2, hashed on the wire); secret_env= is the delivery. The manifest declares container.run and secrets.read for the same key. Adding a venue is a change to the image, never to the runner.
19. Container Security Profile
The required security profile below must be checked against the concrete OCI configuration and runtime. It is not a complete seccomp JSON program: syscall arguments, architecture variants, networking restrictions, and namespace enforcement require their own verification against the host, including failure paths. Runners MUST apply at least these restrictions: Allowed syscall categories:- Process management:
clone,fork,execve,exit,wait4,kill,getpid,getppid - File I/O:
open,read,write,close,stat,fstat,lstat,readdir,mkdir,unlink,rename - Memory:
mmap,munmap,mprotect,brk,madvise - Network (if allowlisted):
socket,connect,sendto,recvfrom,bind(task ingress remains blocked by the network policy) - Time:
clock_gettime,nanosleep,gettimeofday - Misc:
ioctl(limited),fcntl,pipe,poll,select,epoll_*,futex
- Mount operations:
mount,umount2,pivot_root(FUSE mounts are set up by the host before container start) - Module loading:
init_module,finit_module,delete_module - System:
reboot,sethostname,setdomainname,syslog - Dangerous:
ptrace,process_vm_readv,process_vm_writev,kexec_load - Raw I/O:
iopl,ioperm
Shared refusal contract
Workload-registry and native route-admission refusals use the structured admission contract. At A’s height, quota refusals gain the retryable quota code withretry_after,
and the formerly bare InvalidData workload refusals gain allocated
closed-list reasons distinguishing held claims, draining attempts and
mutable generation/image conflicts from terminal constraints. Below A,
retain the old code/context exactly. Clients must handle both forms.