# Agora Client The quick-start has three sections: 1. **[Requirements](/content/docs/quick-start/requirements/index.html)**: hardware, OS, network, and the required HuggingFace token 2. **[Running Agora](/content/docs/quick-start/run/index.html)**: the full run flow, what logs to expect, how to stop and restart 3. **[Advanced](/content/docs/quick-start/advanced/index.html)**: multi-GPU, CLI flags, manual installation, caveats See [Cloud Options](/content/docs/quick-start/setup-guides/cloud/index.html) for running Agora on AWS, GCP, RunPod, Tensordock, or Lambda Labs. --- ## Summary With the [requirements](/content/docs/quick-start/requirements/index.html) met and port **49200** open, start the node with: ``` git clone https://github.com/PluralisResearch/agora cd agora python3 agora_cli.py ``` The CLI will guide you through the setup process. Check run status before joining Live wait times are on the [Dashboard](https://agora.pluralis.ai/) in the **Overview** tab. Locate your compute instance in North America The current run's peers are NA-based and the join gate is RTT < 80 ms to them. Pick an NA datacenter (or an NA-located host on community marketplaces) — instances outside North America are routinely rejected during the authorization check. See [Requirements → Network latency](/content/docs/quick-start/requirements/#network/index.html) for the details. Progress is logged live on the [Dashboard](https://agora.pluralis.ai/). --- ## Run Pluralis Agora on Vast.ai Use this section if you have never rented a cloud GPU before, do not have a Vast.ai account, and have never used SSH. The path below rents an RTX 4090 on Vast.ai, opens the port Pluralis Agora needs, connects from your Linux machine, and starts the node. ### 1. Create a Vast.ai account Open [cloud.vast.ai](https://cloud.vast.ai/) and sign up. Confirm the email Vast.ai sends, then add a payment method under **Account → Billing**. You cannot rent an instance until billing is active. ### 2. Generate an SSH key pair on your Linux machine Open a terminal and run: ``` ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 ``` Press **Enter** at every prompt to accept the defaults. This produces two files: `~/.ssh/id_ed25519` (private — never share) and `~/.ssh/id_ed25519.pub` (public — paste into Vast.ai). Print the public half so you can copy it: ``` cat ~/.ssh/id_ed25519.pub ``` Select the entire output (one line starting with `ssh-ed25519`) and copy it to the clipboard. ### 3. Add the public key to Vast.ai In the Vast.ai console, go to **Account → Keys** (left sidebar). Click **New SSH Key**, paste the line you just copied, and save. ### 4. Create a HuggingFace account and generate a read token Pluralis Agora needs a HuggingFace token to download the model weights on first run. 1. Sign up at [huggingface.co/join](https://huggingface.co/join) and verify your email. 2. Go to [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens). 3. Click **New token**, give it any name, choose **Read** access, and click **Generate**. 4. Copy the token (a string starting with `hf_`). You will paste it into the Agora CLI in step 10. ### 5. Pick the Pluralis template In the Vast.ai console, open the [Pluralis template](https://cloud.vast.ai/?ref_id=519972&template_id=7d396d9a6f97ae15e6a056a6f51ecaa1). This template preconfigures CUDA + PyTorch and already publishes port `49200` to the host, so you skip the manual Docker port-mapping step that other templates require. Why the Pluralis template? Without it you have to edit the offer's **Docker create/run options** by hand and add `-p 49200:49200`. The template already includes that flag. ### 6. Choose a GPU and launch With the template applied, the Vast.ai search page shows offers from individual hosts. 1. Filter the offer list: - **GPU**: at minimum `RTX 4090` (24 GB VRAM). - **RAM**: at least `80 GB`. - **Disk**: at least `80 GB`. - **Location**: **North America** (open the _Geolocation_ filter and tick US / Canada / Mexico). Hosts outside North America fail the < 80 ms RTT join gate. 2. Sort by price. 3. From the offers near the top of the sorted list, pick one whose **reliability score is ≥ 99 %** and whose **DLPerf** number is reasonable for the GPU class. Both values are displayed on the offer card. 4. On the chosen offer, confirm **Launch Mode** is set to **SSH + TCP** (not Jupyter). 5. Click **Rent**. Pick `-p`, not `EXPOSE` If you ever launch a non-Pluralis template, edit **Docker create/run options** and add `-p 49200:49200`. The separate **Open Ports** / `EXPOSE` list only documents the port in image metadata; it does not publish it. ### 7. Read the external port Vast.ai maps the container's internal `49200` to a random external port. You need that external port for the next step and for the Agora launch flag. On your **Instances** page, click **IP & Port Info** on the new instance's card. The dialog shows lines in this format: ``` 65.130.162.74:33526 -> 49200/tcp ``` Record both halves. In the example above: - **Host** (public IP) = `65.130.162.74` - **External port** = `33526` - The instance's internal port `49200` is mapped to that external port. ### 8. Connect over SSH The instance card also exposes a **Connect** or **SSH** button. Click it to reveal the SSH command. It looks like this, with your own host and SSH port: ``` ssh -p root@ ``` Run that command in your terminal (note that Ghostly is not supported by vast.ai). The first time you connect, accept the host fingerprint by typing `yes`. The SSH port is different from the Agora port Vast.ai assigns one random port for SSH (used in the `ssh -p` command) and a separate random port for Agora (the one paired with `49200/tcp` in step 7). Do not confuse the two. ### 9. Update pip and PyTorch on the instance You are now in a shell on the rented machine. Bring the package toolchain up to the version Pluralis Agora expects: ``` python3 -m pip install --upgrade 'pip>=25.3' pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 \ --index-url https://download.pytorch.org/whl/cu128 ``` ### 10. Launch Pluralis Agora Clone the repo and start the CLI: ``` git clone https://github.com/PluralisResearch/agora cd agora python3 agora_cli.py --host_port 49200 --announce_port ``` Replace `` with the value you read in step 7 (for example `33526`). The CLI then prompts you for: - **HuggingFace token** — paste the `hf_…` token from step 4. - **Email address** — optional; press Enter to skip. - **GPU ID** — only asked if the instance has multiple GPUs; for a single-GPU rental, press Enter. - **Run inside Docker?** — answer `n`. You are already inside the Vast.ai container, so a second Docker layer is impractical. Your answers are saved to a config file. Subsequent runs of `python3 agora_cli.py` reuse them. Since Vast.ai nodes automatically attach to a tmux session, your node will continue even if you disconnect. ### 11. Watch the startup phases Once the CLI is running, Agora moves through four phases. The log lines below indicate a healthy startup. **Phase 1 — Network check and weight download** ``` [NETWORK] Running internet speed test... [DOWNLOAD] Downloading model weights... [DOWNLOAD] Model weights downloaded. Waiting for authorization... ``` A residential-grade uplink is not enough: the node needs ≥ 200 Mbps. If the speed test fails, the node is dropped from the queue. **Phase 2 — Authorization queue** ``` [AUTH] Authorization queue: position 2, estimated wait: 1m [AUTH] Access granted for your_user ``` **Phase 3 — Sync (only if joining an active run)** ``` [SYNC] Synchronising weights with peers. Node won't process batches in this phase. [SYNC] This phase will last 400 steps (until local epoch ). [SYNC] Synchronising optimizer state. Node is now processing batches, but doesn't contribute to weight averaging yet. [SYNC] This phase will last 100 steps (until local epoch ). [SYNC] Sync complete. Node is now fully contributing to training. ``` Sync can take several hours end-to-end. **Phase 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 ``` A new `[PROGRESS] Processed [N] batches` line every 60 seconds means the node is contributing. Detailed logs live in `logs/server_gpu.log` on the instance. ### 12. Verify your contribution Open [agora.pluralis.ai](https://agora.pluralis.ai/) and search for your HuggingFace username. Your rented node appears once training begins. --- ### Stopping, restarting, and reconnecting - **Stop the node** (inside the tmux session): press `Ctrl + C`. - **Restart the node** without losing your peer identity: re-run `python3 agora_cli.py --host_port 49200 --announce_port `. As long as the `private.key` file under the agora directory is intact, your node rejoins with the same identity and contribution history. - **Destroy the rental**: from the Vast.ai **Instances** page, click the stop / delete icon on the instance card. Billing stops at that moment. ### Troubleshooting - **`[NETWORK]` speed test fails.** The host's uplink is below 200 Mbps. Destroy the rental and pick another offer with a higher reliability score; community-marketplace hosts vary in network quality. - **Node joins but never processes batches.** Port `49200` is not reachable from outside. Verify in step 7 that the IP & Port Info panel shows `... -> 49200/tcp`. If it does not, the template's port mapping was overridden — relaunch with the Pluralis template. - **`ssh: connect to host ... port ...: Connection refused`.** The instance is still provisioning. Wait 30–60 seconds and retry. If it persists, check the instance status on the Vast.ai dashboard. - **HuggingFace authentication fails.** The token must have **Read** access. Generate a new token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) and re-run the CLI; it will re-prompt for the token if the saved one is invalid. - **Ask for help.** Pluralis [Zulip — Contributor Support channel](https://community.pluralis.ai/#narrow/channel/26-A---Contributor-Support).