Repository navigation
docs: add verified multi-machine fleet setup guide - #63
Merged
Merged
Conversation
Contributor
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Advanced Run ID: 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. Comment |
Contributor
|
Preview deployed!
This is a Cloudflare Workers preview version of this PR's build. |
kjgbot
added a commit
that referenced
this pull request
Sep 9, 2026
…OS (#64) 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. Claude-Session: https://claude.ai/code/session_017Ld4S9gUGzTjhVhbtX9cTd Co-authored-by: kjgbot <kjgbot@agentrelay.dev> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adding a second fleet machine can trip operators on old npm globals, broker naming, and connection discovery. This adds a Guides group to the existing Relay navigation and publishes Adding a machine to a multi-machine fleet at
/docs/fleet-setup.The guide covers installation, enrollment into the existing Cloud workspace, explicit broker startup, connected status, spawning into a separate lane, attaching, and releasing the smoke worker. It retains the permanent setup traps: npm-global PATH shadowing, the installer's invalid
agent-relay uphint, human-name collisions, spawn discovery from the broker root, and STOPPED status with orphaned processes. Troubleshooting also covers expired harness authentication and disk reclamation.The verified fleet harness list is
codex,claude,cursor-agent,grok,gemini, anddroid. Relaycast guidance is limited to registration at startup and retrying if registration fails. Creating the broker root's.agentworkforce/relaymarker before enrollment prevents project discovery from walking up to the home directory.Validation:
upcommand, STOPPED status without metadata, and spawn discovery independent of--cwd.Live enrollment, fleet spawning, shutdown, and OAuth login were verified through help/source rather than exercised against production. No existing brokers or global installs were changed. No deployment or merge performed.
Note
Low Risk
Documentation and navigation only; no runtime, auth, or application code changes.
Overview
Adds a new Guides section to the docs sidebar and publishes Adding a machine to a multi-machine fleet at
/docs/fleet-setup.The guide is an end-to-end operator walkthrough for a second fleet machine: install and PATH/binary checks, Cloud enroll into the existing workspace,
agent-relay node upwith an explicit broker name, connected status verification, and a cross-fleet smoke test (spawn, attach, release). It documents v11.10.4 CLI behavior and common setup traps (npm-global shadowing, invalidagent-relay upquickstart, human-name collisions, spawn cwd vs broker root, STOPPED with orphaned processes), plus troubleshooting for harness OAuth refresh and disk reclamation.Reviewed by Cursor Bugbot for commit 5edbf9b. Bugbot is set up for automated code reviews on this repo. Configure here.