Skip to main content

Headless host

peers-headless runs the Peers runtime in a Node.js process: no Electron, no window, no UI. It is a first-class App host. One user per process.

Use it as an always-on personal node, a CI / agent target, or a second device in scripted tests. The Electron app, PWA, and hosted k8s device are separate hosts; they do not import this package yet.

A headless process can also hold a System Local Folders grant for a directory that should stay available while laptops sleep. Pass --folder (below) or peers fs grant after it is up. This phase records the grant and can index the folder on this machine. Sending those blocks to other devices is a later phase.

Start​

cd peers-headless
npm run build

# Ephemeral (in-memory SQLite), no cloud services
npx peers-headless --new-user --db :memory: --print-credentials --services-url none

# Persistent
npx peers-headless --new-user --db ~/peers/headless/alice --name Alice
# later launches reuse <db>/credentials.json
npx peers-headless --db ~/peers/headless/alice

With an on-disk --db, --new-user writes the credential record to <db>/credentials.json (mode 0600) and refuses to overwrite an existing file. Explicit --user-id/--secret-key, --credentials <file>, or USER_ID/SECRET_KEY override it. --name only applies on first boot; a rename from another device is kept. peers app restart re-execs as the same identity.

The credential record​

{
"userId": "00mabc…",
"secretKey": "…",
"dbSecret": "…",
"previousPublicKeys": [
{ "publicKey": "…", "replacedAt": "2026-10-02T18:04:11.000Z", "reason": "compromised" }
]
}
FieldMeaning
userId, secretKeyThe identity. secretKey is the current Ed25519 signing key; the X25519 encryption key is derived from it.
dbSecretThe SQLCipher key for the on-disk databases. It is independent of the signing key so a key rotation never has to re-encrypt the database. --new-user mints a random one; a file that predates this field derives it from the secret key the way older hosts did, and keeps that value from then on. DB_SECRET overrides it in the environment.
previousPublicKeysPublic keys this identity used before, newest last, with when and why each was replaced. Informational; peers keys show prints it.
rewrapFromPresent only while a rotation is unfinished: the key just retired (publicKey and secretKey). The new key is written as soon as the anchors accept it; the secrets in the personal database are then re-encrypted one by one and the field is removed last. If the process dies in between, the next start finishes the re-encryption with this key and drops it. Do not remove it by hand.

A bare userId::secretKey string, or a file with only userId and secretKey, is still accepted and upgraded in memory. peers keys rotate and peers keys rotate --manual rewrite the file only after every on-record anchor lists the new key. The plain form needs a recovery-email session (peers keys email). When the identity is given only by --secret-key or USER_ID/SECRET_KEY, the host also cannot persist a new secret, because there is no file to rewrite.

Recovering a lost key​

A headless host is never signed out, so peers keys recover (which runs on a signed-out desktop) does not apply to it. To bring a headless host back after its key is lost, publish the new key first — from a signed-out desktop with peers keys recover --user <userId>, or by seeding the registry with the operator tool — then start the host with the new secret: a fresh --db with --user-id and --secret-key, or a credentials.json holding the new secretKey. Keeping the old --db and dbSecret is also fine: at startup the host asks the anchors on record about the key it now holds and re-signs its profile row with it once they confirm it — at once when the old key co-signed the new one, after the recovery delay otherwise. Groups do not follow a recovered key; a member invites the host again.

Restart after a key rotation​

When a rotation does complete, the host rewrites credentials.json (same dbSecret, new secretKey, one more previousPublicKeys entry), replies to the caller, and then exits with code 0. The process does not re-exec itself. Run the host under a supervisor that restarts it (systemd Restart=always, a container restart policy, pm2, …) or start it again by hand. The log line is Key rotated; exiting so the next start uses the new key. peers keys rotate reaches it once every anchor on record lists the new key.

Pair instead of copying a secret​

To add a headless host to an account you already use, do not copy the secret key around. Start it signed out with --pair:

npx peers-headless --pair --db ~/peers/headless/server --name "Home server"

It creates a rendezvous room on --services-url (default https://peers.app) and prints a code such as 7-guitar-revenge-tunnel, plus a QR code when stdout is a terminal. On a signed-in device choose Settings → Add another device and scan or type the code, or on a signed-in host run peers pair 7-guitar-revenge-tunnel. When you approve, the headless process receives the credentials over a direct WebSocket, writes <db>/credentials.json (mode 0600), and continues booting as that account in the same process. The secret never appears on argv, in the environment, or in logs. Later launches need only --db.

While pairing, the process listens on --peer-port (default 3341) for the signed-in device and advertises http://<lan-ip>:<port> and http://127.0.0.1:<port>; the normal device-mesh listener takes the port over once pairing completes. Only a socket presenting the PAKE-derived token for the current code is admitted, and only one. If the host sits behind a proxy or TLS terminator, advertise the public origin instead:

npx peers-headless --pair --db /srv/peers --pair-url https://peers.example.com

--pair refuses to run when <db>/credentials.json, explicit credentials, or USER_ID/SECRET_KEY already provide an identity, and it needs a --services-url (not none) for the rendezvous. If the --db directory still holds personal/ or group_*/ databases from an earlier identity on this host (typically a device whose key was rotated away elsewhere, after its credentials.json was removed), pairing renames them to <name>.stale-<timestamp> before it boots and logs each move; the new identity mints its own dbSecret and could not have opened them. Nothing is deleted; remove the .stale-* directories yourself once you are sure they are not needed. Each line of progress is printed; PAIRING_CODE <code> is a machine-readable marker for scripts. A failed attempt rotates to a new code; if the runtime had already initialized when the failure happened, the process exits non-zero and should be started again. Details of the ceremony are in Add another device.

The signed-in side is available too: peers --auth-file ~/peers/cli/headless-auth.json pair <code> approves a new device from a headless host.

The process binds a frontend socket on 127.0.0.1 and writes ~/peers/cli/headless-auth.json (port + token). That path is separate from Electron's ~/peers/cli/cli-auth.json, so a running desktop app is not stolen.

Point the CLI at this host without hijacking Electron:

peers --auth-file ~/peers/cli/headless-auth.json db query "SELECT name FROM Users"

PEERS_CLI_AUTH_FILE is the same override. --write-cli-auth still replaces the default Electron auth file if you want that.

--port 0 binds an ephemeral frontend port. --peer-port 0 binds an ephemeral device-mesh port and --peer-host 127.0.0.1 restricts it to loopback (default is every interface). --no-db-access disables SELECT/PRAGMA over the socket (allowed by default on a headless host). --no-peer skips the mesh listener.

A machine-readable READY {json} line is printed on stdout when the host is up (userId, deviceId, port, token, authFile, peerPort, webrtc, services).

Registering with peers-services​

A device needs an account token from peers-services before it can use the mailbox (store-and-forward for invites while the other party is offline). On the desktop and PWA the welcome screen asks for it; a headless host asks with --register-services (or PEERS_REGISTER_SERVICES=1):

npx peers-headless --db ~/peers/headless/server --register-services

After the device initializes it calls the same registerWithPeersServices RPC the UI uses and stores the token in the encrypted PEERS_SERVICES_TOKEN user variable, where MailboxClient reads it. Registration is best effort: a failure logs [services] registration ... failed; continuing without a mailbox token and startup continues. The READY payload reports services as off (flag not given or --services-url none), registered, or failed. The flag refuses to run together with --services-url none.

The flag is only the opt-in. Once a token is stored, the runtime keeps it alive on every host (headless, desktop, PWA): it re-authenticates a week before the 30-day expiry and once more if the mailbox answers 401, so a long-running host does not need --register-services on later starts. A host that never registered is left alone.

WebRTC (optional)​

Device-to-device WebRTC runs in a separate Go process, peers-webrtc, the same sidecar the desktop app ships. It is an optional dependency: peers-headless does not bundle the binary, and a host without one (or with one that keeps crashing) boots and forms WebSocket edges with reachable hosts. A PWA cannot use that fallback: it needs the host’s WebRTC sidecar. WebRTC adds the paths a plain listener cannot cover: two devices that both sit behind NAT with no reachable --peer-port, and a pairing destination that a source cannot dial directly.

Discovery order at startup:

  1. --webrtc-sidecar <path> (or PEERS_WEBRTC_SIDECAR): use exactly this binary. If it does not exist the host logs one line and continues without WebRTC.
  2. Otherwise auto-detect: the sibling dev build for this platform (../peers-webrtc/bin/<goos>-<goarch>/peers-webrtc), the legacy un-suffixed ../peers-webrtc/bin/peers-webrtc, then peers-webrtc on PATH.
  3. --no-webrtc: never look for or start a sidecar (webrtc: "off").

Build the binary once with cd peers-webrtc && make local (needs Go); the monorepo checkout then auto-detects it. --no-peer disables the listener; an enabled sidecar can still form outbound mesh connections through a configured bootstrap peer or Services.

Status shows up in three places. The startup log prints [WebRTC] Starting sidecar <path> then [WebRTC] sidecar ready, or a single [WebRTC] ... continuing with WebSocket only line naming the flags when nothing was found. The READY payload carries webrtc: off, starting, ready, down, or unavailable. And NetworkManager only advertises wrtc to peers while the sidecar is authenticated (isAvailable()), so a host whose sidecar is starting or gone stops inviting WebRTC attempts until it recovers. PWAs wait for WebRTC; other hosts may use a reachable WebSocket listener.

The sidecar also serves WebTransport, the phone app's direct connection on the same Wi-Fi (see Your phone on your home network). It listens on UDP, on the same port number as --peer-port, bound to --peer-host when that names one address. Allow that UDP port through the host's firewall. The host publishes its direct addresses automatically. Without a listener (--no-peer) it serves none. The log shows [WebTransport] Listening on UDP <port> (certificates …).

Failure handling is bounded. A sidecar that exits before authenticating or within a few seconds of spawning counts as a failed start; restarts back off (2 s, 4 s, ... 60 s) and after five consecutive failures the host stops retrying, logs [WebRTC] sidecar unavailable; continuing with WebSocket only, and keeps running. A sidecar that ran healthily and then died is restarted with the counter reset.

Scope on loopback: two headless hosts on one machine exercise the signaling path, the datachannel state machine, and sync over wrtc://; they do not exercise STUN/TURN or NAT traversal. If both sides dial at once, the device with the lexicographically smaller deviceId keeps its offer and the other answers it ([Sidecar] WebRTC glare ... in the logs). Without that rule each side dropped its own offer and the wrtc:// edge never formed.

When both transports work, headless prefers a WebSocket and can automatically move an existing WebRTC connection to it; see Devices.

What it does​

  • Calls initializePeerDevice with DBLocal (file or :memory:)
  • Encrypts secret persistent variables and decrypts them for the host features that use them, such as System HTTP credentials
  • Installs peers-core from the local bundle (S3 only when --services-url is not none)
  • Registers the Node isolated-package runtime
  • Captures console output into ConsoleLogs
  • Serves the same socket.io RPC and system contracts the CLI already uses, including System Packages: peers packages import, create, install, reload, and uninstall work exactly as on Electron. The provider lives in the Runtime (peers-device's packages); headless gives it plain Node filesystem and shell access. Remote-repo linking (linkRemoteRepo) is Electron-only because it needs git/gh
  • Listens for device connections (--peer-port, default 3341) and can dial explicit peers (--peer http://127.0.0.1:3342)
  • Registers the WebRTC sidecar as a second protocol manager when a peers-webrtc binary is found (see WebRTC); the sidecar itself lives in the Runtime (peers-device's WebRTCSidecar) and is shared with the desktop app
  • Dials devices it discovers, not only the ones on argv: a ws protocol manager lets NetworkManager connect to own devices found in the synced Devices table, peers learned from another device's network info, and group admins on join. Addresses come from Devices.serverUrl and from asking the target (get-ws-addresses over the mesh); the target answers with what it advertises: http://127.0.0.1:<peer-port> plus its LAN address, or the --advertise-url origins when given (hosts behind a reverse proxy or NAT). The desktop app does the same, advertising its LAN address on port 3333. Both dial a WebSocket before WebRTC and move a WebRTC connection up to a WebSocket once one connects (see Devices)
  • Device pairing on both sides: --pair as the signed-out new device (direct WebSocket transport), peers pair <code> as the signed-in approver
  • Logs unhandled promise rejections instead of exiting, like Electron's main process, so a peer disconnecting mid-sync cannot take the host down
  • One process, one user — spawn another process for a second device

Offline / test flags​

FlagPurpose
--files-dir <dir>Folder for the encrypted file-contents database, chunks.sqlite (default <db>/files). With --db :memory:, contents stay in memory unless you provide --files-dir. Contents older builds kept in <dir>/file_chunks are copied in at startup (peers files)
--services-url noneNo mailbox, no peers.app discovery
--register-servicesRegister with --services-url at startup and store the mailbox token (PEERS_REGISTER_SERVICES=1). Incompatible with --services-url none
--no-peerDo not listen for other devices
--peer-host 127.0.0.1Mesh listener on loopback only
--peer <url>Connect to a known peer (repeatable)
--advertise-url <url>Origin other devices dial to reach this listener instead of the detected addresses (repeatable)
--lan-scanScan the LAN for Electron peers on port 3333
--max-connections <n>Override the device connection cap (default 30). A testing knob: a small cap reproduces at-capacity shedding with a handful of devices (peers-e2e's cap.e2e.test.ts uses 4)
--webrtc-sidecar <path>Use this peers-webrtc binary instead of auto-detecting (PEERS_WEBRTC_SIDECAR is the same)
--no-webrtcNever look for or start the WebRTC sidecar; WebSocket edges only
--folder <groupId>=<absolutePath>[:ro|:rw]Grant a local directory at startup (repeatable). :ro is read-only; the default is readwrite. The same group and real path are reused on later startups. Headless has no folder picker. See System Local Folders.

Testing with it​

Multi-device scenarios live in peers-e2e; see End-to-end fleet testing. It spawns fleets of real headless processes (up to 100), wires them into a mesh over loopback, and drives each through its RPC socket, with per-device logs, mesh snapshots, and fault injection. npx peers-fleet up from that package stands up the same fleet detached for interactive or agent use.

peers-headless itself keeps only the spawn helpers and a runtime smoke suite. @peers-app/peers-headless exports spawnHeadlessProcess and runPeersCli: each spawned host is a separate process (in-memory SQLite, ephemeral ports, loopback mesh, --services-url none) that prints READY {json}; the CLI is pointed at it with --auth-file. Children run without NODE_ENV=test so the runtime behaves like a real device. Set PEERS_HARNESS_DEBUG=1 to mirror every child's output to the test's stderr. In peers-headless: npm test (unit + in-process smoke), npm run test:live (real hosts + CLI), npm run test:all.

For pairing, spawnPairingHeadlessProcess starts a --pair host against a given --services-url and resolves with its code (ready resolves with the READY payload once a source approves). There is no stand-in rendezvous any more: peers-e2e's pairing.e2e.test.ts runs the real peers-services as a fleet child and pairs two real headless processes through it.

Not yet​

  • UI / static file serving
  • peers:// protocol handling
  • Shipping the peers-webrtc binary with npx peers-headless (a platform-specific optional package or a release download); today you build it or point --webrtc-sidecar at one
  • Pairing over WebRTC: --pair still uses the direct WebSocket transport, so a headless destination needs a source that can reach one of its advertised URLs