DHT Discovery

Overview

mycellm uses a Kademlia-based DHT on UDP port 8422 for decentralized peer discovery and model availability announcements. The DHT is optional — nodes can operate using only bootstrap-mediated discovery.

How it works

Each node that participates in the DHT maintains a routing table of peers organized by XOR distance from its own Peer ID. Nodes announce which models they can serve, and other nodes query the DHT to find providers.

Node A (has llama-3.2-3b)
    │
    ├── STORE(key=sha256("llama-3.2-3b"), value=PeerA_addr)
    │       ▼
    │   DHT peers closest to key
    │
Node B (wants llama-3.2-3b)
    │
    └── FIND_VALUE(key=sha256("llama-3.2-3b"))
            ▼
        Returns PeerA_addr

Model keys are SHA256(model_name). Values contain the announcing peer’s address, available VRAM, estimated tokens/sec, and a signed timestamp.

Protocol messages

Discovery uses two message types over the QUIC control channel:

DHT_QUERY

Sent by a node looking for model providers:

{
  "type": "DHT_QUERY",
  "key": "a1b2c3...",
  "model": "llama-3.2-3b-q4_k_m",
  "max_results": 5
}

DHT_RESPONSE

Returned with matching providers:

{
  "type": "DHT_RESPONSE",
  "key": "a1b2c3...",
  "providers": [
    {
      "peer_id": "d4e5f6...",
      "addr": "203.0.113.10:8421",
      "model": "llama-3.2-3b-q4_k_m",
      "tps": 42.5,
      "vram_free_mb": 6144,
      "timestamp": 1711152000,
      "signature": "..."
    }
  ]
}

Announcements

Nodes re-announce loaded models every 10 minutes. Announcements expire after 30 minutes if not refreshed. When a model is unloaded, the node sends a withdrawal message.

# View current DHT announcements
mycellm dht status

# Manually announce a model
mycellm dht announce llama-3.2-3b-q4_k_m

iOS behavior

iOS devices do not run a local DHT node. Maintaining a Kademlia routing table requires persistent UDP listeners, which conflicts with iOS background restrictions and battery life.

Instead, the iOS app queries the bootstrap node as a DHT gateway:

iOS ──DHT_QUERY──▶ Bootstrap ──(DHT lookup)──▶ Network
                                                  │
iOS ◀──DHT_RESPONSE──────────────────────────────┘

This adds one hop of latency but avoids keeping a UDP socket alive in the background.

Disabling the DHT

For environments where UDP multicast is blocked or unnecessary:

mycellm serve --no-dht

Or in ~/.config/mycellm/.env:

MYCELLM_DHT_ENABLED=false

When DHT is disabled, the node relies entirely on bootstrap-mediated discovery and fleet registry lookups.

Configuration

Setting	Default	Description
dht.port	8422	UDP port for DHT traffic
dht.replication	3	Number of peers that store each key
dht.announce_interval	600	Seconds between re-announcements
dht.expiry	1800	Seconds before an announcement expires