🧬 Run a Cellule.ai pool

Join the molecule. Federated LLM inference, signed handshakes, cross-pool replication. Every node matters.

Quick start — docker compose (~3 minutes)

1. Get the compose file

   mkdir cellule-pool && cd cellule-pool
   curl -O https://cellule.ai/docs/docker-compose.yml
   curl -O https://cellule.ai/docs/.env.example
   cp .env.example .env

2. Edit .env with your pool name + public URL + DB password.

   POOL_NAME=my-community-pool
   POOL_URL=http://YOUR_PUBLIC_IP:8080
   DB_PASS=some-strong-random-password
   ADMIN_PASSWORD=admin-secret

   Your POOL_URL must be reachable from the public internet. The simplest setup is to NAT TCP port 8080 on your router to your machine’s LAN IP.

3. Start the stack

   docker compose up -d
   docker compose logs -f cellule-pool

   You should see CELLULE.AI POOL v0.2.51 and migration messages followed by federation: mode=observe atom_id=.... Your pool is now running.

4. Verify locally

   curl http://localhost:8080/v1/federation/info

   Returns a JSON card with your pool’s atom_id (64-char hex) and pubkey. Save these — they’re your identity.

5. Verify publicly

   From another machine (your phone on 4G works) :

   curl http://YOUR_PUBLIC_IP:8080/v1/federation/info

   If this fails, your NAT rule isn’t in place yet. The pool is running but can’t be joined by the molecule.

6. Request federation

   Contact the Cellule.ai community with your atom_id + POOL_URL to get bonded. For now, DM @moleculeiallm on X. A later version of this flow will be self-serve.

What you get

As soon as your pool is bonded trust level 2 :

• Your pool appears in the live molecule on the cellule.ai landing page as a new satellite in the atom canvas.
• Accounts created on any bonded pool replicate to yours via M11.1 gossip.
• Ledger gossip via M11.2 keeps your pool in sync with the molecule’s revenue history.
• Workers from any pool can migrate to yours via the M11.3 seed list protocol.
• You can accept your own workers (local LLM machines) via WebSocket ws://YOUR_POOL_URL:8080/ws.

Requirements

• Linux or macOS (Windows via WSL2)
• Docker 20+ with compose v2
• 2 GB RAM, 10 GB disk (more if you run workers too)
• Public URL / NAT rule for TCP 8080 inbound
• No GPU required for the pool itself (workers can be GPU or CPU, separately)

Troubleshooting

Container keeps restarting

Check docker compose logs cellule-pool. Most common cause : POOL_URL not set or still http://YOUR_PUBLIC_IP:8080 (placeholder). The pool refuses to boot without a valid URL.

Migrations fail

The image uses pgvector/pgvector:pg16 automatically via compose. If you use an external postgres, make sure the vector extension is available (SELECT * FROM pg_available_extensions WHERE name='vector').

Federation handshake fails

Usually means your POOL_URL is not reachable from the Cellule.ai VPS. Test with curl from any public machine. If it fails there, fix your NAT / DNS / reverse proxy before asking to be bonded.

Source + support

• Full manual runbook (no-docker path) : RUNBOOK_POOL_BOOTSTRAP.md
• Architecture : ARCHITECTURE.md
• X : @moleculeiallm
• Main site : cellule.ai