​

CIP-10 v2

Versioning. This is v2 of CIP-10. v1 is preserved verbatim as Part I. v2 combines that base specification, the code-alignment revision, and the persistent-workload class. Conflict rule: Part II is canonical wherever it contradicts Part I. The Persistent Workloads section is canonical for persistent workloads and supersedes the Part I §16.2 deferral of long-running services. The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174. Summary of v2 changes

• Container Registry actor allocated at 0x13 (0x11 is the CIP-11 VALIDATOR_SET genesis snapshot and 0x12 is the CIP-18 PaymentGate reservation, so the registry takes the next free slot).
• Fee distribution routes through a SettlementConfig at GOVERNANCE_SYSTEM_ACTOR=0x09 via a dedicated UpdateContainerSettlementConfig opcode (164) — matching the existing per-pool UpdateRegistrySettlementConfig pattern rather than a single opcode with a target_pool discriminant (the live codec never adopted the discriminant form).
• Three-flow off-chain billing model clarified: runner job (CIP-2), storage rent (CIP-9), container compute (CIP-10) are independent escrows that share only the SettlementConfig shape, each with its own update opcode.
• BillingAttestation.tee_signature will upgrade to CompositeAttestation per CIP-23 v2 §3.12; the shipped Phase-B type carries Option<String> pending that TEE wiring.
• System instruction opcodes 160–164 allocated for the Container Registry per the live codec (CIP-13 v2 §1 authoritative wire table; the next free block after system-DKG took 158–159). Image/class registration is system_deployers-gated (operational, like the CIP-23 TEE trusted-key registry), while UpdateContainerSettlementConfig stays governance/0x09-gated (economic, like UpdateRegistrySettlementConfig).
• Billing meters real cgroup accounting at millisecond granularity with a 100 ms floor; the enforced-cgroup Standard sandbox runs rootless runc via systemd-cgroup delegation (§6–7 below).

​

Part I — v1 Specification (verbatim from cip-10-runner-containers.md)

​

1. Abstract

• OCI-compatible: Containers use standard OCI images. Any image that runs on Docker or Podman runs on a Cowboy Runner.
• Storage-integrated: CIP-9 volumes are mounted as FUSE filesystems inside the container at deterministic paths. The model or script sees a standard filesystem.
• Resource-bounded: Every container declares CPU, memory, disk, and optional GPU limits. Runners enforce these limits and refuse tasks that exceed their capacity.
• Network-isolated: Containers run with no ingress and allowlisted egress by default. The task definition specifies which external endpoints are reachable.
• Ephemeral: Containers are destroyed after job completion. All persistent state lives in CIP-9 volumes; the container’s own filesystem is scratch space.
• Model-agnostic: The runtime supports LLM tool-calling workloads (Llama, Kimi-K2, Claude, GPT, etc.), Python scripts, compiled binaries, and arbitrary OCI entrypoints with the same container primitive.

​

2. Motivation

1. What environment does the code run in? A bare Python process? A Docker container? A VM? Without a standard, Runners cannot guarantee reproducible execution.
2. How are dependencies managed? An ML inference job needs specific library versions, model weights, and system packages. The Runner node’s host environment should not bleed into the job.
3. How is the job sandboxed? A malicious task definition could attempt to access the Runner’s host filesystem, exfiltrate secrets, or abuse network access.
4. How are hardware accelerators exposed? GPU inference requires device passthrough with controlled access.
5. What does an LLM see? When Claude or Kimi-K2 runs as a Cowboy Runner doing tool calling, it needs a shell environment with its standard tools (Read, Write, Bash, etc.) operating against mounted volumes. The container must provide this environment transparently.

​

3. Definitions

• Container: An isolated, ephemeral execution environment created from an OCI image. A container has its own filesystem root, process namespace, network namespace, and resource limits. It is destroyed after the job completes.
• OCI Image: A container image conforming to the Open Container Initiative Image Specification. Consists of an ordered set of filesystem layers, a configuration (entrypoint, env vars, working directory), and a manifest.
• Image Manifest: The OCI descriptor that identifies an image by its content-addressed digest (sha256:...). Pinning a digest ensures reproducible builds.
• Runtime Config: A structured definition within a CIP-2 task that specifies the container image, resource limits, network policy, GPU requirements, volume mounts, and environment variables for the job.
• Scratch Filesystem: The container’s own writable filesystem layer (overlayfs). This is ephemeral and destroyed on container teardown. It is NOT backed by CIP-9 storage.
• Base Image: A pre-built, protocol-maintained OCI image optimized for common Runner workloads (LLM tool-calling, Python data science, etc.). Base images may be cached on Runner nodes for fast startup.

​

4. Design Overview

​

4.1 Architecture

1. Pulls the container image (if not cached).
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): CIP-10 extends the OffchainTask struct with a runtime_config field that specifies the container environment. The existing VRF selection, result submission, and deferred callback mechanisms are unchanged.
• 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 Format

• application/vnd.oci.image.manifest.v1+json
• application/vnd.docker.distribution.manifest.v2+json (Docker v2, backward-compatible)

​

5.2 Image Addressing

ImageRef {
  registry:  string,        // registry hostname (e.g., "registry.cowboylabs.org", "ghcr.io")
  repository: string,       // image name (e.g., "cowboy/runner-base")
  digest:    string,        // content-addressed digest (e.g., "sha256:abc123...")
  tag:       string?,       // optional human-readable tag (informational only; digest is authoritative)
}

​

5.3 Image Registries

1. Protocol registry (registry.cowboylabs.org): Maintained by the Cowboy protocol. Hosts base images and community-vetted images. Images are replicated across multiple mirrors for availability. No authentication required for pulls.
2. Public registries (ghcr.io, docker.io, etc.): Standard public registries. The task definition specifies the full image reference. Runner nodes must have network access to the registry.
3. Private registries: Authenticated registries where the account owner provides pull credentials in the task definition (encrypted with the Runner’s TEE attestation key). Credentials are scoped to the job duration and never persisted by the Runner.

​

5.4 Image Caching

• Cache hit: Image layers already present locally. Container creation starts immediately.
• Cache miss: Layers are pulled from the registry. Pull time depends on image size and network.
• Base images: Protocol base images (§5.5) are pre-pulled and pinned in the cache. They are never evicted.

​

5.5 Base Images

​

6. Runtime Environment

​

6.1 Container Filesystem Layout

/
├── mnt/
│   └── volumes/                    # CIP-9 volume mount root
│       ├── {volume_name_1}/        # FUSE-mounted volume
│       └── {volume_name_2}/        # FUSE-mounted volume
├── tmp/                            # writable tmpfs (scratch space)
├── workspace/                      # writable, default working directory
└── ... (image filesystem layers)   # read-only image content

​

6.2 Environment Variables

COWBOY_TASK_ID=<task_id>                    # CIP-2 task ID
COWBOY_RUNNER_ADDRESS=<runner_address>       # This Runner's address
COWBOY_ACCOUNT_ADDRESS=<account_address>     # Task submitter's account
COWBOY_TIMEOUT_BLOCK=<timeout_block>         # Job deadline (block height)
COWBOY_VOLUME_MOUNTS=<comma-separated>       # e.g., "agent-memory,pipeline"
COWBOY_NETWORK_POLICY=<policy_name>          # e.g., "allowlist", "none"

​

6.3 Entrypoint and Command

1. runtime_config.command (if specified in the task definition) — overrides the image’s ENTRYPOINT and CMD.
2. Image ENTRYPOINT + CMD — the default from the OCI image config.

1. Connects to the model API (Claude, Kimi-K2, etc.) or runs a local model.
2. Provides the model with a system prompt and tools (Read, Write, Bash, etc.).
3. Executes tool calls against the container’s filesystem (including FUSE-mounted volumes).
4. Returns the final result to the Runner engine for onchain submission.

​

6.4 User and Permissions

• Root (uid=0) is prohibited unless runtime_config.allow_root = true and the Runner supports it. Runners MAY reject tasks requesting root.
• FUSE mount points (/mnt/volumes/*) are owned by the container user.
• The container process has no access to the host filesystem, network namespace, or other containers.

​

7. Resource Limits

​

7.1 Resource Declaration

ResourceLimits {
  cpu_millicores:   u32,       // CPU allocation (1000 = 1 core)
  memory_mib:       u32,       // Memory limit in MiB
  scratch_disk_mib: u32,       // Scratch filesystem (overlayfs) limit in MiB
  gpu:              GpuRequest?, // Optional GPU request (see §8)
  max_duration_sec: u32,       // Hard wall-clock timeout (seconds)
}

​

7.2 Enforcement

​

7.3 Resource Classes

​

7.4 Runner Capability Advertising

RunnerProfile {
  ... (existing CIP-2 fields) ...
  # NEW: Resource capabilities
  total_cpu_millicores:  u32,
  total_memory_mib:      u32,
  total_scratch_mib:     u32,
  gpu_devices:           list[GpuDevice],
  supported_platforms:   list[string],      // e.g., ["linux/amd64", "linux/arm64"]
  base_images_cached:    list[bytes32],     // digests of cached base images
}

​

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-Aware Runner Prefiltering

1. The Dispatcher maintains capability indices — filtered sublists of the active runner list grouped by advertised capabilities (GPU vendor/model, platform architecture, memory tier, cached base images).
2. When a task specifies resource requirements (e.g., gpu.count > 0, memory_mib > 16384), the VRF selection runs against the filtered sublist of capable Runners, not the full active list.
3. The start_index calculation from CIP-2 §6 is applied to the filtered list: start_index = hash(vrf_seed + (submission_block - vrf_generation_block)) (mod filtered_list_size).
4. If the filtered list is empty (no capable Runners registered), the task fails immediately at submission with NO_CAPABLE_RUNNERS.

​

9. Network Policy

​

9.1 Default: Isolated

​

9.2 Egress Allowlist

NetworkPolicy {
  mode:           ENUM { NONE, ALLOWLIST },
  egress_rules:   list[EgressRule],
}

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 ingress: Containers cannot listen on ports or accept incoming connections. There are no inbound requests to the container.
• 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

# Example: Task requiring Claude API access
NetworkPolicy(
    mode=ALLOWLIST,
    egress_rules=[
        EgressRule(host="api.anthropic.com", port=443, protocol=TCP),
    ]
)

​

10. Container Lifecycle

​

10.1 Full Lifecycle

​

10.2 Phase Details

1. Image pull: If the image is not cached, pull layers from the registry. If pull fails (registry unavailable, digest mismatch), the Runner calls skip_task().
2. Container creation: Create the container with resource limits (cgroups v2), namespace isolation (PID, mount, network, user), and filesystem layers (overlayfs for scratch).
3. Volume mounts: For each VolumeAttachment in the task definition:
   • Obtain CapToken from the Dispatcher.
   • Obtain volume encryption key (TEE-sealed or threshold-shared, per CIP-9 §9.2).
   • Start the FUSE daemon mounting the volume at /mnt/volumes/{name}/.
   • Start the sync daemon for background push/pull.
   • Fetch the current manifest from Relay Nodes.
4. Environment injection: Set COWBOY_* env vars and task-defined env vars.
5. Start entrypoint: Execute the container’s entrypoint process.

• The entrypoint process runs. For LLM workloads, this is the model harness executing tool calls against the filesystem.
• FUSE-mounted volumes handle reads/writes transparently (CIP-9 §12.1).
• The sync daemon pushes and pulls in the background at the configured interval.
• The Runner engine monitors resource usage and enforces limits.

1. Entrypoint exit: The entrypoint exits with code 0 (success) or non-zero (failure).
2. Final sync: The sync daemon performs a final push of all dirty files to Relay Nodes. This blocks until complete or until a teardown timeout (TEARDOWN_TIMEOUT_SEC, default 30s) is reached.
3. Manifest commit: The Runner commits storage manifests onchain for each attached volume.
4. Result submission: The Runner calls submit_result() on the CIP-2 Runner Submission Contract with the job output.
5. Container destruction: The container, its scratch filesystem, and all in-memory state are destroyed. Volume data persists on Relay Nodes.

​

10.3 Failure Modes

​

10.4 Exit Codes

​

11. onchain State

​

11.1 CIP-2 Task Definition Extension

struct OffchainTask:
    ... (existing CIP-2 fields) ...
    volume_attachments: list[VolumeAttachment]    # CIP-9
    runtime_config:     RuntimeConfig              # CIP-10 (NEW)

RuntimeConfig {
  image:             ImageRef,
  resource_class:    string?,         // e.g., "medium" (shorthand for resource limits)
  resources:         ResourceLimits?, // explicit limits (overrides class if both specified)
  network:           NetworkPolicy,
  gpu:               GpuRequest?,
  env:               map[string, string],  // additional env vars
  command:           list[string]?,   // override entrypoint + cmd
  working_dir:       string?,         // override working directory (default "/workspace")
  allow_root:        bool,            // default false
}

​

11.2 Container Registry Actor

BaseImageEntry {
  name:       string,          // e.g., "cowboy/runner-agent"
  digest:     bytes32,         // current pinned digest
  updated_at: u64,             // block height
  size_bytes: u64,             // total image size
  platforms:  list[string],    // supported architectures
}

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,
}

​

11.3 Key Space

# Base images
key = 0x1 || keccak256(container_registry_address) || 0x00 || keccak256("image" || image_name)
value = rlp(BaseImageEntry)

# Resource classes
key = 0x1 || keccak256(container_registry_address) || 0x00 || keccak256("class" || class_name)
value = rlp(ResourceClassEntry)

​

12. Billing and Fees

​

12.1 Compute Resource Billing

max_compute_cost = (cpu_millicores / 1000) * max_duration_sec * CPU_FEE_PER_CORE_SEC
                 + (memory_mib / 1024) * max_duration_sec * MEMORY_FEE_PER_GIB_SEC
                 + gpu_count * max_duration_sec * GPU_FEE_PER_SEC

actual_compute_cost = (cpu_used_millicores / 1000) * actual_duration_sec * CPU_FEE_PER_CORE_SEC
                    + (peak_memory_mib / 1024) * actual_duration_sec * MEMORY_FEE_PER_GIB_SEC
                    + gpu_count * actual_duration_sec * GPU_FEE_PER_SEC

refund = max_compute_cost - actual_compute_cost

​

12.2 Image Pull Fees

pull_cost = image_size_bytes * EGRESS_FEE_PER_BYTE

​

12.3 Billing Attestations and Dispute Window

BillingAttestation {
  task_id:               uint256,
  cpu_used_millicores:   u32,        // average CPU utilization
  peak_memory_mib:       u32,        // peak memory usage
  actual_duration_sec:   u32,        // wall-clock execution time
  gpu_seconds:           u32,        // GPU time used
  bytes_egressed:        u64,        // network egress bytes
  runner_address:        bytes32,
  tee_signature:         bytes64?,   // TEE attestation signature (if available)
  cgroup_digest:         bytes32,    // BLAKE3 hash of cgroup accounting snapshot
}

​

12.4 Relationship to CIP-3

​

13. Parameters

​

14. Security Considerations

​

14.1 Container Escape

• Namespace isolation: PID, mount, network, user, UTS, IPC namespaces are all isolated.
• Seccomp profile: A restrictive seccomp profile blocks dangerous syscalls (mount, reboot, kexec_load, etc.).
• Capabilities dropped: All Linux capabilities are dropped except a minimal set (CAP_NET_BIND_SERVICE for egress, CAP_FOWNER for FUSE mounts).
• Read-only root: The image filesystem is mounted read-only. Only /tmp, /workspace, and CIP-9 mounts are writable.
• No privileged mode: --privileged is never allowed. Even allow_root=true does not grant host capabilities.
• gVisor/Kata (optional): Runner operators MAY use gVisor (application kernel) or Kata Containers (lightweight VM) for additional isolation. This is an operator choice, not a protocol requirement.

​

14.2 Image Supply Chain

• Digest pinning: Images are always pulled by digest, preventing tag-based supply chain attacks.
• Base image governance: Protocol base images are updated only via governance proposals. Digests are recorded onchain.
• No implicit pulls: The Runner never pulls an image not explicitly specified in the task definition.
• Layer verification: Each layer’s digest is verified on pull per the OCI distribution spec.

​

14.3 Network Exfiltration

• Default deny: No network access unless explicitly allowlisted.
• No wildcards: Allowlist entries must be specific hostnames.
• No DNS exfiltration: DNS resolution happens inside the container but is restricted to resolving allowlisted hosts (Runners SHOULD use a DNS proxy that blocks queries for non-allowlisted domains).
• Bandwidth limits: MAX_EGRESS_BANDWIDTH prevents 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 COWBOY_* vars and task-defined vars.
• 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: In v1, a GPU device is assigned to at most one container at a time (no sharing).

​

15. Implementation Notes

​

15.1 Recommended Runtime Stack

​

15.2 Rootless Operation

​

15.3 Container Creation Time Budget

​

15.4 Logging

• Logs are buffered in memory (max LOG_BUFFER_SIZE, default 10 MiB).
• Logs are available to the task submitter as part of the result payload (if the result_schema requests them).
• Logs are NOT persisted by the Runner after container destruction.
• If the task attaches a CIP-9 volume, the entrypoint can write logs to the volume for durable storage.

​

16. Scope and Future Work

​

16.1 v1 Scope (This CIP)

• OCI-compatible container images with digest pinning.
• Container filesystem isolation with read-only root and writable scratch.
• CIP-9 FUSE volume mounts inside containers.
• Mandatory resource limits (CPU, memory, scratch disk, wall-clock time).
• GPU passthrough (NVIDIA CUDA, AMD ROCm).
• Network isolation with explicit egress allowlists.
• Standard base images for common workloads (agent, Python, ML).
• Container lifecycle integrated with CIP-2 task dispatch.
• Compute resource billing (CPU-sec, memory-sec, GPU-sec).
• onchain Container Registry for base image digests and resource classes.

​

16.2 Explicitly Out of Scope

• Long-running services: v1 containers are ephemeral (bounded by max_duration_sec). Persistent services (web servers, databases) that run indefinitely are a future CIP. CIP-5 timers can be used to re-dispatch periodic jobs.
• Container-to-container networking: Direct communication between containers from different tasks. In v1, coordination happens via CIP-9 shared volumes.
• Custom container runtimes: v1 requires an OCI-compatible runtime. Support for WASM, Firecracker micro-VMs, or other execution models is a future extension.
• Image building onchain: v1 images are built externally and pushed to registries. A decentralized image build service is a future CIP.
• Trusted builder attestation: Verifying that an image was built from a specific source repository (e.g., via Sigstore). This is a future supply chain security enhancement.
• Spot/preemptible execution: v1 has no concept of interruptible, lower-cost execution tiers. This is a future pricing extension.
• Multi-container pods: v1 runs a single container per task. Sidecar patterns (e.g., running a local model alongside a tool-calling harness) require the entrypoint to manage sub-processes internally or be combined into a single image.

​

Appendix A: Examples

​

A.1 LLM Tool-Calling Agent (Claude)

submit_task(
    task_definition=encode_task({
        "model": "claude-sonnet",
        "system": "You are a research assistant. Your notes are in /mnt/volumes/notes/.",
        "prompt": "Research the latest developments in fusion energy. Update your notes.",
    }),
    runtime_config=RuntimeConfig(
        image=ImageRef(
            registry="registry.cowboylabs.org",
            repository="cowboy/runner-agent",
            digest="sha256:a1b2c3...",
        ),
        resource_class="medium",
        network=NetworkPolicy(
            mode=ALLOWLIST,
            egress_rules=[
                EgressRule(host="api.anthropic.com", port=443),
            ],
        ),
        env={"ANTHROPIC_API_KEY": "<encrypted>"},
    ),
    volume_attachments=[
        VolumeAttachment(
            volume_name="notes",
            access_mode=READ_WRITE,
            mount=True,
            max_bytes=100_000_000,
        ),
    ],
    num_runners=1,
    timeout_blocks=500,
    ...
)

1. Runner selected via VRF
2. Image "cowboy/runner-agent" already cached (base image) → skip pull
3. Create container:
   - cgroups: cpu.max=200000/100000, memory.max=2G
   - namespaces: new PID, mount, net, user
   - network: iptables ALLOW api.anthropic.com:443, DROP all else
4. FUSE mount /mnt/volumes/notes/ (CIP-9 key delivery, manifest fetch)
5. Start entrypoint (model harness)

1. Bash("ls /mnt/volumes/notes/")
   → research/  summaries/  sources.json

2. Read("/mnt/volumes/notes/summaries/fusion-2026-02.md")
   → [last month's fusion research summary]

3. [Claude searches the web via allowed API, analyzes findings]

4. Write("/mnt/volumes/notes/research/fusion-2026-03-07.md", new_findings)
   → Written to local tmpfs, sync daemon pushes to Relay Nodes

5. Write("/mnt/volumes/notes/summaries/fusion-2026-03.md", updated_summary)

6. Bash("wc -l /mnt/volumes/notes/research/*.md")
   → 15 research notes total

7. Entrypoint exits (code 0)
8. Final sync: 2 dirty files pushed to Relay Nodes
9. Manifest committed onchain
10. submit_result() with summary of work done
11. Container destroyed. Volume data persists.

​

A.2 GPU ML Inference

submit_task(
    task_definition=encode_task({
        "action": "inference",
        "model_path": "models/classifier-v3.pt",
        "input_dir": "batch-2026-03-07/",
    }),
    runtime_config=RuntimeConfig(
        image=ImageRef(
            registry="registry.cowboylabs.org",
            repository="cowboy/runner-ml",
            digest="sha256:d4e5f6...",
        ),
        resources=ResourceLimits(
            cpu_millicores=4000,
            memory_mib=16384,
            scratch_disk_mib=51200,
            max_duration_sec=1800,
            gpu=GpuRequest(count=1, min_vram_mib=24576, compute_cap="8.0", driver="cuda"),
        ),
        network=NetworkPolicy(mode=NONE),
    ),
    volume_attachments=[
        VolumeAttachment(volume_name="models", access_mode=READ_WRITE, mount=True,
                         max_bytes=5_000_000_000),
        VolumeAttachment(volume_name="predictions", access_mode=WRITE_ONLY, mount=True,
                         path_prefix="batch-2026-03-07/", max_bytes=1_000_000_000),
    ],
    ...
)

import torch

# Volumes are just directories
model = torch.load("/mnt/volumes/models/classifier-v3.pt")
model.cuda()

for batch_file in Path("/mnt/volumes/models/batch-2026-03-07/").glob("*.pt"):
    inputs = torch.load(batch_file).cuda()
    preds = model(inputs)
    torch.save(preds, f"/mnt/volumes/predictions/{batch_file.stem}_pred.pt")

​

A.3 Agent Swarm with Custom Image

submit_task(
    task_definition=encode_task({
        "model": "kimi-k2",
        "system": "You are a financial analyst. Use the tools in /usr/local/bin/ to analyze data. Write reports to /mnt/volumes/reports/.",
        "prompt": f"Analyze {company}'s Q4 earnings. Use fin-scrape and fin-analyze tools.",
    }),
    runtime_config=RuntimeConfig(
        image=ImageRef(
            registry="ghcr.io",
            repository="acme-finance/analyst-runner",
            digest="sha256:789abc...",
        ),
        resource_class="medium",
        network=NetworkPolicy(
            mode=ALLOWLIST,
            egress_rules=[
                EgressRule(host="api.moonshot.cn", port=443),
                EgressRule(host="api.sec.gov", port=443),
                EgressRule(host="finance.yahoo.com", port=443),
            ],
        ),
    ),
    volume_attachments=[
        VolumeAttachment(volume_name="reports", access_mode=WRITE_ONLY, mount=True,
                         path_prefix=f"analyst-{i}/", max_bytes=50_000_000),
    ],
    ...
)

1. Bash("fin-scrape --source sec-edgar --ticker AAPL --filing 10-Q")
   → Scrapes SEC filing (allowed via egress rule)

2. Bash("fin-analyze --input /tmp/aapl-10q.json --metrics revenue,margins,guidance")
   → Custom tool in the image analyzes the filing

3. Write("/mnt/volumes/reports/aapl-q4-analysis.md", analysis)
   → Written to agent-2/aapl-q4-analysis.md (prefix-scoped)

4. Write("/mnt/volumes/reports/aapl-q4-data.json", structured_data)

​

Appendix B: 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 (loopback only)
• 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

​

Part II — v2 Revision (canonical; concrete addresses + fee plumbing)

​

0. What this revision does

​

1. Container Registry actor address: 0x13

​

2. Container fee distribution via SettlementConfig

ContainerSettlementConfig {
  runner_percent:    8900,   // 89%
  treasury_percent:   100,   // 1%
  burn_percent:      1000,   // 10%
}

​

3. Three independent off-chain billing flows (clarification)

​

4. BillingAttestation reuses CIP-23 CompositeAttestation

pub tee_signature: Option<CompositeAttestation>,    // per CIP-23 §3.4

​

5. Container Registry instructions (opcodes 160–164)

​

6. Millisecond billing granularity

d_ms                = max(actual_duration_ms, 100)
actual_compute_cost = cpu_used_millicores · d_ms · CPU_FEE_PER_CORE_SEC / 1000 / 1000   // /1000 ms→s, /1000 millicores→cores
                    + peak_memory_mib     · d_ms · MEMORY_FEE_PER_GIB_SEC / 1024 / 1000
                    + gpu_seconds         · GPU_FEE_PER_SEC

​

7. Enforced-cgroup Standard sandbox + real metering

​

9. Governance-tunable fee rates + escrow-time snapshot

​

10. Deferred settlement + billing disputes (optimistic fallback)

​

11. Registry-backed digest images (supersedes v1 §5.2 / §14.2 addressing)

• ImageRef is either a protocol BaseImage enum key or a bare 32-byte digest. A digest ref is admissible iff registered at 0x13 (RegisterBaseImage writes a digest→name index; unregistered digests reject at submit — there is no trust path from a bare digest to a provisioned image).
• The image digest is blake3 over a canonical rootfs walk — sorted directory entries, each contributing relative-path ‖ NUL ‖ file-mode ‖ NUL ‖ (content | symlink-target) with directories contributing path+mode only. runner-node image-digest <rootfs> prints it; cowboy container register-image --digest records it on-chain.
• The runner serves a digest image from <image_root>/<digest-hex>/rootfs only after re-hashing the tree and matching the claimed digest — a tampered or mis-provisioned rootfs never runs.
• Runners advertise serves_registered_images in their container capability; the dispatcher’s Filter 3.5 matches digest jobs only to such runners.
• Clients resolve image names to digests via the exact-key storage read RPC (GET /actors/{addr}/storage/value?key= — registry keys exceed 32 bytes and are hash-stored, invisible to prefix scans).

​

12. Strong isolation tier (gVisor)

• Selection: the executor picks the lowest tier satisfying the job’s min_isolation_tier, so Standard jobs never consume gVisor capacity; the dispatcher’s Filter 3.5 prefilters on advertised tiers, and a runner advertises Strong only when the runsc binary is actually usable (fail-closed by construction).
• Rootless runsc invocation: --network=none (the egress-deny model as a flag), --ignore-cgroups (runsc otherwise creates a default sandbox cgroup rootless cannot), --rootless when unprivileged, and no OCI user namespace in the bundle — the sentry is the isolation boundary; a spec-supplied userns kills the gofer re-exec.
• Billing is unmetered under rootless runsc: it cannot program host cgroups, so the attestation self-reports metered = false and the §4 trust gate charges the full escrow — conservative by construction. gVisor resource caps + metering arrive with rootful deployments.

​

13. Fail-closed capability advertising

​

14. Backwards compatibility

​

Persistent Workloads

​

1. Scope

​

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 Part I §9.

​

3. Registry record

system:container_registry:workload:<workload_id>

WorkloadRecord {
  workload_id:      [u8; 32],
  generation:       u64,
  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>,
}

​

3.1 Enum tags

​

3.2 Instructions

​

3.3 Registration and updates

• generation = 1
• observed_status = Provisioning
• observed_at = current_block

​

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.

​

4. Lifecycle and health

​

4.1 Route eligibility

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

​

4.2 Supervisor behavior

​

4.3 Stop and deregistration

• observed_status = Stopped; or
• current_block >= saturating_add(observed_at, WORKLOAD_LEASE_TTL_BLOCKS + WORKLOAD_STALE_CLEANUP_GRACE_BLOCKS).

​

5. Volume mounts

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

• the volume MUST exist;
• 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.

​

6. Billing

​

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 §3.

​

8. Activation

1. merge the canonical protocol types and opcodes;
2. advance the node protocol pin and activate the 0x13 handlers;
3. advance the runner protocol pin and deploy the supervisor and signed reporter;
4. deploy proof-checked Gateway workload resolution and streaming routes; and
5. configure and register the operator-managed workload.

register → report Running → relay a route → stop and drain → 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.

​

9. Backwards compatibility