wanderbooks/deploy/README.md

The books on a machine of your own

Plan 8.2 P9a, section 3.8. This is the recipe for the enforced deployment: the books live on a machine you control, in a folder only a dedicated account can read, and agents reach them through the server with a token. Locally the books are same_user (advisory) — hidden from the agent, not locked against it; here they are behind an account and a machine boundary.

Nothing here needs the owner's books: every step works on a copy.

The pieces:

• wanderbooks-server.service — the system unit (one account, one data root, loopback only).
• wanderbooks — the server-only build of the one executable (cargo build --release -p ledger-cli --no-default-features).
• Caddy (or Tailscale Funnel, or cloudflared) — TLS and the door from the internet.
• crates/ledger-cli/tests/two_user.rs — the two-account checks the CI job .github/workflows/two-user.yml runs, and which you can run on one machine (step 9).

1. The account and the folder

sudo useradd --system --create-home --home-dir /var/lib/wanderbooks \
             --shell /usr/sbin/nologin wanderbooks
sudo install -d -o wanderbooks -g wanderbooks -m 0700 /srv/wanderbooks
sudo install -m 0755 target/release/wanderbooks /usr/local/bin/wanderbooks
sudo install -D -m 0644 deploy/wanderbooks-server.service \
             /etc/systemd/system/wanderbooks-server.service

The executable is the server-only build: no viewer, no window libraries. On a Linux package install (P11) this is the same binary and the package manager writes the file; until then, copy it as above.

2. Make the data root, once

sudo -u wanderbooks -H /usr/local/bin/wanderbooks setup --root /srv/wanderbooks

setup makes the folder private (0700), records it for that account and asks for the owner passphrase when a terminal is attached. Self-host has no /h/ pages (D-28, D-51); the passphrase guards a format upgrade only. Set it at a terminal if the machine has none:

ssh -t you@server 'sudo -u wanderbooks -H /usr/local/bin/wanderbooks passphrase'

3. Bring the books over

The transport is a backup clone or a copied data folder (D-31: there is no fetch, and no separate archive verifier). On the machine the books are on now:

wanderbooks close                 # nothing writes while it is copied
wanderbooks books list            # note the id, e.g. acme
cp -a "$XDG_DATA_HOME/wanderbooks/books/acme" /media/usb/acme

The copy must hold the journal, the stored files, the vault and its key; cp -a of the book's folder holds all four. If you would rather move a verified backup, make one (wanderbooks books back-up acme) and clone the repository it wrote; both are the same books.

Bring that folder to the server, start the service, and adopt it:

sudo systemctl daemon-reload
sudo systemctl enable --now wanderbooks-server
sudo -u wanderbooks -H /usr/local/bin/wanderbooks books adopt /media/usb/acme \
     --root /srv/wanderbooks --id acme

The preview names the source's head (Head: event N (short hash)); with --yes (or a y at the prompt) the move is confirmed against exactly that head, so a source that changed after the preview is refused. The original is left as it was; nothing is deleted.

The head check. Ask the agent on the server for books.verify (or books.start): both report the head. Compare it with books.verify on the machine the books came from, taken before the move. They are the same event count, sequence number and hash: the move loses nothing. (The copy is written in this version's journal format; a source written by an older version gains one format event at adoption, and then the counts differ by exactly that event, which the preview says: "The copy is in this version's journal format".)

4. Keep the machine's hardening

The unit says --isolation enforced, so books.start reports service_user (enforced): the server is told, it never guesses. The unit also sets ProtectSystem=strict, NoNewPrivileges=yes, ProtectHome=yes and IPAddressDeny=any with IPAddressAllow=localhost, and no seccomp or Landlock lines (D-32, D-51).

The loopback-only rule is deliberate: the server reaches nothing out. A book whose backup target is a remote git repository needs that host allowed, or its backups fail:

# /etc/systemd/system/wanderbooks-server.service.d/backup.conf
[Service]
IPAddressAllow=203.0.113.10

A backup to a folder on this machine needs nothing. The tunnel and Caddy run as their own services and reach 127.0.0.1:7411, which the rule allows.

5. A token for each client

The token is a static bearer (wb_ and 32 random bytes); the server keeps only its SHA-256. Mint one per client, named for it:

sudo -u wanderbooks -H /usr/local/bin/wanderbooks token create \
     --root /srv/wanderbooks --book acme --name laptop
sudo -u wanderbooks -H /usr/local/bin/wanderbooks token print \
     --root /srv/wanderbooks --book acme --name laptop

token create keeps the text in the server account's OS keyring and token print shows it once; copy it to that client and nowhere else. Revoke it with token revoke --book acme --name laptop when a client is lost.

A headless machine has no Secret Service by default, and token create refuses to mint a token it cannot keep. Run the two commands inside a session that has one, for example:

sudo -u wanderbooks -H dbus-run-session -- sh -c '
  gnome-keyring-daemon --unlock --components=secrets >/dev/null
  /usr/local/bin/wanderbooks token create --root /srv/wanderbooks --book acme --name laptop
  /usr/local/bin/wanderbooks token print  --root /srv/wanderbooks --book acme --name laptop
'

The keyring lives only for that session, which is enough: the text is copied to the laptop, and the server checks the token's SHA-256 from the books, not from the keyring. (Making a token without keeping it anywhere is not a command; if your machine has a persistent Secret Service, use it.)

6. TLS and the door

The server listens on 127.0.0.1:7411 for the tunnel, and on its own Unix sockets for anything running as the same account. Put TLS in front of the loopback port. Two ways that need no open inbound port:

Tailscale Funnel (a tailnet name, TLS included):

sudo tailscale funnel --bg 7411

The books are then at https://<machine>.<tailnet>.ts.net/b/acme/mcp.

Caddy (a domain you own, automatic certificates):

books.example.com {
    reverse_proxy 127.0.0.1:7411
}

with cloudflared tunnel --url http://127.0.0.1:7411 instead of Caddy if you use a Cloudflare tunnel. Either way the path is passed through unchanged: the MCP endpoint is https://<host>/b/acme/mcp.

Nothing else listens. Do not forward 7411 on the router, and do not put the Unix sockets behind the proxy: they check the caller's account (3.9) and a proxy would hide it.

7. Point the agent at it

Claude Code (a client that sends headers):

claude mcp add --transport http wanderbooks-acme https://books.example.com/b/acme/mcp \
  --header "Authorization: Bearer <the token from step 5>"

Codex (~/.codex/config.toml; the token stays in the environment, not the file):

[mcp_servers.wanderbooks-acme]
url = "https://books.example.com/b/acme/mcp"
bearer_token_env_var = "WANDERBOOKS_ACME_TOKEN"

export WANDERBOOKS_ACME_TOKEN='<the token from step 5>'

The plan's local rule is that no client configuration holds a token (the bridge reads the keyring). For a remote machine there is no command yet that keeps a remote token in the client's keyring, so this recipe puts it in Claude's configuration (mode 0600) or in Codex's environment. That gap is recorded in plan/served.md 8.2 P9a's As-built block.

8. First start

Start a session and ask for books.start. It answers isolation: "service_user (enforced)", and every tool works over the TLS door with the token. Logs:

journalctl -u wanderbooks-server -f

The server runs no jobs in the background: serve holds the books open until systemd stops it. On a stop it finishes the call in progress, makes a last backup and closes (3.9), so TimeoutStopSec=600 is generous rather than needed.

Backups still run on their own, from the books' settings, as on the desktop (3.7, D-30, D-31); this machine runs git itself.

9. Prove the boundary (what CI runs)

.github/workflows/two-user.yml runs the same job on every change:

1. makes two accounts, wanderbooks (server) and the runner (agent);
2. makes books with this version in a desktop root, copies them, and adopts the copy into /srv/wanderbooks;
3. serves them as wanderbooks with --isolation enforced --http 127.0.0.1:17411, and mints a token;
4. runs crates/ledger-cli/tests/two_user.rs as the runner with WB_TWO_USER=1 and the deployment's settings. The test proves the runner cannot open /srv/wanderbooks or its journal, then reads, writes, uploads, files, exports and verifies over the HTTP door (in a second book, tunnel, so the moved books' head is never advanced), and compares the moved books' head with the source's.

agent_uid_cannot_read_tenant and self_host_adopt_same_head skip themselves when WB_TWO_USER is unset, so an ordinary cargo test on a laptop stays green; isolation_label_is_enforced_under_the_unit needs no second account and always runs.

On one machine without a second account, run the client side in a user namespace (a different user ID than the server's):

WB_TWO_USER=1 WB_TENANT_ROOT=... WB_SERVER_URL=http://127.0.0.1:17411 \
WB_BOOK=acme WB_TOKEN=... WB_WRITE_BOOK=tunnel WB_WRITE_TOKEN=... \
WB_SOURCE_DIR=... \
unshare --user --map-auto --setuid 0 --setgid 0 -- target/debug/deps/two_user-<hash> --nocapture

The two books and their tokens are made by the job (or by hand as in steps 2 to 5): acme is the moved books, and tunnel is empty, so the write checks never move acme's head. WB_SOURCE_DIR is the journal the books were moved from, readable by the agent account.