Join HiveMind La Ruche

1. Use the models

1. Create your account with a handle of your choice. The handle is public (it can appear in lists and on the message bus), so pick a pseudonym: 1 to 64 ASCII letters, digits and . _ @ + -.

curl -s https://hivemind-openrouter-1003063861791.us-central1.run.app/v1/hivemind/register -H "Content-Type: application/json" -d '{"handle":"your-handle","role":"consumer"}'

2. The reply holds your API key (api_key). It is shown once and cannot be recovered: store it somewhere safe. If you lose it, register a new handle.
3. A new account holds 0 points unless the operator grants some. Points come from sharing a GPU (path 2) or from a grant: if you only want to try, ask for one in a GitHub issue.
4. Test your key:

export HIVEMIND_API_KEY=hm-YOUR_KEY
curl https://hivemind-openrouter-1003063861791.us-central1.run.app/v1/chat/completions \
  -H "Authorization: Bearer $HIVEMIND_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"hivemind/auto","messages":[{"role":"user","content":"Hello!"}]}'

In an editor (VS Code, Continue, …) follow the connection guide.

2. Share your GPU to answer questions

Your machine runs a model, the gateway sends it questions, and you earn points for the tokens you serve. You will use a terminal.

1. Get the code (Python 3.11 or 3.12):

git clone https://github.com/xaviercallens/HiveMind.git && cd HiveMind
pip install httpx fastapi uvicorn

2. Find the model that fits your card (the table below lists all of them). This command reads your card’s memory and needs no account:

python scripts/hivemind_producer_agent.py --gateway https://hivemind-openrouter-1003063861791.us-central1.run.app --suggest --detect-vram

3. Install Ollama, then download the model it suggested, for example:

ollama pull qwen2.5-coder:3b

4. Create a producer account the same way, with "role":"producer" (or "prosumer" if you also want to use models, or "trainer" for intense GPU training via OpenTrainer), and keep the key.

5. Your machine must be reachable over https at a public address: the gateway refuses plain http and private addresses. At home that means a tunnel or a reverse proxy in front of the producer shield, a small program that exposes only the two routes the gateway needs and demands its token. Check with curl https://YOUR_ENDPOINT/v1/models.
6. Start the shield and the agent (all options: the producer guide). Use --once first to see the gateway’s answer:

export HIVEMIND_API_KEY=hm-YOUR_PRODUCER_KEY
export HIVEMIND_ENDPOINT_TOKEN="$(python -c 'import secrets;print(secrets.token_urlsafe(32))')"
python scripts/hivemind_producer_shield.py --upstream http://127.0.0.1:11434 --port 8787 --allow-model qwen2.5-coder:3b &
python scripts/hivemind_producer_agent.py --gateway https://hivemind-openrouter-1003063861791.us-central1.run.app --endpoint https://YOUR_ENDPOINT --preset coder-lite --once

On Windows (PowerShell) set variables with $env:NAME="value" instead of export. Remove --once to keep the agent running.

7. Optional — keep your GPU connected across reboots with an auto-start background service (systemd on Linux, Scheduled Task on Windows 10/11, launchd on macOS):

python scripts/hivemind_producer_autostart.py linux --model coder=qwen2.5-coder:7b --apply ./producer-autostart
python scripts/hivemind_producer_autostart.py windows --model coder=qwen2.5-coder:7b --apply ./producer-autostart

You can stop at any time: after about two minutes without a heartbeat the gateway stops sending you requests.

3. Train models at night with BOINC

This path is open to the public: the federated BOINC & Night-MoE coordinator is live at HiveMind La Ruche (live Night-MoE telemetry at /night-moe, BOINC coordinator status at /boinc/status and citizen-science leaderboard at /community). You can check your hardware, run a local dry-run (--dry-run), and lease workunits today.

• Linux on an x86-64 processor for the native BOINC portable bundle, or Linux, Windows and macOS with the Python BOINC/BLS worker
• An NVIDIA card with at least 3.5 GB of video memory (cuda_hivemind; 12 GB+ for cuda_hivemind_big), or a 4+ thread CPU with 8 GB RAM for CPU/BLS transit sweeps (cpu_hivemind_solver)
• A first download of about 4.4 GB, reused afterwards
• Community work is offered at night, 22:00–07:00 Paris time, when the network is least busy
• The standard BOINC client; the project’s files are digitally signed

1. Run the read-only hardware and coordinator network preflight check first (it installs nothing; add --allow-cpu-solver on a machine without an NVIDIA driver):

python3 scripts/hivemind_volunteer_preflight.py --project-url https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app

2. Run a complete local dry-run test (--dry-run). It checks that this machine can run a small GPU kernel on a built-in test pattern (a dip injected into a synthetic 16,384-point curve: a self-check, not real TESS or JWST data) and that the coordinator answers. It does not train a model:

python3 scripts/hivemind_boinc_idle_worker.py --coordinator https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app --handle your-handle --domain physics_sim --dry-run

3. Lease, fold and submit a live federated BOINC workunit (physics_sim, code_generation or math_reasoning) from the public coordinator (remove --once to keep folding at night):

python3 scripts/hivemind_boinc_idle_worker.py --coordinator https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app --handle your-handle --domain physics_sim --once

4. Or attach a standard BOINC client (boinccmd) directly to the public project URL and inspect verified receipts on /api/v1/federated/ledger:

boinccmd --get_project_config https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app
boinccmd --project_attach https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app YOUR_ACCOUNT_KEY

Honest status of the helper script (hivemind_boinc_idle_worker.py): the result it submits is a deterministic placeholder computed from the workunit id, not a trained model, so treat any points shown for it as provisional. Real training workunits run only through the BOINC client attached above.

On a PC you also play on, ask the BOINC client itself to step aside. This prints two small settings files (nothing is installed or changed until you add --apply with your BOINC data folder; your old files are kept as backups):

python3 scripts/hivemind_volunteer_config.py gamer --game YourGame.exe

With these settings the BOINC client does no GPU work while you are using the computer, gives back the video memory of a paused task, and stops GPU work at once while a program you name with --game is running. Tested with the real BOINC client on Linux. Not tested on Windows. A game you do not name, played with a controller only, is not detected: name your games.

Night training for end-users and HiveMind nodes (22:00–07:00 Paris time): End-users (volunteers, developers and gamers) leave their PC or laptop running overnight to fold exoplanet transits and compute rank-4 QLoRA inner-loop updates, earning 250 HMT and 45 Cobblestones per workunit to spend the next day on all models. Dedicated HiveMind nodes (GPU producers, HiveMiners and the owner fleet) switch from daytime OpenRouter inference (07:00–22:00) to nocturnal DiLoCo outer-step aggregation, Multi-Krum verification and SVD teacher-to-student distillation (live node telemetry at /v1/hivemind/bees/owner-fleet-status).

3b. OpenTrainer — Intense GPU Co-Training (BOINC + AMCP + Kafka + Aglets, Firewall-Friendly)

Registering with the "trainer" role on /signup connects your GPU to OpenTrainer (/v1/hivemind/opentrainer/status), the central coordinator integrating BOINC, AMCP v1.5, Kafka (hivemind.amcp.federation.v1), and Signed Task Agents (IBM Aglet life cycle without mobile code) built between the RTX 2070 (XAVGAMSRV, 8 GB, Windows 11) and the GCP Tesla T4 (socreateai-agora-hermes-node1, 16 GB, Linux) across PRs #366, #399, #401, #407, #408, #409, and #410 (see the OpenTrainer architecture guide).

• Tier B Outbound HTTPS Relay (outbound-https-relay): Your trainer GPU initiates outbound-only HTTPS (TCP/443) calls to /v1/hivemind/opentrainer/heartbeat and /v1/hivemind/opentrainer/submit-delta — zero inbound firewall ports, zero 0.0.0.0 listeners, works behind residential NAT, CGNAT, and Windows Firewall
• Tier A Signed Task Agents over AMCP & Kafka (amcp-kafka-aglet / wireguard-t4-hub / ssh-loopback-tunnel): Implements IBM's Aglet life cycle (dispatch task_offer -> arrival check_offer -> clone task_claim -> result task_result -> retract task_abort) without mobile code (weights_only=True, CRLF-normalized code_pin) for Stage-2 Tiny Granite-MoE NF4 QLoRA and DiLoCo 2D-DCT outer steps
• Tier C BOINC Night Workunits (boinc-night-workunit): Asynchronous night workunits over standard HTTPS (TCP/443) when the GPU is idle between 22:00 and 07:00

1. Verify outbound firewall traversal, register your trainer GPU on OpenTrainer, and submit a verified Aglet round receipt (remove --once to run continuously):

export HIVEMIND_API_KEY=hm-YOUR_TRAINER_KEY
python scripts/hivemind_opentrainer_agent.py --gateway https://hivemind-openrouter-1003063861791.us-central1.run.app --network-mode outbound-https-relay --check-firewall --submit-delta --once

Newcomers are welcome at the co-training nights. Night 3 runs Monday 2 November 22:00 to Tuesday 07:00 Paris. You need no account to ask for a slot, and producers need no migration: producer, prosumer and trainer keys share the training role. Short guide: docs/TRAINER_JOIN.md.

2. Create a WireGuard key pair and keep the private key to yourself; only the public key is ever shared:

wg genkey | tee hivemind-wg-private.key | wg pubkey > hivemind-wg-public.key

3. Print this machine's federation plan (read-only: it installs nothing and contacts nothing; exit code 2 means no GPU was read):

PYTHONPATH=src python3 scripts/hivemind_federate_node.py --handle your-handle --coordinator https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app --json

4. Reply on issue #431 before 18:00 Paris on the day of the night with your public key, GPU model, free video memory and operating system (attach the JSON plan; it holds no key). The operator answers with a learner id, an overlay address, the commit to check out and the shared signing key, out of band. Points: submissions are recorded as unverified and credit 0 until server-side verification exists.

4. Gamers and Steam

Your GPU should work for HiveMind only while you are not playing. There is no HiveMind game on Steam yet: the Steam ID 3133700 that appears in this repository belongs to an unrelated game add-on (Fantasy Grounds), so do not look for us there. What exists today is a helper script that pauses the BOINC GPU queue while you play (below), and the BOINC client’s own settings (section 3). Citizen-science standings are on the community page.

The helper pauses the BOINC GPU queue (boinccmd --set_gpu_mode never) when it sees keyboard or mouse input in the last 4 seconds, GPU load above 45%, or a GPU temperature above 78 °C, and sets it back to auto otherwise. On Linux it needs xprintidle (X11 only); where it cannot measure your input it assumes you are playing and does nothing. It changes the BOINC GPU mode itself, so it overrides a mode you set by hand. We have not measured its effect on frame rate. What it computes while you are away is a built-in self-check pattern, not real telescope data (see section 3).

1. Start the automatic idle-GPU worker (remove --once to leave the automatic pause/resume daemon running in the background while you play):

python3 scripts/hivemind_boinc_idle_worker.py --coordinator https://hivemind-at-home-ruche-cfhmhmvv5a-uc.a.run.app --handle your-handle --idle-threshold-seconds 4 --once

2. You can also trigger an immediate manual GPU pause or resume from a Steam launch option:

python3 scripts/hivemind_boinc_idle_worker.py --pause-now

3. If you also run an Ollama producer from path 2, a loaded language model keeps its video memory even when nobody is asking; before launching a heavy game, stop the producer agent (Ctrl+C) and unload the model (replace the name with your model’s):

ollama stop qwen2.5-coder:3b

4. After you play: start the producer agent again, with the same command as in path 2 (the BOINC idle-GPU worker resumes by itself).

Good to know

• Producers see the questions sent to them. Do not run a producer on a machine that holds secrets, and do not send confidential text to the network.
• Points have no cash value and are not a payment.
• Sharing uses electricity while your GPU answers. Measure your card with nvidia-smi --query-gpu=power.draw --format=csv and multiply by the hours it works.
• The software is open source (AGPL-3.0). Read the code before you run it.
• The network is young and run by volunteers; availability is not guaranteed.

Questions and help

Open an issue on GitHub, in English or French. For a security problem, read the security policy first.