The Seed daemon
The Seed daemon is the Go program that stores, checks and syncs Hypermedia data, and this page says where its code is, what it listens on, which flags matter, what it stores, and who may call it.

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:

    It stores signed blobs, and it checks and indexes them.

    It keeps account keys and signs with them.

    It syncs with other nodes over libp2p.

    It serves files over HTTP.

    It serves everything to the apps through gRPC and HTTP.

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

-p2p.port

55000

peer-to-peer sync and the P2P RPCs

HTTP

-http.port

55001

gRPC-web for every service, /ipfs/*, /hm/api/config, /debug/*

gRPC

-grpc.port

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

-data-dir

~/.mtt

Where everything is stored. The desktop app passes its own data directory.

-server-mode

false

Trust the deployment network and filter anonymous private reads. Hosted sites and gateways use this mode; the Docker image sets SEED_SERVER_MODE=true.

-api.allowed-origins

empty

Additional exact browser origins accepted in default mode.

-keystore-dir

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.

-p2p.testnet-name

empty

Joins a named testnet in place of mainnet by adding a suffix to the protocol id.

-p2p.no-relay

false

Disables circuit relay.

-p2p.bootstrap-peers

the Seed gateways and the public IPFS bootstrap peers

The peers a fresh node connects to first. none, or an empty value, turns bootstrapping off.

-p2p.isolated

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.

-lndhub.disabled

false

Turn off the wallet integration. Payment calls fail.

-syncing.no-discovery

false

Refuse to fetch content the node does not have, turning off discovery.

-syncing.no-pull

false

Disable the sync scheduler, which also runs every DiscoverEntity request and subscription rerun.

-storage.sqlite-soft-heap-limit

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.

-log-level

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

The SDK targets the Seed API. It does not call the daemon. The daemon's protobuf messages are available to TypeScript through the generated clients in @shm/shared.

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