feat: federated peers via tailcat (no Tailscale account) - #6401
Merged
Conversation
Operators can paste a tc… address in Instances to start a local tailcat forward (15555→5555 by default) and register a loopback peer. Includes install/forward lifecycle, boot restore, docs, and tests. Closes #6400
atomantic
reviewed
Sep 6, 2026
atomantic
left a comment
atomantic
left a comment
Owner
There was a problem hiding this comment.
Reviewed and updated this PR directly with follow-up commits 315c0568f and 4ccffeb27.
Resolved findings:
- Wait for the tailcat listener-ready message instead of treating a short-lived process as ready; terminate startup failures and timeouts.
- Keep repeated/split bearer-capability diagnostics and child errors out of API errors and logs.
- Roll back the child and peer when persisting its restart mapping fails, without retrying the failed mapping write during rollback.
- Preserve the managed loopback port and host selection when a remote peer announces itself; limit forward cleanup to tailcat peers and propagate cleanup failures.
- Regenerate the API route catalog and replace the new form fixture's address with a reserved documentation address so the privacy guard passes.
Validation: focused server/client regression tests and production client build passed locally. All Linux, Windows, client, database, CI Gate, and Full CI Gate jobs passed for 4ccffeb27b53b0fb2b80a5adb05a1462cad4bc1c: https://github.com/atomantic/PortOS/actions/runs/34051075046. GitHub reports CLEAN / MERGEABLE. No remaining blocking findings from this review. A real two-install tailcat smoke test was not performed.
Left open for merge as requested.
This was referenced Sep 7, 2026
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.
Summary
tc…address in Instances → Add Peer without a Tailscale account.15555 → remote 5555(PORTS.TAILCAT_FORWARD/DEFAULT_TAILCAT_LOCAL_PORT); if 15555 is busy, the next free loopback port is used.tailcat(PATH orgo install), manages forward lifecycle, persists mappings in machine-localdata/tailcat-forwards.json, and restores them on boot.Closes #6400
Security / privacy
tc…addresses are never logged, never returned on peer records to the UI/peers, and never appear in docs/tests (placeholders only:<tcADDR>/tcEXAMPLE…).serve-all, no exit-node.Docs
docs/features/tailcat-peers.md— feature note + copy/paste Grok Bot / agent sandbox setup guidedocs/PORTS.md,docs/STORAGE.mdupdatesTests
server:services/tailcatPeer.test.js,lib/ports.test.js(18 passed)client:src/pages/Instances.test.jsx(5 passed)Test plan
tc…address in Instances → Tailcat address; confirm peer at127.0.0.1:15555(or next free port)