Bootstrap Quick Start¶

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

Local Development¶

For local work, start a leader and fellows directly:

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:

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. TensorFlow/Keras installation is best-effort on macOS so a host can still join as a control-plane fellow even when PyPI has no TensorFlow wheel for that exact Python version. Training jobs still require a compatible TensorFlow installation on that host.

Join Session With Token¶

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

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:

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 TensorFlow-compatible Python/TensorFlow pair locally, then rerun the bootstrap or fellow update --yes.
Fellow stale: use swarm fellows and swarm release --fellow-id <id> before retrying.