Components

Deep dive into the Archipelag.io system components

System Components

Archipelag.io consists of several key components that work together to provide distributed compute.

Coordinator

The central control plane, built with Elixir/Phoenix.

Responsibilities

User authentication and API key management
Job submission and placement
Island registry and health tracking
Billing and credit management
Real-time streaming via WebSocket

Key Features

Placement Algorithm: Selects optimal Islands based on:
- Warm containers (cached images)
- Regional proximity
- Job affinity
- Island load and reputation
Karma System: Islands earn reputation through successful jobs
Trust Levels: Cargos have sandboxing tiers (0-3)

Tech Stack

Elixir/Phoenix 1.8
PostgreSQL for persistence
NATS for Island communication
Oban for background jobs

Island Software

The Rust-based daemon running on Islands.

Responsibilities

Connect to coordinator via NATS
Report hardware capabilities
Execute assigned Cargos
Stream output back to coordinator
Manage container and WASM runtimes

Supported Runtimes

Docker Containers: GPU-accelerated Cargos
WebAssembly: Lightweight sandboxed execution

Security Features

Read-only root filesystem
Network isolation
Memory/CPU limits
Image signature verification
Fuel-based WASM limits

Cargos

Pre-built compute tasks that run on Islands.

Available Types

{% tab(name="LLM") %} **llm-chat**: Large language model inference using llama.cpp - Model: Mistral 7B Q4_K_M - Requirements: 8GB+ GPU VRAM - Performance: 30-50 tokens/sec on RTX 3080

**sd-diffusers**: Stable Diffusion image generation - Supports: SD 1.5 (4GB), SDXL (8GB), SDXL+Refiner (12GB) - Output: 512x512 to 1024x1024 - Features: xformers, FP16, torch.compile

**video-transcode**: FFmpeg-based video processing - Formats: MP4, WebM, MKV, MOV, GIF - Codecs: H.264, H.265, VP9, AV1 - GPU acceleration via NVENC

Lightweight data processing modules: - `wasm-json`: JSON queries/transforms - `wasm-hash`: SHA256, MD5, BLAKE3 - `wasm-compress`: gzip, brotli - `wasm-qrcode`: QR code generation

{% end %}

I/O Protocol

All Cargos use JSON lines for communication:

// Input (stdin)
{"prompt": "Hello", "max_tokens": 100}

// Output (stdout, one JSON per line)
{"type": "status", "message": "loading model"}
{"type": "token", "content": "Hello"}
{"type": "done", "usage": {"completion_tokens": 42}}

Mobile Agents

Native apps that contribute mobile device compute.

iOS Agent

Runtimes: WASM, CoreML
Hardware: A14+ Neural Engine
Preconditions: Charging, WiFi, cool temperature

Android Agent

Runtimes: WASM (Chicory), ONNX
Hardware: Snapdragon NPU/NNAPI
Preconditions: Charging, WiFi, cool temperature

Both agents implement strict precondition checking to:

Preserve battery health
Prevent overheating
Ensure reliable connectivity

Message Fabric (NATS)

JetStream-enabled message broker connecting all components.

Topics

Topic	Direction	Purpose
`coordinator.hosts.register`	Agent → Coordinator	Island registration
`host.{id}.heartbeat`	Agent → Coordinator	Health updates
`host.{id}.jobs`	Coordinator → Agent	Job dispatch
`host.{id}.output`	Agent → Coordinator	Streaming output
`host.{id}.status`	Agent → Coordinator	Job status

Features

Persistent streams for reliability
Auto-reconnect
At-least-once delivery
Message replay for recovery

Data Flow

sequenceDiagram
    participant U as User
    participant C as Coordinator
    participant N as NATS
    participant H as Island
    participant W as Cargo

    U->>C: POST /jobs
    C->>C: Find best Island
    C->>N: Publish job
    N->>H: Deliver job
    H->>W: Execute
    W-->>H: Stream output
    H-->>N: Publish chunks
    N-->>C: Deliver chunks
    C-->>U: WebSocket stream
    H->>N: Job complete
    N->>C: Status update
    C->>C: Bill user