Skip to content
Lattice PMLattice PM

Helper Replica

lattice helper run operates an always-on, least-privilege vault replica. A helper authenticates as a live vault member and serves existing signed revisions and resource chunks, but its membership key cannot author revisions, membership cutovers, conflict merges, mailbox deposits, or object-storage head publications.

A helper receives the repository and epoch secrets, opens the KDBX, and can read vault contents while running. It is an availability replica, not an untrusted-storage boundary. Use the separate encrypted object-storage service when the storage host must not decrypt vault contents.

Provisioning

Section titled “Provisioning”

Create and accept a normal file-based join, selecting the helper role when the admin approves it:

Terminal window
lattice vault invite personal --out personal.lattice-invite
lattice vault join personal.lattice-invite --out helper.lattice-join
lattice vault invite approve personal helper.lattice-join \
  --role helper --out helper.lattice-acceptance
lattice vault join accept helper.lattice-acceptance

Compare the pairing confirmation code out of band as usual. The helper can now start in recovery-required; the admin then transfers an exact authoritative baseline using the existing target-encrypted recovery workflow:

Terminal window
lattice vault members personal
lattice vault recover export personal <helper-device-id> \
  --out helper.lattice-recovery
lattice vault recover import personal helper.lattice-recovery \
  --confirm 0000-0000-0000-0000

The export runs on the admin device. The import runs on the helper. Transfer the package and confirmation code over separate channels. For a system service, stage the package in the service-visible recovery directory as described in docs/guide/daemon.md; ProtectHome=true and PrivateTmp=true intentionally hide normal home and temporary paths. This step installs the signed revision graph, rollback floors, resource payloads, KDBX materialization, and initialized-state evidence without letting the helper sign a bootstrap revision. A running helper imports through its local IPC endpoint and activates without a restart.

Start the helper in the foreground:

Terminal window
lattice helper run

All configured vaults must have local Helper membership and credentials available at process startup. KDBX key files remain local to the helper and may be supplied by config, a key-file path environment variable, or a systemd credential. A helper with pending or missing authoritative state remains available as recovery-required so the live import can complete; helper mode does not start with a locked credential cache. Local KDBX edits are ignored and never become signed state; if they prevent safe remote materialization, restore the helper from a new recovery export.

Concurrent branches require a writer-signed merge. A helper accepts and serves signed fast-forwards and membership cutovers but will not create the merge revision itself.

systemd

Section titled “systemd”

The packaged system unit uses the same private vault state as the normal daemon and conflicts with lattice.service:

Terminal window
sudo install -Dm0755 target/release/lattice /usr/bin/lattice
sudo install -Dm0644 packaging/systemd/lattice-helper.service \
  /etc/systemd/system/lattice-helper.service
sudo systemctl daemon-reload
sudo systemctl enable --now lattice-helper.service

Provide one LoadCredential=lattice-vault-NAME.password:/path/to/password drop-in per vault. The helper and normal daemon units must not run against the same state directory simultaneously.

For a user service without root access:

Terminal window
install -Dm0755 target/release/lattice ~/.local/bin/lattice
install -Dm0644 packaging/systemd/user/lattice-helper.service \
  ~/.config/systemd/user/lattice-helper.service
systemctl --user daemon-reload
systemctl --user enable --now lattice-helper.service

Enable user lingering separately when the helper must survive logout.