docs(serve): note the macOS Application Firewall requirement for the front door

[steipete]

Docs-only follow-up to #2789.

The serve SSH front door listens in the crabbox process itself. On macOS hosts with the Application Firewall enabled, that binary must be allowed to accept incoming connections. Notarized release builds qualify automatically under the default "allow downloaded signed software" setting. Locally built binaries, including Developer ID-signed but unnotarized ones, are blocked silently: the agent registers and leases provision, but clients on other machines time out waiting for the SSH transport. This was found during the #2789 production live test, where Gatekeeper reported the test build as "Unnotarized Developer ID". Same-host connections are not filtered.

No code, worker, or behavior changes. Verified with node scripts/check-docs-links.mjs.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge.

What this changes

This PR documents macOS firewall permission requirements and recovery steps for the serve SSH front door.

Example: A Mac runs a local crabbox build with its firewall enabled and the serve front door on TCP port 2222.

• Before: The reachability documentation does not explain why remote SSH connections can time out despite successful provisioning.
• After: The documentation directs the operator to allow the crabbox executable in Firewall Options.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Useful, narrowly scoped documentation with one low-impact factual overstatement.
Proof confidence	🌊 off-meta tidepool	Not applicable: This documentation-only PR changes no runtime behavior; its reported live-test observation supplies context rather than proof of a universal macOS policy.
Patch quality	🐚 platinum hermit (4/6)	1 actionable review finding remain.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Mac operators can see successful agent registration and provisioning while remote SSH connections time out because the executable lacks firewall permission.
Reason: The maintainer-authored follow-up supplies a concrete recovery path at the relevant networking instructions without adding configuration or changing runtime behavior.

Merge readiness

⛔ Needs changes before merge - 1 item remains

Keep open: this maintainer-authored documentation follow-up addresses a real troubleshooting gap absent from main, with one narrow factual correction.

Priority: P3
Reviewed head: 44e8471cdf35ad692c38c0a35e909b4eee709ec5

Before merge

• Qualify the claim that unnotarized local builds are always blocked (P3) - A locally built executable that is already permitted by the firewall is reachable, and Apple's documented automatic allowance depends on a valid certificate-authority signature, not an unconditional distinction between notarized releases and unnotarized local builds. The categorical statement can therefore send operators with an already-allowed build toward an unnecessary exception or binary replacement. Describe these builds as potentially requiring explicit permission, or scope the observed failure to the tested macOS version and policy. See Apple's firewall settings contract.

Findings

• [P3] Qualify the claim that unnotarized local builds are always blocked — docs/providers/serve.md:198-200

Agent review details

How this fits together

The serve agent accepts remote SSH connections in the crabbox process and forwards authorized connections to container SSH endpoints on loopback.

flowchart LR
  Client[Remote Crabbox client] --> Firewall[macOS Application Firewall]
  Firewall --> FrontDoor[Crabbox SSH front door]
  Coordinator[Coordinator assignments] --> FrontDoor
  FrontDoor --> Container[Container SSH on loopback]

Loading

Technical review

Best possible solution:

Keep the executable-specific firewall recovery instructions and describe local-build blocking as conditional on the host's effective firewall policy.

Do we have a high-confidence way to reproduce the issue?

Source confirms the process that owns the listener; the reported macOS timeout was not independently reproduced during this read-only documentation review.

Is this the best way to solve the issue?

The warning belongs beside the existing single-port reachability instructions, but one observed unnotarized-build failure should not become a universal firewall rule.

Full review comments:

• [P3] Qualify the claim that unnotarized local builds are always blocked — docs/providers/serve.md:198-200
  A locally built executable that is already permitted by the firewall is reachable, and Apple's documented automatic allowance depends on a valid certificate-authority signature, not an unconditional distinction between notarized releases and unnotarized local builds. The categorical statement can therefore send operators with an already-allowed build toward an unnecessary exception or binary replacement. Describe these builds as potentially requiring explicit permission, or scope the observed failure to the tested macOS version and policy. See Apple's firewall settings contract.
  Confidence: 0.9

Overall correctness: patch is correct
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 0e9437c383e4.

Provenance checked

• Single-port SSH reachability documentation keeps the original intent (d44ae16: feat(serve): single-port SSH front door for served leases #2789 introduced one agent-owned SSH port per machine while retaining container SSH endpoints on loopback.)

Security

None.

Evidence

Acceptance criteria:

• node scripts/check-docs-links.mjs
• git diff --check

What I checked:

• Pinned documentation addition: The introduced diff adds only the ten-line macOS firewall paragraph; the fetched main documentation lacks that guidance. (docs/providers/serve.md:194, 44e8471cdf35)
• Production listener owner: The agent calls startFrontDoor with its advertised address and SSH port; startFrontDoor opens the TCP listener within the agent process. (internal/providers/serve/frontdoor.go:106, 0e9437c383e4)
• Apple firewall contract: Apple describes automatic access for downloaded software in terms of a valid certificate authority signature, rather than a blanket notarization requirement: Change Firewall settings on Mac.
• Recorded motivation and related implementation: The PR body reports a cross-machine timeout during live testing of feat(serve): single-port SSH front door for served leases #2789; that merged PR deliberately moved incoming SSH connections into the agent process. (d44ae1681fff)
• Repository policy and inspection limits: Read the complete root AGENTS.md; no nested documentation AGENTS.md or maintainer-notes directory exists. No helper, second reviewer, build, or test ran. Older-content history inspection encountered unavailable local objects; the pinned diff, main documentation, listener source, and relevant commit metadata were readable. (AGENTS.md:1, 44e8471cdf35)

Likely related people:

• Peter Steinberger: Raw commit d44ae16 adds docs/providers/serve.md:177 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: d44ae1681fff; files: docs/providers/serve.md)

Labels

Label changes:

• add P3: This is focused troubleshooting documentation for an advanced CLI hosting workflow, with no runtime change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Label justifications:

• P3: This is focused troubleshooting documentation for an advanced CLI hosting workflow, with no runtime change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 12, 2026, 3:13 PM ET / 19:13 UTC.