docs(fleet): start the broker from a keychain-unlocked session on macOS

[kjgbot]

Follow-up to #63. Adds the one failure mode that cost the most time bringing a second machine online, and that the guide does not currently mention.

The problem

Workers inherit the security session of the process that spawned them. A broker started from a session with a locked login keychain hands every worker a locked keychain, so any harness storing credentials there fails:

Error: Your macOS login keychain is locked.
error: resolve delegated relayfile credentials: mint delegated relayfile
       credentials: http 401 unauthorized: Unauthorized

cursor-agent and the RelayFile CLI both hit this.

Why it is easy to misdiagnose

Three properties, all now documented:

1. Unlocking in the macOS GUI does not unlock it for SSH. Separate security sessions.
2. Unlocking in one SSH session does not carry to the next.
3. agent-relay does not need the keychain. agent-relay status and agent-relay workspace active keep working while cursor-agent and relayfile fail — so a healthy agent-relay is not evidence the keychain is available.

That third one is what makes the 401 so misleading: it reads as an authentication or account problem, and the natural response is to re-run a device login. The credential was already present the whole time; it was sitting in a keychain the session could not read.

What this adds

• Section 3: an unlock-then-start sequence in one interactive session (ssh -t is required so security can prompt), plus a note that set-keychain-settings clears the idle timeout but cannot survive a reboot without storing a password somewhere it should not be.
• Troubleshooting: an entry naming both the keychain error and the 401, with security show-keychain-info as the check, and the point that unlocking in a separate session will not fix an already-running worker — the broker has to be restarted.

Documentation only.

🤖 Generated with Claude Code

https://claude.ai/code/session_017Ld4S9gUGzTjhVhbtX9cTd

---

Note

Low Risk
Documentation-only changes with no runtime, security, or data-handling code impact.

Overview
Documentation-only update to the fleet setup guide for a macOS pitfall when bringing nodes online: workers inherit the broker’s security session, so a broker started with a locked login keychain breaks harnesses that read Keychain credentials (cursor-agent, RelayFile) with misleading auth-style errors while agent-relay itself still looks healthy.

Adds §3 subsection with unlock-then-start steps (ssh -t, security unlock-keychain, set-keychain-settings, then agent-relay node up), notes on GUI vs SSH sessions and post-reboot warnings, plus a Troubleshooting entry linking to that section—emphasizing that fixing keychain in another SSH session does not heal running workers and that relayfile 401s should be checked with security show-keychain-info before re-auth.

^{Reviewed by Cursor Bugbot for commit f2d5eda. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: fde0a622-33e3-42e4-97cd-aeedeb0baa05

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview deployed!

Environment	URL
Web	https://4d1d7da0-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.