Network Architecture
Seed Hypermedia uses a peer-to-peer network built on libp2p. Every daemon is a network node that can discover, connect to, and exchange content with other nodes. There's no central server — content flows directly between peers.
In practice, gateway nodes serve as important hubs that make content accessible via HTTP. But the architecture is fundamentally decentralized — if a gateway goes down, content remains available on other peers.
Peer Discovery
Nodes discover each other through several mechanisms:
• Bootstrap nodes — Well-known peers that help new nodes join the network
• DHT (Distributed Hash Table) — Kademlia-based peer discovery
• mDNS — Local network discovery for peers on the same LAN
• Direct connections — Explicitly connecting to known peer addresses
# List connected peers
grpcurl -plaintext -d '{}' localhost:55002 \
com.seed.networking.v1alpha.Networking/ListPeers
# Connect to a specific peer
grpcurl -plaintext -d '{
"addrs": ["/ip4/1.2.3.4/tcp/55000/p2p/12D3KooW..."]
}' localhost:55002 \
com.seed.networking.v1alpha.Networking/ConnectContent Syncing
Syncing determines which content gets replicated between peers. There are two modes:
Subscriptions
When you subscribe to an account, your daemon actively seeks and replicates all their content. This ensures you always have the latest version available locally.
# Subscribe to an account
grpcurl -plaintext -d '{
"uri": "hm://z6Mk.../"
}' localhost:55002 \
com.seed.activity.v1alpha.Subscriptions/SubscribePush-Based Sync
When you create content, you push it to specific peers (typically gateways). This is more reliable than waiting for passive discovery.
# Push content to a peer
grpcurl -plaintext -d '{
"addrs": ["/p2p/12D3KooW..."],
"resources": ["hm://z6Mk.../my-doc"],
"recursive": true
}' localhost:55002 \
com.seed.documents.v3alpha.Resources/PushResourcesToPeerAlways push explicitly after creating content. P2P gossip is slow and unreliable for initial distribution.
Gateways
Gateways are SHM nodes that also run a web server, making content accessible via standard HTTP. They bridge the P2P network and the traditional web.
Key gateways:
• hyper.media — The main production gateway
• seed-gateway.exe.xyz — Community gateway with .md extension support
You can run your own gateway using the seed-web Docker image. This gives you full control over how your content is served.
Self-Hosting a Gateway
# Docker compose for a basic gateway
version: '3'
services:
seed-daemon:
image: ghcr.io/seed-hypermedia/seed-daemon:latest
volumes:
- ./data:/data
command: ['-data-dir', '/data']
seed-web:
image: ghcr.io/seed-hypermedia/seed-web:latest
ports:
- '80:3000'
environment:
- DAEMON_GRPC_URL=http://seed-daemon:55002Important: The daemon exposes port 55002 for gRPC and 55001 for HTTP internally. The web server connects to the daemon's gRPC port.
QUIC Transport
SHM uses QUIC as its primary transport protocol, providing:
• Encrypted connections by default
• Multiplexed streams over a single connection
• NAT traversal capabilities
• Low-latency connection establishment
For optimal performance, increase UDP buffer sizes on the host:
# Linux: Increase UDP buffer size
sudo sysctl -w net.core.rmem_max=7500000
sudo sysctl -w net.core.wmem_max=7500000Troubleshooting
• Content not syncing — Check peer count with ListPeers; try explicit push
• Low peer count — Ensure outbound UDP is not blocked by firewall
• Slow sync — Push directly to gateways instead of waiting for gossip
• Buffer size warning — Set sysctl UDP buffer sizes as shown above
• Content visible locally but not on gateway — You forgot to push! Always push after creating.