From f2d5eda9f341ff8c2bfeefab6a4285ac73b1bedc Mon Sep 17 00:00:00 2001 From: kjgbot Date: Wed, 9 Sep 2026 12:48:51 +0200 Subject: [PATCH] docs(fleet): start the broker from a keychain-unlocked session on macOS Workers inherit the security session of the process that spawned them, so a broker started from a locked-keychain session hands every worker a locked keychain. Any harness that stores credentials in the Keychain then fails -- cursor-agent and the RelayFile CLI both do. The failure is easy to misdiagnose for three reasons, all documented here: - unlocking the keychain in the macOS GUI does not unlock it for SSH; they are separate security sessions - unlocking in one SSH session does not carry to the next - agent-relay itself does not need the keychain, so `agent-relay status` and `agent-relay workspace active` keep working while cursor-agent and relayfile fail with what look like auth errors ("http 401 unauthorized") Adds the unlock-then-start sequence to section 3 and a troubleshooting entry that names the 401 explicitly, so the next operator does not spend an afternoon re-logging in to fix a credential that was already present. Follow-up to #63. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017Ld4S9gUGzTjhVhbtX9cTd --- web/content/docs/fleet-setup.mdx | 70 ++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/web/content/docs/fleet-setup.mdx b/web/content/docs/fleet-setup.mdx index ba50bb19..e3ccae5d 100644 --- a/web/content/docs/fleet-setup.mdx +++ b/web/content/docs/fleet-setup.mdx @@ -119,6 +119,54 @@ Do not remove the human identity to make room for the broker. The broker registers with Relaycast on start. If registration fails, retry. +### macOS: start the broker from a keychain-unlocked session + +On macOS, start the broker from a session where the login keychain is unlocked. +Workers inherit the security session of the process that spawned them, so a +broker started from a locked session hands every worker a locked keychain. + +This matters for any harness that stores credentials in the Keychain — including +`cursor-agent` and the RelayFile CLI. They fail with errors that look like +authentication problems but are not: + +```text +Error: Your macOS login keychain is locked. +error: resolve delegated relayfile credentials: mint delegated relayfile + credentials: http 401 unauthorized: Unauthorized +``` + +Three properties make this easy to misdiagnose: + +- Unlocking the keychain in the macOS GUI does **not** unlock it for SSH. They + are separate security sessions. +- Unlocking it in one SSH session does not carry to the next one. +- `agent-relay` itself does not need the keychain, so `agent-relay status` and + `agent-relay workspace active` keep working while `cursor-agent` and + `relayfile` fail. A working `agent-relay` is not evidence that the keychain is + available. + +Unlock and start the broker in a single interactive session. `ssh -t` is +required so `security` can prompt: + +```bash +ssh -t mini-node-2 +security unlock-keychain "$HOME/Library/Keychains/login.keychain-db" +security set-keychain-settings "$HOME/Library/Keychains/login.keychain-db" +cd "$HOME/fleet/mini-node-2" +agent-relay node up --no-spawn --background --broker-name mini-node-2 +``` + +`set-keychain-settings` with no flags clears the idle timeout and the +lock-on-sleep behaviour, so the keychain stays unlocked while the machine is up. +It does not survive a reboot — nothing can, without storing the password +somewhere it should not be. + + + After a reboot, repeat this before starting the broker. A broker that + auto-starts unattended will be in a locked session, and every worker it spawns + inherits that. + + ## 4. Verify the node is connected ```bash @@ -257,6 +305,28 @@ the original task and working directory. During the observed fleet setup, Claude sessions needed this intervention; Codex and Cursor sessions stayed authenticated. That observation is not a guarantee that their credentials cannot expire. +### A worker fails with "login keychain is locked" + +```text +Error: Your macOS login keychain is locked. +Run security unlock-keychain and try again. +``` + +The broker was started from a session with a locked keychain, and the worker +inherited it. Unlocking the keychain now in a separate SSH session will not fix +the running worker — the broker has to be restarted from an unlocked session. +See [Start the broker from a keychain-unlocked +session](#macos-start-the-broker-from-a-keychain-unlocked-session). + +The same cause produces `http 401 unauthorized` from `relayfile status`. Check +the keychain before treating that as an authentication or account problem: + +```bash +security show-keychain-info "$HOME/Library/Keychains/login.keychain-db" +``` + +A locked keychain reports `User interaction is not allowed.` + ### The machine runs out of disk space **Symptom:** Installs, builds, worktree creation, or agent startup fail with