# QuinkGL Multi-Device Setup Guide

This guide explains how to run the **QuinkGL Gossip Learning** nodes on multiple physical computers (e.g., your laptop and a friend's computer, or a cloud server) without using Docker.

## Prerequisites

On **each** computer, you need:
1.  **Python 3.10+** installed.
2.  **Git** to clone the repository.
3.  **Internet Access** (for downloading dependencies and peer discovery).

---

## 1. Installation (On All Computers)

Open your terminal (Mac/Linux) or PowerShell (Windows) and run:

```bash
# 1. Clone the repository
git clone https://github.com/aliseyhann/quinkgl-p2p-chat.git
cd quinkgl-p2p-chat

# 2. Setup Virtual Environment (Recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install Dependencies
pip install -r requirements.txt

```

---

## 2. Running Nodes

To make them talk to each other, they need to be in the same **domain**. They will find each other using public bootstrap servers (if on different networks) or local broadcast (if on same WiFi).

### Computer A (Alice)
Run this command to start the first node:

```bash
# Make sure you are in the project root folder
# Note: Using port 8001 (metrics) and letting OS choose UDP port for P2P

python3 scripts/run_gossip_node.py \
    --node-id node_alive_A \
    --domain experiment_1 \
    --dataset breast_cancer \
    --gossip-interval 2.0 \
    --metrics-port 8001
```

### Computer B (Bob)
Run this command on the second computer:

```bash
# Different node-id, same domain!

python3 scripts/run_gossip_node.py \
    --node-id node_bob_B \
    --domain experiment_1 \
    --dataset breast_cancer \
    --gossip-interval 2.0 \
    --metrics-port 8002
```

---

## 3. How It Works

1.  **Peer Discovery:** The nodes use the **IPv8** protocol. They connect to public "Bootstrap Nodes" (like Tribler's DHT) to announce themselves.
2.  **UDP Hole Punching:** Even if you are behind a home router (NAT), IPv8 tries to "punch a hole" so devices can talk directly.
    *   *Note: If you are on very strict corporate networks or mobile hotspots, this might sometimes fail.*
3.  **Gossip:** Once discovered (you will see `Found 1 peer(s)` in logs), they start exchanging model weights.

## 4. Troubleshooting

*   **No Peers Found?**
    *   Wait a bit (up to 30-60 seconds for global DHT discovery).
    *   Ensure both computers have the **exact same** `--domain`.
    *   Check if your firewall calls for permission (Allow Python to access network).

