​

CIP-10: Runner Container Runtime

​

1. Background

​

2. Goal

​

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 rather than an individual job (§17).
• OCI runtime bundle: A root filesystem and OCI runtime configuration used to launch a container. The required CBFS path constructs the filesystem under §5.8. OCI manifest and layer pulls are outside that path; the inspected executor still uses operator-provisioned filesystems.
• 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. Protocol BaseImage enum keys resolve through reserved registry names; application deltas pin their base by digest.

​

4. Design Overview

​

4.1 Architecture

1. Resolves the registered image, fetches and composes it on a cache miss, and verifies its digest (§5).
2. Creates a container with the specified resource limits and network policy.
3. Mounts CIP-9 volumes as FUSE filesystems inside the container.
4. Starts the container entrypoint.
5. Monitors execution until completion, timeout, or crash.
6. Commits storage manifests and submits results onchain.
7. 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_attachments are 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

ImageRef::Base(BaseImage)
ImageRef::Digest([u8; 32])

​

5.2 Artifact Identity and Digest

• The registered digest MUST be the blake3 rootfs digest of the composed tree, computed with the recipe below. No second identity is introduced; ImageRef::Digest (cowboy-protocol/crates/cowboy-protocol-codec/src/job_spec/container.rs:86-89) continues 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 = None registers 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 with base = 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.

walk(base, dir):
    entries := read_dir(dir)                      # error propagates; no entry is skipped
    sort entries by file_name()                   # OS byte order of the file name, per directory
    for e in entries:
        path := e.path()
        rel  := path relative to base             # never includes the root itself
        meta := symlink_metadata(path)            # lstat: symlinks are NOT followed

        emit rel.to_string_lossy() as bytes
        emit 0x00
        emit (meta.permissions().mode() as u32).to_le_bytes()    # 4 bytes, little-endian
        emit 0x00

        if meta is symlink:   emit read_link(path).to_string_lossy() as bytes
        elif meta is file:    emit file contents
        elif meta is dir:     walk(base, path)                    # inline recursion, no marker
        else:                 emit nothing                        # fifo/socket/device: path+mode only

        emit 0x00                                 # trailing NUL closes every entry, including dirs

• Sorting is per directory, by file_name(), not a global sort over full paths. A directory’s subtree is emitted inline between its own path ‖ NUL ‖ mode ‖ NUL prefix and its trailing NUL; there is no separate directory terminator or depth marker.
• The mode is the full st_mode as 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.

​

5.3 Delta and Composition

• Every member path MUST be relative and MUST be under app/. Absolute paths, .. components, and members outside app/ 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 reconciliation: a review request to make “an empty delta invalid” is honored for the zero-member case; a delta consisting only of app/ remains valid because the reference assembler emits it deliberately, package.rs.)
• uid, gid, mtime, atime, ctime, device major and minor, and owner and group names MUST all be normalized to 0 / empty. The gzip header’s mtime MUST be 0 and its OS byte 255 (unknown). None of these fields participate in the digest — the digest hashes only relative path, mode, and content or link target (§5.2) — but normalizing them is what makes the archive itself 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 0o777 and directory modes created by the assembler to 0o755. This is not cosmetic: Linux reports symlink modes as 0o777 while macOS applies the process umask, and the recipe hashes the mode, so an unnormalized symlink digests differently on the two platforms (cli/crates/offchain-image/src/fsutil.rs).

• regular files MUST be 0o644, or 0o755 when 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.

• a *.dist-info/ directory MUST contain only METADATA, WHEEL, top_level.txt, entry_points.txt, namespace_packages.txt, INSTALLER, REQUESTED, and license or notice files;
• bin/, RECORD, direct_url.json, uv_cache.json, .lock, and __pycache__ MUST be absent anywhere in the delta; and
• bytecode MUST NOT be compiled into the delta.

​

5.4 Storage and Availability

• The volume MUST be Visibility::Public (node/ras/src/types.rs:230) (proposed — the plan says “public CBFS volume” without making it a checked precondition; 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: status leaves Active, 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.
• Rent is not the only way an image dies. 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 stays Active and the registration stays admissible. Admission cannot detect this; the failure surfaces as a cold runner failing to fetch. 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 {
  digest:       [u8; 32],          // composed rootfs digest (§5.2); MUST NOT be zero
  base_digest:  Option<[u8; 32]>,  // u8 0 = None | 1 ‖ [u8; 32]
  name:         Vec<u8>,           // ≤ 64, UTF-8; empty for an unnamed image
  volume_id:    [u8; 32],
  object_path:  Vec<u8>,           // ≤ 256, UTF-8 CBFS manifest path
  object_hash:  [u8; 32],          // BLAKE3 plaintext content hash of the delta object
  delta_bytes:  u64,
  rootfs_bytes: u64,
}

• Re-registering an existing name under a different digest MUST be rejected. There is no in-place base refresh.
• A new base release is therefore either a new name, or requires an explicit DeregisterImage of the old digest first — which is reference-count gated, so a base cannot be retired out from under a workload that references it.

• name empty — an ordinary permissionless registration. Any account MAY submit it. The empty case MUST bypass validate_name (container_registry.rs:76-84), which rejects an empty name; no BaseImageEntry is written.
• name non-empty — it MUST be a protocol base-image enum key (runner-base, runner-python; job_spec/container.rs:35-52) and the sender MUST hold a genesis.system_deployers key. Binding an enum key is a protocol-trust operation: an unprivileged account that could rebind runner-python would capture every ImageRef::Base(RunnerPython) job on the chain. This is the only privileged case in this section.

1. digest is non-zero and is not already registered, live or tombstoned. Registration is create-only; there is no refresh. (This tightens the current register_base_image, which rewrites an existing name→digest binding, container_registry.rs:551-561.)
2. The StorageCommitment for volume_id exists at the Storage Manager (0x0A) under sm_keys::volume_key — the same read the registry already performs for workload mounts (node/execution/src/execution/container_registry.rs:304-312).
3. commitment.status == VolumeStatus::Active (node/ras/src/types.rs:262). Registering into a volume already in grace is refused; grace only extends an existing registration (§5.7).
4. commitment.visibility == Visibility::Public (proposed, §5.4).
5. commitment.owner equals the transaction signer.
6. object_path is non-empty, valid UTF-8, and within its cap; object_hash is non-zero.
7. delta_bytes <= MAX_IMAGE_DELTA_BYTES and rootfs_bytes <= MAX_COMPOSED_ROOTFS_BYTES (§5.9).
8. If base_digest = Some(d), d resolves to a live (non-tombstoned) locator, that locator’s own base_digest is None (one-level composition), and its volume is live under §5.7 (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).
9. If name is non-empty, the name/system_deployers rule above, and no existing entry for that name under a different digest.
10. 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 digest→name index the current RegisterBaseImage writes, at system:container_registry:digest:<digest> (container_registry.rs:64-67, 574-581), so §5.7 admission and get_image_name_by_digest (container_registry.rs:623-640) keep working unchanged. 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 (node/execution/src/runner/dispatcher.rs:5467-5477), so an empty string would be indistinguishable from a corrupt entry; hex gives clients a stable display name). Note that 64 hex characters is exactly CONTAINER_NAME_MAX_LEN (container_registry.rs:24), so the hex form fits the existing bound with no slack — the index value is written directly and is not routed through validate_name;
• for a named registration, the BaseImageEntry at system:container_registry:image:<name> exactly as today (container_registry.rs:562-573), with size_bytes = rootfs_bytes;
• the locator record at system:container_registry:image_locator:<digest> (proposed key, following the actor’s existing system:container_registry:<family>:<suffix> idiom, container_registry.rs:57-105), serde-JSON like every other value this actor stores; and
• the per-volume registration counter at system:container_registry:image_count:<volume_id> (proposed), a u64 JSON-decimal count in the same style as the existing workload reference counts (container_registry.rs:182-215), incremented here and decremented when the locator is reaped — not when it is tombstoned.

ImageLocator {
  digest:        [u8; 32],
  base_digest:   Option<[u8; 32]>,   // pinned at registration; never re-resolved
  name:          Option<String>,     // Some only for a protocol base key
  publisher:     Address,
  volume_id:     [u8; 32],
  object_path:   String,
  object_hash:   [u8; 32],
  delta_bytes:   u64,
  rootfs_bytes:  u64,
  registered_at: u64,                // block height
  tombstoned:    bool,
  tombstoned_at: u64,               // 0 while live; set at phase 1
}

​

5.6 Resolution and Publication

1. submit RegisterImage and observe its commitment on chain; then
2. make the delta object publicly readable; and only then
3. disclose the digest.

​

5.7 Admission

• the digest resolves through the digest index — the check that exists today at node/execution/src/runner/dispatcher.rs:5467-5477, inside escrow_container_compute (dispatcher.rs:5457); and
• the locator’s volume commitment loads and its status is exactly Active or exactly GracePeriod.

​

5.8 Fetch, Compose, Verify, and Cache

1. Read the locator for the digest from the Container Registry, proof-checked.
2. Resolve the base from base_digest — never from a name. If base_digest = Some(d), ensure d is installed locally, fetching it by this same procedure first. Bases are pinned once installed.
3. Fetch the object at object_path from the public volume using the existing CBFS SDK client already used for runner storage. The fetch MUST be subject to IMAGE_PULL_TIMEOUT_SEC (§13) and MUST abort as soon as the streamed byte count exceeds min(delta_bytes, MAX_IMAGE_DELTA_BYTES). A publisher who under-declares delta_bytes cannot make a runner stream more than it agreed to.
4. Verify the object hash against object_hash before anything is extracted. A mismatch aborts; the bytes MUST NOT be written into the image root.
5. 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 under app/; 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 exceeding min(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).
6. 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.
7. Digest and compare. 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. This is the same rule the existing verify_digest_root enforces for provisioned trees (runner/crates/runner-container/src/image.rs:98-120); this section extends it to fetched ones.
8. 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.
9. Record the fetch in the cache index for LRU accounting.

• A digest whose fetch failed for a transient reason (timeout, relay unavailable, object temporarily missing) MUST NOT be retried before an exponential backoff elapses, 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 — 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, not a transient condition; retrying it burns bandwidth to reach the same conclusion and is exactly the shape an attacker would use to amplify a registration into repeated runner work.

​

5.9 Image Limits

​

5.10 Protocol Base Images

​

6. Runtime Environment

​

6.1 Filesystem

​

6.2 Environment

​

6.3 Command

​

6.4 User and Permissions

​

7. Resource Limits

​

7.1 Resource Declaration

ResourceClassEntry {
  name: String,
  cpu_millicores: u32,
  memory_mib: u32,
  scratch_disk_mib: u32,
  max_duration_sec: u32,
  gpu_count: u8,
  gpu_min_vram_mib: u32,
}

​

7.2 Enforcement

​

7.3 Executable Tiers

​

7.4 Capabilities and Selection

• The runner-side mirror of the capability struct (runner/crates/runner-common/src/types.rs:193-202) has no serves_registered_images field, so no runner can advertise it today even though the node’s dispatcher already filters on it. Adding the field and advertising it is REQUIRED.
• RunnerCapabilities round-trips through bincode into sled on the runner side. The struct comment and runner_registration_bincode_roundtrips_optional_capability_fields test require positional serialization without skipped fields. Adding serves_registered_images changes that stored record shape; #[serde(default)] does not make bincode self-describing. Persistence and deployment acceptance follow §16.4.

​

8. GPU Passthrough

​

8.1 GPU Request

GpuRequest {
  count:          u8,        // number of GPUs requested
  min_vram_mib:   u32,       // minimum VRAM per GPU
  compute_cap:    string?,   // minimum CUDA compute capability (e.g., "8.0")
  driver:         string?,   // required driver framework ("cuda", "rocm")
}

​

8.2 Device Exposure

• 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/kfd and /dev/dri/render*.

​

8.3 GPU Capability in Runner Registry

GpuDevice {
  vendor:        string,     // "nvidia", "amd"
  model:         string,     // "A100", "H100", "MI300X"
  vram_mib:      u32,        // e.g., 81920 for A100-80G
  compute_cap:   string,     // e.g., "8.0" for A100
}

​

8.4 Capability Filtering

​

9. Network Policy

​

9.1 Default: Isolated

​

9.2 Egress Allowlist

// Egress requirements; not the RuntimeConfig wire schema.
EgressRule {
  host:     string,          // hostname or IP (e.g., "api.anthropic.com", "api.moonshot.cn")
  port:     u16?,            // specific port (default: 443)
  protocol: ENUM { TCP, UDP },  // default: TCP
}

• No wildcards: Each allowed host must be explicitly listed. *.example.com is 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.conf points 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

​

10. Container Lifecycle

​

10.1 Execution Flow

​

10.2 Setup and Teardown

​

10.3 Failures

​

10.4 Exit Evidence

​

11. On-chain Interface

​

11.1 Container Jobs

RuntimeConfig {
  image: ImageRef,
  command: Vec<String>,
  resource_tier: ResourceTier,
  network: NetworkPolicy,
  min_isolation_tier: IsolationTier,
}

​

11.2 Container Registry

BaseImageEntry {
  name: String,
  digest: [u8; 32],
  size_bytes: u64,
  updated_at: u64,
}

​

11.3 Storage

system:container_registry:image:<name>
system:container_registry:class:<name>

​

11.4 Instructions

​

11.5 Image Access Weights

​

12. Billing and Fees

​

12.1 Compute Escrow

max_compute_cost = cpu_millicores * max_duration_sec * cpu_rate / 1000
                 + memory_mib * max_duration_sec * mem_rate / 1024
                 + gpu_count * max_duration_sec * gpu_rate

​

12.2 Metered Charge

d_ms = max(actual_duration_ms, 100)
measured_cost = cpu_used_millicores * d_ms * cpu_rate / 1000 / 1000
              + peak_memory_mib * d_ms * mem_rate / 1024 / 1000
              + gpu_seconds * gpu_rate
actual = min(measured_cost, escrowed)
refund = escrowed - actual

​

12.3 Attestation and Disputes

BillingAttestation {
  cpu_used_millicores: u32,
  peak_memory_mib: u32,
  actual_duration_ms: u32,
  gpu_seconds: u32,
  bytes_egressed: u64,
  cgroup_digest: [u8; 32],
  metered: bool,
  tee_attestation: Option<Vec<u8>>,
}

​

12.4 Separate Accounting

​

12.5 Settlement Split

SettlementConfig {
  runner_percent: 89,
  treasury_percent: 1,
  burn_percent: 10,
}

​

12.6 Cold-Fetch Fee

• Parameter. cip10.container.cold_fetch_fee_per_mib, in wei per MiB of delta_bytes, registered alongside the three existing container paths (node/runner/src/types.rs:1905-1907). Default 0 — the fee is inert until cold-start cost is measured.
• Charge. fee = ceil(delta_bytes / 1 MiB) * rate, computed from the registered delta_bytes, not from anything the runner reports (proposed rounding).
• Reservation. The fee is reserved from the submitter at submit_task in the same handler that escrows max_compute_cost (node/execution/src/runner/dispatcher.rs:5457), on top of it (proposed — the plan says “taken from the job’s escrow”, which could also mean carved out of max_compute_cost; charging on top 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).
• Snapshot. Both the rate and the computed fee amount and delta_bytes MUST be snapshotted into the JobComputeLock at submit (node/runner/src/types.rs:3513-3527), 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. Snapshotting delta_bytes alongside makes the lock self-describing for audit.
• Lock existence. The lock MUST be written whenever max_compute_cost + cold_fetch_fee > 0. The current handler returns early when the compute cost is zero (dispatcher.rs:5490-5493), which would drop a cold-fetch-only lock on the floor for a job whose resource class prices to zero.
• Settlement. 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.
• Disputed jobs. A DisputeContainerBilling affects 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.
• Attestation field. BillingAttestation (node/runner/src/types.rs:3355-3380) has no cold-fetch field today. Adding image_cold_fetch: bool is REQUIRED. Like metered, it is self-reported; unlike metered, it has no cgroup evidence behind it (§14.2).

​

13. Parameters

​

14. Security Considerations

​

14.1 Container Escape

• 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: --privileged is 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 implemented tier.

​

14.2 Image Supply Chain

​

14.3 Network Exfiltration

• 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 bandwidth limit MUST prevent a container from saturating the Runner’s network.

​

14.4 Resource Exhaustion

• 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.
• CIP-9 quotas: Volume write quotas are enforced by CapToken max_bytes.

​

14.5 Secret Leakage

• No host env inheritance: Container environment is clean — only explicitly constructed runtime metadata and approved application values.
• 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

• 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

​

15.2 Cgroup Metering

cgroup_digest = blake3(cpu.stat || NUL || memory.peak)

​

15.3 Startup and Logs

​

16. Implementation Scope

​

16.1 Evidence

​

16.2 Remaining Requirements

• Capability safety: qualify actual sandbox launch, cgroup delegation, and resource capacity before advertising; test the unsafe no-cgroups registration guard and reject unsupported requested policies.
• Storage and cleanup: exercise the actual caller path through authorized mount, writes, final sync, storage commitment, result submission, timeout/failure, and credential cleanup. Verify scratch quotas and bounded output capture. Correct termination attribution: the current driver classifies exit 137 as OOM, which does not satisfy §10.4 without independent OOM evidence.
• GPU execution: implement §8’s device allocation, compatible runner filtering, and §14.6 isolation/clearing before enabling GPU tiers.
• Egress: implement §9’s allowlist, DNS/IP pinning, SNI checks, TTL refresh, and bandwidth enforcement, with an explicit credential-delivery mechanism for authenticated model APIs. The rule limit target is 32; a bandwidth value is not yet specified.
• Image distribution: implement permissionless registration, locator and tombstone storage, access weights, volume admission, hardened fetch/composition, bounded positive and negative caches, and capability matching under §5, §7.4, and §11.5. Integrate the cold-fetch reservation, attestation field, and settlement in §12.6. The image caps are §5.9 and the fetch timeout is §13; they are requirements, not evidence of a live fetch path. Resolve the publication-order versus per-owner-locator decision recorded in §5.6. Private-image access and runner-initiated decline remain deferred (§14.2 and §16.3).
• Image retention: validate the proposed 600-block tombstone grace against actual admitted-job lifetimes, redraw chains, and job-configured dispute windows before relying on reaping to release in-flight locators (§5.5). The sizing assumption is not a proven lifetime bound.
• Other image paths: OCI 1.1 image/Docker distribution manifests, architecture selection, and public/private OCI registries remain deferred, with a retained 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. These requirements do not provide a second provisioning path for the registered images in §5.
• Larger resource envelopes: retained design ceilings are 16,000 millicores, 65,536 MiB memory, 204,800 MiB scratch, 7,200 seconds, and eight GPUs per task. They require executor, admission, and pricing coverage before use; custom limit overrides are not in the wire schema.
• Dispute bond: the retained proposal for a refundable dispute bond has no amount or implemented handling. Define a valid-dispute criterion and refund rule before introducing it; §12.3 currently uses full-escrow fallback without adjudication or a bond.
• Security profile: verify the §19 syscall policy and actual host restrictions, including failure paths, rather than inferring them from OCI compatibility.
• Authenticated metering: provide CAE generation, activation, and verified meter binding under CIP-23, plus dispute rejection and settlement tests through the actual submission path. The dormant verifier is not an activated service.
• Persistent workload acceptance: exercise the implemented signed reporter, health/restart/drain loop, lease-expiry shutdown, and workload mount authorization through the generic Runner’s discovery and live gateway path. Complete the acceptance sequence in §17.8.

​

16.3 Assignment Decline

• an opcode in the container block or the next free system slot;
• fields { job_id, assignment_hash, reason }, where reason distinguishes image-fetch failure from capacity and from capability;
• sender authorization restricted to a current assignee of that job — no third party may decline on a runner’s behalf;
• binding to the assignment hash, so a decline cannot replay against a later assignment of the same job;
• clearing the job’s timeout index entry (query::put_job_timeout_index, dispatcher.rs:3450-3456) as part of the same transaction, so the redraw is immediate and the stale timeout does not fire later;
• a redraw that excludes the decliner, reusing the existing excluded argument to the v3 candidate-snapshot builder;
• a per-epoch decline cap per runner, so declining is not a free way to cherry-pick jobs; and
• a liveness-score effect smaller than a timeout’s but not zero, so that declining is cheaper than stalling and more expensive than serving.

​

16.4 Image Integration

• RegisterImage and DeregisterImage own opcodes 160 and 161 with the payloads in §5.5. Decoders MUST accept only the §5.5 payload shapes for these opcodes; alternative payload layouts MUST reject, with negative decode fixtures covering the name/digest/size and name-only layouts. Shared instruction encoding and exact protocol dependency pins MUST agree across cowboy-protocol, node, runner, and the CLI; opcode uniqueness tests MUST cover 160–165.
• Protocol base images MUST be registered before a job uses their enum keys. Both base and digest jobs match on fetch capability, not a warm-cache inventory (§7.4).
• ImageRef, RuntimeConfig, the container job type, and resource-class wire shapes are unchanged. The image locator and registration instructions, JobComputeLock fee snapshot, and BillingAttestation.image_cold_fetch require their specified producer/consumer changes. Compute settlement, disputes, and the independent cold-fetch component MUST follow §12.
• Adding serves_registered_images changes the runner’s bincode-persisted capability record. Persisted registration stores MUST be recreated for that record shape; integration coverage MUST exercise this replacement as well as a fresh runner. The node-side base_images field keeps its wire shape and is informational.
• The CBFS path MUST use the existing public-volume client and verify both the plaintext object hash and composed rootfs digest. A working local assembler alone does not satisfy the fetch, admission, and settlement contract.

​

16.5 Exclusions

​

17. Persistent Workloads

​

17.1 Scope

​

17.2 Workload model

• It has no max_duration_sec bound. 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.

​

17.3 Registry record

system:container_registry:workload:<workload_id>

WorkloadRecord {
  workload_id:      [u8; 32],
  generation:       u64,
  attempt:          u64,
  attempt_phase:    WorkloadAttemptPhase,
  prepared_until_block: u64,
  drain_until_block: u64,
  attempt_recipients: list<WorkloadAttemptRecipient>,
  owning_actor:     Address,
  image:            ImageRef,
  resource_class:   bytes,
  volume_mounts:    list<WorkloadMount>,
  serving_endpoint: bytes,
  restart_policy:   RestartPolicy,
  desired_state:    WorkloadDesiredState,
  observed_status:  WorkloadObservedStatus,
  observed_at:      u64,
  reporter:         Address,
}

WorkloadChanges {
  image:            Option<ImageRef>,
  resource_class:   Option<bytes>,
  volume_mounts:    Option<list<WorkloadMount>>,
  serving_endpoint: Option<bytes>,
  restart_policy:   Option<RestartPolicy>,
  desired_state:    Option<WorkloadDesiredState>,
  reporter:         Option<Address>,
}

​

17.3.1 Enum tags

​

17.3.2 Instructions

​

17.3.3 Registration and updates

• generation = next chain-wide generation (1 if no generation has been assigned)
• observed_status = Provisioning
• observed_at = current_block

​

17.3.4 Endpoint validation

• UTF-8 encoding;
• an absolute http or https URL;
• an explicit host and port;
• no userinfo, query, or fragment; and
• a maximum encoded length of 256 bytes.

​

17.4 Lifecycle and health

​

17.4.1 Route eligibility

• desired_state = Running;
• observed_status = Running;
• attempt > 0;
• attempt_phase = Running; and
• saturating_sub(current_block, observed_at) <= WORKLOAD_LEASE_TTL_BLOCKS.

​

17.4.2 Supervisor behavior

​

17.4.3 Stop and deregistration

​

17.4.4 Attempt admission and standing roles

1. 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.
2. 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.
3. For the still-current generation, obtain authenticated acceptance of the reporter’s Stopped report 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.
4. 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

WorkloadMount {
  volume:     [u8; 32],
  mount_path: bytes,
  mode:       WorkloadMountMode,
  principal:  Address,
}

• the volume MUST exist;
• each volume ID MUST occur at most once, even if two entries use different container paths;
• mount_path MUST 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
• principal MUST be the volume owner or hold a grant covering the requested access mode.

​

17.6 Billing

​

17.7 Deferred capabilities

• hibernation and summon-on-message;
• migration and rescheduling across hosts;
• autoscaling;
• third-party scheduling and isolation;
• persistent-workload host billing and disputes;
• 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

register → [mounted: offer and owner certificates] → Begin → report Running → relay a route → Stop and drain → report Stopped → deregister

• 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 Provisioning record is not stale at its registration block;
• stale cleanup rejects one block before its boundary and succeeds at the boundary; and
• a fresh Degraded workload with desired state Stopped is not deregisterable.

​

18. Examples

​

18.1 Isolated Script

RuntimeConfig {
  image: ImageRef::Base(BaseImage::RunnerBase),
  command: vec!["/bin/sh".into(), "-c".into(), "echo hello".into()],
  resource_tier: ResourceTier::Small,
  network: NetworkPolicy::None,
  min_isolation_tier: IsolationTier::Standard,
}

​

18.2 Model Harness

​

18.3 GPU Inference

​

18.4 Custom Tools

​

19. Container Security Profile

• 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