Cargos

Cargo architecture — runtime types, Island requirements, trust levels, pricing, and the I/O protocol

Cargos

A Cargo is a signed, versioned unit of computation that runs on Islands. “Cargo” is the Archipelag.io term for a workload blueprint — it defines what to execute, what resources are needed, how much it costs, and what security constraints apply. The coordinator matches jobs to capable Islands, and the Island software executes the Cargo in a sandbox.

Runtime Types

Every Cargo has a runtime_type that determines how it is executed on the Island:

Platform Compatibility

The coordinator checks platform compatibility during Island selection — a coreml Cargo will never be dispatched to a Linux Island, and an onnx Cargo won’t go to an Island that doesn’t report "onnx" in its supported_runtimes.

Model Resolution

Native runtimes (llmcpp, onnx, diffusers) use HuggingFace URIs to reference models:

hf://TheBloke/Mistral-7B-Instruct-v0.2-GGUF          → auto-discovers best .gguf file
hf://sentence-transformers/all-MiniLM-L6-v2           → auto-discovers model.onnx
hf://runwayml/stable-diffusion-v1-5                   → downloads pipeline components
hf://TheBloke/Mistral-7B-GGUF:mistral-7b.Q4_K_M.gguf → specific file

Models are cached on the Island at ~/.island/model-cache/ with LRU eviction. The Island preloads a starter set of models at startup based on hardware capabilities.

Island Requirements Matching

Cargos declare minimum hardware requirements. The coordinator only dispatches jobs to Islands that meet all requirements:

Job submitted (workload: llm-chat)
        │
        ▼
  Requirements: 6GB VRAM, 4 CPU, 8GB RAM
        │
        ▼
  Island selection query
        │
        ├── Filter: meets requirements?
        ├── Prefer: same region
        ├── Prefer: warm container (already cached)
        ├── Prefer: high reputation score
        ├── Prefer: low active_jobs count
        │
        ▼
  Best Island selected ──► Job dispatched

Islands that have recently run the same Cargo get a placement bonus — the container image is already cached, eliminating pull latency.

Trust Levels

Every Cargo has a trust level (0-3) that determines the security posture applied during execution:

Sandbox Tier Mapping

Each sandbox tier applies resource limits and a seccomp syscall filter:

Pricing Models

Cargos support three pricing models, used individually or in combination:

The coordinator charges consumers atomically using UPDATE ... WHERE credits >= price to prevent race conditions. If a consumer doesn’t have enough credits, the job is rejected before dispatch.

Island Payouts

When an Island completes a job, the platform calculates the Island payout:

1. Base payout = Cargo price - 20% platform fee
2. Hardware tier multiplier applied (higher-spec hardware earns more)
3. Payout only processed if the Island meets the karma monetization threshold (+10 karma)

Islands below the karma threshold still execute jobs (to build karma) but do not receive payouts.

I/O Protocol

Cargos receive input as JSON on stdin and emit output as JSON Lines on stdout. This protocol is consistent across all runtime types.

Input

The coordinator sends a JSON object on stdin when the container starts. The schema depends on the Cargo type:

LLM Chat:

{
  "prompt": "Explain quantum computing",
  "max_tokens": 512,
  "temperature": 0.7
}

Image Generation:

{
  "prompt": "A sunset over mountains",
  "width": 512,
  "height": 512,
  "steps": 20,
  "seed": 42
}

Output

Cargos emit JSON Lines on stdout. Each line is a message with a type field:

Cargo stdout
        │
        ▼
  Agent parses each JSON line
        │
        ├── token ──► NATS host.{id}.output ──► Coordinator ──► WebSocket ──► User
        ├── progress ──► NATS host.{id}.progress ──► Coordinator ──► User
        ├── image ──► NATS host.{id}.image ──► Coordinator ──► User
        ├── done ──► NATS host.{id}.status (succeeded)
        └── error ──► NATS host.{id}.status (failed)

Stderr is captured for debugging but not streamed to consumers.

Cargo Catalog

The coordinator maintains a catalog of approved Cargos. Each Cargo entry includes:

Signature Requirements

Cargos at trust level 2 or higher must be signed using cosign (part of the Sigstore project). The signature fields tracked are:

• cosign_signature — The signature value
• cosign_certificate — The signing certificate
• cosign_log_index — Rekor transparency log entry index
• signature_verified_at — When verification last succeeded
• signature_verified_by — Who performed the verification

The Island software verifies signatures before execution using public keys fetched from the coordinator.

Reputation Tracking

Each Cargo tracks its execution history:

• reputation_score — Composite quality score (0.0 to 1.0)
• total_jobs, successful_jobs, failed_jobs — Raw counts
• avg_execution_time_ms — Average completion time

The ReputationWorker runs hourly to auto-suspend Cargos with reputation below 0.5 or success rate below 90% (after 100+ jobs), and flags Cargos with excessive complaints for manual review.

Next Steps

{% end %}