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" }
]
}
| Field | Meaning |
|---|---|
userId, secretKey | The identity. secretKey is the current Ed25519 signing key; the X25519 encryption key is derived from it. |
dbSecret | The 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. |
previousPublicKeys | Public keys this identity used before, newest last, with when and why each was replaced. Informational; peers keys show prints it. |
rewrapFrom | Present 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:
--webrtc-sidecar <path>(orPEERS_WEBRTC_SIDECAR): use exactly this binary. If it does not exist the host logs one line and continues without WebRTC.- 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, thenpeers-webrtconPATH. --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
initializePeerDevicewithDBLocal(file or:memory:) - Encrypts secret persistent variables and decrypts them for the host features that use them, such as System HTTP credentials
- Installs
peers-corefrom the local bundle (S3 only when--services-urlis notnone) - 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, anduninstallwork exactly as on Electron. The provider lives in the Runtime (peers-device'spackages); headless gives it plain Node filesystem and shell access. Remote-repo linking (linkRemoteRepo) is Electron-only because it needsgit/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-webrtcbinary is found (see WebRTC); the sidecar itself lives in the Runtime (peers-device'sWebRTCSidecar) and is shared with the desktop app - Dials devices it discovers, not only the ones on argv: a
wsprotocol manager letsNetworkManagerconnect to own devices found in the syncedDevicestable, peers learned from another device's network info, and group admins on join. Addresses come fromDevices.serverUrland from asking the target (get-ws-addressesover the mesh); the target answers with what it advertises:http://127.0.0.1:<peer-port>plus its LAN address, or the--advertise-urlorigins 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:
--pairas 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
| Flag | Purpose |
|---|---|
--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 none | No mailbox, no peers.app discovery |
--register-services | Register with --services-url at startup and store the mailbox token (PEERS_REGISTER_SERVICES=1). Incompatible with --services-url none |
--no-peer | Do not listen for other devices |
--peer-host 127.0.0.1 | Mesh 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-scan | Scan 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-webrtc | Never 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-webrtcbinary withnpx peers-headless(a platform-specific optional package or a release download); today you build it or point--webrtc-sidecarat one - Pairing over WebRTC:
--pairstill uses the direct WebSocket transport, so a headless destination needs a source that can reach one of its advertised URLs