Skip to content

Running Agora#

Start the node#

git clone https://github.com/PluralisResearch/agora-test
cd agora-test
python3 agora_cli.py

On first run, the CLI prompts you interactively for:

  • Your HuggingFace token
  • (Optional) email address
  • GPU ID if you have multiple GPUs
  • Whether to run inside Docker (recommended)
  • Host port and announce port. Both default to 49200 + gpu_id, differing only if the port is remapped externally

Your answers are saved to a config file. On subsequent runs of python3 agora_cli.py, the saved values are reused; running the command again resumes from the saved configuration.

Using Claude Code? Run /agora-join

The repo includes a Claude Code skill at .claude/skills/agora-join that covers token entry, port mapping, Docker vs native, multi-GPU launch, and startup monitoring. Type /agora-join in Claude Code from the repo root to use it instead of the steps below.

Docker vs Native#

Docker is recommended: it pins the exact Python version and dependencies, isolating the node from the system Python.

If Docker is not available, native install works but requires Python 3.13 exactly with pip >= 25.3: older pip cannot apply the --build-constraint used by the install.

python3 -m pip install --upgrade 'pip>=25.3'

Blackwell cards need the CUDA 12.8 PyTorch build

The RTX 5090, RTX PRO 4500, and RTX PRO 6000 require PyTorch built against CUDA 12.8. agora_cli.py installs that build for you; if you are setting the environment up yourself, or already have another PyTorch in it, install it explicitly:

pip install torch==2.11.0 \
  --index-url https://download.pytorch.org/whl/cu128

Keep the node running after you log out

On any remote SSH machine, run inside tmux or screen so the node does not terminate when your session ends:

tmux new -s agora
python3 agora_cli.py
# Ctrl-b d to detach; `tmux attach -t agora` to reattach

Required on RunPod: Docker-in-Docker is impractical there, so use the native install inside tmux. See Cloud Options → RunPod.

Expected startup output#

Startup runs through four phases. The log signatures below distinguish a healthy startup from one that has stalled in an earlier phase.

1. Network check and weight download#

[NETWORK]  Running internet speed test...
[DOWNLOAD] Downloading model weights...
[DOWNLOAD] Model weights downloaded. Waiting for authorization...

If the speed test fails or the download is too slow, your node is dropped from the queue. Check your connection meets the 200 Mbps down / 100 Mbps up minimum.

2. Authorization queue#

[AUTH]     Authorization queue: position 2, estimated wait: 1m
[AUTH]     Access granted for your_user

During high demand, the queue can be long. If your node times out waiting, restart; it will re-enter the queue.

3. Sync (if joining an active run)#

[SYNC] Synchronising weights with peers. Node won't process batches in this phase.
[SYNC] This phase will last 50 steps (until local epoch <E>).
[SYNC] Synchronising optimizer state. Node is now processing batches, but doesn't contribute to weight averaging yet.
[SYNC] This phase will last 20 steps (until local epoch <E>).
[SYNC] Sync complete. Node is now fully contributing to training.

Sync runs in two phases. The first synchronizes your weights with other workers in your stage; the second warms up your local optimizer state. Expect a runtime of several hours end-to-end. Compute points start accruing in the second phase; presence points credit from the moment your peer joins. See Contributor Join Flow for the detailed description.

4. Training#

[SERVER]   Training started
[TRAINING] Training step 1
[PROGRESS] Processed 51 batches in the last 60s
[PROGRESS]   Forward pass: 28 batches
[PROGRESS]   Backward pass: 23 batches

Healthy signal: [PROGRESS] Processed [N] batches should update every 60 seconds. As long as that line continues to appear, your node is actively contributing to the swarm.

Detailed logs are written to logs/server_gpu<ID>.log.

Verifying your contribution#

Once training starts, your participation appears on the Dashboard. Look for your node by HuggingFace username.

Stopping the node#

  • Native: press Ctrl + C in the terminal running the CLI
  • Docker: docker stop <container_name> && docker rm <container_name>

Rejoining is available at any time. Contribution history is preserved across restarts as long as the same private_gpu<ID>.key file is kept (see Advanced → Identity key).

Troubleshooting#

  • Error messages at startup: check Setup Guides, which cover auth failures, port tests, CUDA issues, and more
  • Node joined but is not processing batches: usually a network issue; verify port 49200 is reachable from outside
  • Ask for help: Zulip

Advanced#

  • Multiple GPUs, CLI flags, and manual installation → Advanced