Skip to content

Bootstrap quick start

Use this page for the common remote fellow onboarding paths. Use Bootstrap contract for the full contract and endpoint reference.

Local development

For local work, start a leader and fellows directly:

on your own machine
swarm start-cluster --fellows 2
swarm fellows

Remote fellow with curl

Run this on the remote host after the leader is reachable from that host:

on the remote GPU machine
curl -fsSL http://<leader>:8080/api/v1/bootstrap/fellow.sh | bash -s -- \
  --leader-url http://<leader>:8080

Add --dry-run first to inspect what the script would do.

On macOS, the bootstrap script prefers python3.13, python3.12, or python3.11 when present, then falls back to any Python 3.11+ interpreter. The PyTorch runtime (requirements-runtime.txt) is installed best-effort there, so a host can still join and appear in the swarm even when PyPI has no matching torch wheel for that interpreter. Training jobs on that host still need a working torch install.

Join session with token

Create a session from /ops/join-v2 or with the API:

from anywhere that can reach the leader
curl -sX POST http://<leader>:8080/api/v1/bootstrap/join-sessions \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 3600}'

Then run the generated command with --session-id and --token.

Docker Compose tunnel

For a temporary public test URL:

on the leader host
docker compose --profile local-fellow --profile tunnel up -d --build
docker compose --profile tunnel logs -f tunnel

Use the printed /ops/join-v2 URL to generate remote join commands.

Top troubleshooting checks

  • Leader unreachable: verify the remote host can reach SWARM_LEADER_URL.
  • Ports busy: set --zmq-act-port and --zmq-grad-port, or rely on auto fallback.
  • Install fails: ensure Python 3.11+, venv/pip, and network access to package indexes.
  • macOS joins but training fails: install a Python version with a matching PyTorch wheel, then rerun the bootstrap or fellow update --yes.
  • Fellow stale: use swarm fellows and swarm release --fellow-id <id> before retrying.