Island Setup Guide

Set up your machine as an Island to contribute compute on the Archipelag.io network

Island Setup Guide

Turn your idle hardware into a compute node on the Archipelag.io network.

Requirements

• OS: Linux (x86_64 or aarch64), macOS (Apple Silicon or Intel), or Windows (x86_64)
• RAM: 4GB minimum
• Network: Stable internet connection (outbound access to port 4222)
• Optional: Docker (for container Cargos) or NVIDIA GPU (for GPU Cargos)

Without Docker, the Island runs in WASM-only mode.

Quick Install

Windows without WSL

If you prefer not to use WSL, you can install natively with PowerShell:

irm https://archipelag.io/install.ps1 | iex

This will:

1. Download the latest Island binary for Windows
2. Create a default config at %USERPROFILE%\.island\config.toml
3. Add %USERPROFILE%\.island\bin to your user PATH
4. Suggest WSL if it’s available (for the best experience)

Then open a new PowerShell window and run:

island --agent --config "$env:USERPROFILE\.island\config.toml"

{% end %}

Manual Install (Linux / macOS)

If you prefer not to pipe to shell:

# Download the binary for your platform
# Available: linux-x86_64, linux-aarch64, darwin-x86_64, darwin-aarch64
curl -fsSL https://github.com/archipelag-io/node-agent/releases/latest/download/island-VERSION-PLATFORM -o island
chmod +x island
mv island ~/.island/bin/

Check the releases page for the latest version and available binaries. Each binary has a corresponding .sig signature file and there is a checksums-VERSION.sha256 file for verification.

Configuration

The installer creates a config file at ~/.island/config.toml:

# Archipelag.io Island Configuration

[host]
name = "my-machine"    # Friendly name for this Island
region = "auto"        # Auto-detect region, or set manually (e.g. "eu-west")

[coordinator]
nats_url = "tls://island:PASSWORD@sail.archipelag.io:4222"
api_url = "https://app.archipelag.io"   # For demand-driven preloading

[workload]
llm_chat_image = "ghcr.io/archipelag-io/llm-chat:latest"
gpu_devices = []       # e.g. ["0"] or ["0", "1"] for specific GPUs

[workload.resource_limits]
memory_mb = 4096       # Max memory per Cargo container
read_only_rootfs = true
tmpfs_size_mb = 256
network_disabled = true

[cache]
enable_preload = false
max_cached_images = 10

[model_cache]
max_cache_gb = 20          # Max disk for ML models (GGUF, ONNX, etc.)
# cache_dir = "/data/models"  # Optional: custom cache directory

[preload]
enabled = true             # Auto-preload models based on hardware
# models = ["hf://TheBloke/Mistral-7B-Instruct-v0.2-GGUF"]  # Override auto-selection

[pricing]
# default_price = "1.0"           # Default asking price for all Cargos (credits/job)
# [pricing.workloads]             # Per-Cargo overrides
# "gguf-mistral-7b" = "2.0"
# "gguf-qwen3.5-4b" = "0.80"

[signing]
enabled = true
require_signature = false

[registry]
enabled = true
require_digest = false

The nats_url is pre-configured by the installer. The connection uses TLS encryption to sail.archipelag.io:4222.

Key Settings

Start the Island

# After install, reload your shell
source ~/.zshrc   # or ~/.bashrc

# Start the Island
island --agent --config ~/.island/config.toml

You should see output like:

INFO Starting island v0.4.0
INFO Loaded configuration from /home/user/.island/config.toml
INFO Container cache disabled (no Docker)
INFO Model cache initialized: 0 models in /home/user/.island/model-cache
INFO Connected to NATS at nats://127.0.0.1:4222
INFO Detected capabilities: 12 CPU cores, 32768 MB RAM, GPU: None
INFO Hardware tier: 32768MB RAM, 0MB VRAM — 2 models selected for preload
INFO   Preload: Qwen3.5-0.8B (GGUF, 600MB)
INFO   Preload: Mistral 7B Instruct (GGUF, 4.4GB)
INFO Registered Island df1745b5-...
INFO ========================================
INFO        ISLAND PAIRING CODE: 9RUGCQ
INFO ========================================
INFO Subscribed to job assignments via JetStream
INFO Agent running. Waiting for jobs...
INFO Preloading: Qwen3.5-0.8B (GGUF, 600MB)
INFO Downloading model: hf://Qwen/Qwen3.5-0.8B-GGUF (605 MB)
INFO Download progress: 50%
INFO Model preloading complete
INFO Detected capabilities: 10 CPU cores, 16384 MB RAM, GPU: None
INFO Registered Island 20352697-... with coordinator
INFO Subscribed to job assignments via JetStream
INFO Agent running. Waiting for jobs...

Demand-Driven Preloading

Your Island automatically adapts to what Consumers need. Two mechanisms work together:

Push (instant): When a Consumer requests a model and no Island has it ready, the coordinator sends your Island a preload signal if your hardware can handle it. Your Island downloads the model in the background and becomes eligible for future jobs immediately.

Pull (periodic): Every 15 minutes, your Island checks which Cargos are in highest demand and preloads the top models it can serve. This keeps your Island aligned with market demand without manual intervention.

Both require coordinator.api_url in your config (see above). You’ll see log messages like:

INFO Preload recommendation: gguf-qwen3.5-4b (demand: 3)
INFO Preloading recommended model: gguf-qwen3.5-4b
INFO Preloaded: gguf-qwen3.5-4b -> /home/user/.island/model-cache/.../Qwen3.5-4B-Q4_K_M.gguf

Models are cached in ~/.island/model-cache/ and managed by the LRU cache (oldest models evicted when model_cache.max_cache_gb is exceeded). You don’t need to manually manage which models to host — your Island figures it out from network demand.

The demand score uses a weighted formula across multiple time windows:

Setting Your Asking Prices

By default, your Island earns the Cargo’s default price_per_job for each completed job. To charge a custom rate, set asking prices in your config.toml:

[pricing]
default_price = "1.0"             # Fallback for Cargos without a specific price

[pricing.workloads]
"gguf-mistral-7b" = "2.0"        # Mistral 7B: 2 credits/job
"gguf-qwen3.5-4b" = "0.80"       # Qwen 3.5 4B: 0.80 credits/job
"image-gen" = "5.0"              # Image generation: 5 credits/job

Your asking prices are sent to the coordinator with each heartbeat. The coordinator uses them to match your Island with Consumers:

1. A Consumer submits a job (with an optional bid price, or they accept the market rate)
2. The coordinator finds capable Islands and checks their asking prices
3. If a Consumer’s bid covers your asking price, the job is dispatched to you
4. You earn your asking price (not the Consumer’s bid — it’s a first-price auction)

If you don’t set asking prices, the Cargo’s default price is used — you still earn credits for every completed job.

Browser Islands can set asking prices per Cargo directly from the Island dashboard at app.archipelag.io/host — click the price next to any cached Cargo to edit it.

Mobile Islands can set prices via the set_asking_prices channel message (see the mobile SDK documentation).

You can view current market rates and price history on the Compute Exchange.

Running as a Service

To keep the Island running in the background:

Linux (systemd):

cat > ~/.config/systemd/user/island.service << 'EOF'
[Unit]
Description=Archipelag.io Island
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=%h/.island/bin/island --agent --config %h/.island/config.toml
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now island

macOS (launchd):

cat > ~/Library/LaunchAgents/io.archipelag.island.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>io.archipelag.island</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOU/.island/bin/island</string>
        <string>--agent</string>
        <string>--config</string>
        <string>/Users/YOU/.island/config.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOU/.island/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOU/.island/logs/stderr.log</string>
</dict>
</plist>
EOF

# Replace YOUR with your username, then:
launchctl load ~/Library/LaunchAgents/io.archipelag.island.plist

Windows (Task Scheduler):

Open PowerShell as Administrator and run:

$action = New-ScheduledTaskAction `
    -Execute "$env:USERPROFILE\.island\bin\island.exe" `
    -Argument "--agent --config `"$env:USERPROFILE\.island\config.toml`""

$trigger = New-ScheduledTaskTrigger -AtLogon

$settings = New-ScheduledTaskSettingsSet `
    -AllowStartIfOnBatteries `
    -DontStopIfGoingOnBatteries `
    -RestartCount 3 `
    -RestartInterval (New-TimeSpan -Minutes 1)

Register-ScheduledTask -TaskName "Archipelag.io Island" `
    -Action $action -Trigger $trigger -Settings $settings `
    -Description "Archipelag.io Island compute agent"

To stop or remove:

Stop-ScheduledTask -TaskName "Archipelag.io Island"
Unregister-ScheduledTask -TaskName "Archipelag.io Island" -Confirm:$false

Docker Setup

Docker is optional. Without it, the Island only runs WASM Cargos.

macOS: The installer uses Colima (lightweight, free) instead of Docker Desktop:

brew install colima docker
colima start --cpu 2 --memory 4

Linux (including WSL): Install Docker from your package manager:

sudo apt install docker.io
sudo systemctl start docker
sudo usermod -aG docker $USER   # then log out and back in

Windows (native): Install Docker Desktop and make sure the WSL 2 backend is enabled (this is the default). Docker Desktop is free for personal use.

Network & Security

The Island makes outbound-only connections:

• TLS to sail.archipelag.io:4222 — the NATS message bus (encrypted, authenticated)
• HTTPS to container registries — to pull approved Cargo images

No inbound ports need to be opened. The Island never accepts incoming connections.

What runs on your machine

Only network-approved, signed container images or WASM modules. Consumers cannot run arbitrary code. All Cargos run in sandboxed environments with:

• Read-only root filesystem
• No network access (by default)
• Memory and CPU limits
• Seccomp security profiles

Logging

# Default: human-readable output
island --agent --config ~/.island/config.toml

# JSON output (for log aggregation)
ARCHIPELAG_LOG_JSON=true island --agent --config ~/.island/config.toml

# Verbose logging
RUST_LOG=debug island --agent --config ~/.island/config.toml

# Trace a specific module
RUST_LOG=archipelag_agent::nats=trace island --agent --config ~/.island/config.toml

Troubleshooting

“Docker not available” warning

This is non-fatal. The Island runs in WASM-only mode. Install Docker if you want to run container Cargos.

“Failed to connect to NATS”

1. Check your internet connection
2. Verify sail.archipelag.io resolves: dig sail.archipelag.io
3. Check port 4222 is reachable: nc -zv sail.archipelag.io 4222
4. Verify the nats_url in your config file has the correct credentials

“authorization violation” in logs

The NATS credentials in your config may be wrong. Re-run the installer to get a fresh config, or check that nats_url matches the expected format.

macOS Gatekeeper blocks the binary

xattr -d com.apple.quarantine ~/.island/bin/island

Or go to System Settings > Privacy & Security and click “Allow Anyway”.

Windows: “irm” or “curl” install doesn’t work

The install script (install.sh) is a Linux/macOS shell script — it won’t run in PowerShell or CMD. On Windows, either use WSL (recommended) or follow the native Windows steps above to download the binary manually.

Windows: WSL says “wsl –install” is not recognized

You may be running an older version of Windows 10. WSL 2 requires Windows 10 version 2004 or later (build 19041+). Check your version by pressing Win+R, typing winver, and pressing Enter. If you’re below build 19041, update Windows first.

Agent exits immediately

Check that --agent flag is passed. Without it, the binary just prints help and exits.