The Seed daemon, seed-daemon, is the program that implements the Hypermedia protocol. On this site, "daemon" always means this program. You rarely use it directly: the desktop app starts one for you, and a site runs one in a container.
The daemon does five jobs:
The CLI and the app environment never need a daemon of their own, because they talk to a site's Seed API.
Where the code is
The daemon is in backend/, written in Go. The entry point is backend/cmd/seed-daemon. These are the main packages:
backend/blob: the blob types, verification and the indexer.
backend/api: the gRPC services.
backend/hmnet: libp2p, sync and the file gateway.
backend/storage: the SQLite schema and migrations.
backend/core: keys and signing.
backend/config: the flags.
The protobuf definitions are in proto/. They generate both the Go server and the TypeScript clients. Run ./dev gen after you change them.
backend/cmd holds other binaries beside the daemon: monitord (health checks of sites), relayd (a libp2p relay, a server that forwards connections for peers behind NAT), pingp2p (a connectivity test), and seed-sqlite and mkdb (database tools).
How programs talk to it
A program reaches the daemon through one of its three listeners. This section lists them, then the plain HTTP routes, then who may call.
Listener | Flag | Default | Serves |
|---|---|---|---|
libp2p |
| 55000 | peer-to-peer sync and the P2P RPCs |
HTTP |
| 55001 | gRPC-web for every service, |
gRPC |
| 55002 | the same services over plain gRPC |
The gRPC and HTTP listeners bind every network address. In default mode the daemon still accepts only callers on the same machine. Server mode skips that check and relies on the network of the deployment.
The desktop app passes its own ports, listed in the port table. A daemon that you run yourself keeps the 55000 defaults. You can also set every flag as an environment variable with the SEED_ prefix, so -p2p.port is SEED_P2P_PORT. SEED_DAEMON_FLAGS adds extra flags in front.
The HTTP surface
Besides gRPC-web, the HTTP port serves the file gateway and a few utility routes.
GET /ipfs/<cid> returns a file or one raw piece of IPFS data. If the node does not have it, the daemon searches the network for up to a minute. GET /ipfs/<cid>.dagjson decodes a DAG-CBOR blob and prints it as readable JSON. It is the quickest way to inspect a change, ref or comment. POST /ipfs/file-upload splits a file into UnixFS chunks and returns its CID. POST /ipfs/<cid> stores one raw piece of IPFS data. Both uploads accept up to 150 MiB and need no authentication. See Files.
GET /hm/api/config on the daemon returns its peer id, addresses and protocol id. The web app's version of the same route adds the registered account.
GET /debug/version reports the build. The other /debug/* pages cover metrics (/debug/metrics), pprof, the p2p and network reports, the SQLite pool and its memory, the C allocator and an embedded grpcui. The daemon admits callers to them by the same rules as the API.
Who is admitted
The daemon has two modes.
Default mode. The daemon accepts only connections from the same machine (loopback). It trusts a local program once it is connected. That program can read everything the daemon holds and write as any key it keeps, because signing happens inside the daemon. For HTTP the daemon checks more:
The Host header must be exactly localhost or a loopback IP address.
A request from a browser must come from an exact origin the daemon trusts. The daemon reads the browser's fetch metadata and the Origin header. For media and frames that send no Origin, it uses the origin in Referer.
-api.allowed-origins adds trusted browser origins, such as the origin of the desktop app's windows. It does not open the daemon to other machines or other Host names.
Server mode. -server-mode, or SEED_SERVER_MODE=true, turns the checks above off. The daemon trusts the network of the deployment. So you must do these things yourself:
Keep the daemon's HTTP and gRPC ports private, behind the web app.
Proxy only the public /ipfs/* routes.
In server mode the daemon hides private content from a caller with no token. A caller with a valid bearer token may read the private content it is allowed to see. A bearer token never allows a write. The Docker image turns server mode on through its environment. Integrity explains the trust model.
Configuration
You configure the daemon with flags. These are the ones that matter most to a person who runs one.
Flag | Default | Meaning |
|---|---|---|
|
| Where everything is stored. The desktop app passes its own data directory. |
| false | Trust the deployment network and filter anonymous private reads. Hosted sites and gateways use this mode; the Docker image sets |
| empty | Additional exact browser origins accepted in default mode. |
| empty | Use a file-based keystore in place of the OS keychain or the local vault file. It is marked insecure. Sites use it inside their container. |
| empty | Joins a named testnet in place of mainnet by adding a suffix to the protocol id. |
| false | Disables circuit relay. |
| the Seed gateways and the public IPFS bootstrap peers | The peers a fresh node connects to first. |
| false | Talk to no other node: refuse every connection, and skip bootstrap, peer exchange, relay and NAT. It also turns off bootstrap peers and the wallet. |
| false | Turn off the wallet integration. Payment calls fail. |
| false | Refuse to fetch content the node does not have, turning off discovery. |
| false | Disable the sync scheduler, which also runs every |
| 0 | Bytes of heap memory SQLite may hold across all connections. Above it page caches recycle their oldest pages instead of growing; nothing fails. 0 means no limit. See Daemon operations. |
| info | debug, info, warning or error. |
The daemon network reference lists the rest of the flags and every timeout and constant. Self-hosting shows the flags a site container uses.
What it stores
The data directory holds three things.
keys/libp2p_id_ed25519 is the device key, which identifies this daemon to other peers. It is separate from every account key.
vault.json is the local vault file: the encrypted store for account keys. A secret in the OS keychain decrypts it. It is not the vault service, which can sync with it.
db/db.sqlite is the SQLite database. It holds every blob, the index derived from them, full-text search, and the domain store.
The schema in backend/storage/schema.sql is the source of truth, and migrations only go forward. A reindex rebuilds everything the daemon derives from the blobs. It can take a long time on a large node. A debug flag forces a reindex with profiling.
Running it
You rarely start the daemon by hand:
The desktop app starts one with its own ports and data directory.
A site runs one in a container, in server mode. Self-hosting describes it.
For development, ./dev run-backend builds and runs seed-daemon alone. Flags after -- go to the daemon.
Contributing has the build setup.
Daemon operations explains what to look at when a running daemon is slow or uses too much memory.
Working with it
In the Seed app
The desktop app starts the daemon and waits for /debug/version to answer. Then it starts its own API bridge, the local copy of the Seed API. When that setting is on, it also starts a local app environment. The app's settings show the daemon's peer id and addresses.
CLI
The CLI does not need a local daemon. One command uses one: seed-cli space dev talks to the desktop app's API bridge and to the daemon's HTTP port, to publish a folder into the running app. See Publish a folder.
SDK
Seed API
The web app answers every site's /api/<Key> routes by calling the daemon over gRPC-web. Over plain HTTP, the daemon itself serves /ipfs, /hm/api/config and the /debug pages. Daemon gRPC lists the services for programs that call the daemon directly.
Agents
Seed Agents read and write through a site's Seed API, and they fetch media from the daemon's /ipfs route. Agents on a local app environment use the desktop app's daemon through the API bridge. Hosted agents use hyper.media.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime