Skip to content

docs: README network interfaces and ports - #113

Merged
chaodu-agent merged 2 commits into
mainfrom
docs/network-surface
Nov 14, 2026
Merged

chaodu-agent merged 2 commits into
mainfrom
docs/network-surface

Conversation

@chaodu-agent

@chaodu-agent chaodu-agent commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

What changed

Adds a "Network interfaces and ports" section to the README (after Auth, plus a Contents link). Docs only. It covers listening sockets, outbound connections, what the app never does, how to expose it, and macOS versus Linux differences.

Version: the app version on main is 0.12.0 and the latest release is v0.11.0 (.agents versions.txt agrees). The README describes main, not the release.

How the facts were established

  • Code read at main (33911d3): MCPHTTPEndpoint.swift, AuthPolicy.swift, main.swift, FirstRunSetup.swift, AttachManager.swift, ReverseAttachClient.swift, Switchboard.swift, UpstreamMCP.swift, scripts/install-prebuilt.sh, scripts/install-linux.sh, poc/reverse-attach-linux/src/{http,auth,attach}, plus greps for UDP, Unix sockets and extra listeners. Nothing was built or run.
  • Read-only observation on a test Mac agent (0.10.1) and a bare 0.12.0 launch on a laptop. Observed sockets (names redacted):
LISTEN       127.0.0.1:8795   agent MCP HTTP server (loopback only)
ESTABLISHED  127.0.0.1:8795 <- 127.0.0.1:<ephemeral>   x2, local clients (peer not identified)
LISTEN       127.0.0.1:8794   Playwright MCP (node child), agent upstream "browser"
No UDP, no Unix sockets, no non-loopback listener.
tailscale serve status: https://<host>.<tailnet>.ts.net:8444 (tailnet only) -> http://127.0.0.1:8795
Laptop 0.12.0, no flags: LISTEN 127.0.0.1:8795 only.

Differences between code and observation

  1. Observed agent is 0.10.1, code is 0.12.0.
  2. The switchboard is configured on the observed agent but no socket to it was visible at the snapshot. Unexplained.
  3. No agent-to-8794 connection seen (agent idle). No live evidence of the dial.
  4. Code says Playwright is a separate LaunchAgent. The observed 8794 listener appeared as a child node process. Parentage unconfirmed. The README says "separate process the app only connects to".
  5. Other apps' paths on the tailnet :443 are unrelated and left out.
  6. poc/pw-mcp/install.sh maps tailnet :8443 to 8794 with no token. Not seen on the test Mac. Now documented in the README as a PoC installer mapping, separate from the app's sockets (review fix).
  7. Two loopback clients on 8795 (probably the tailscaled serve proxy). Left out.

Not verified

Identity of the loopback clients, whether the switchboard socket is up, who starts Playwright on the test Mac, 0.12.0 behaviour under an installed LaunchAgent, anything on Linux (not run), and a non-loopback --host (never run). Linux and IPv6 are labelled "not verified" in the README.

Lint

npx markdownlint-cli2@0.17.2 README.md with the repo config: 0 errors. CI's job globs only docs/**/*.md, so it does not lint the README.

Update (review fix): added the :8443 row and off command, Linux Wayland client socket and Playwright unit, the upstream URL wording, and auth qualified as the installer default.

Ran: PATH=~/.nvm/versions/node/v22.20.0/bin npx markdownlint-cli2@0.17.2 README.md
(repo .markdownlint-cli2.jsonc) -> Summary: 0 error(s). Note CI globs only docs/**/*.md.
Facts from .agents/tasks/readme-network/facts.md (code at main 0.12.0 plus a read-only
observation of a macmini agent, 0.10.1). No build run.
…ream, auth)

Ran: PATH=~/.nvm/versions/node/v22.20.0/bin npx markdownlint-cli2@0.17.2 README.md
(repo .markdownlint-cli2.jsonc) -> Summary: 0 error(s). CI globs only docs/**/*.md.
Findings checked against code before editing:
- poc/pw-mcp/install.sh:36 (serve --https=8443 -> 127.0.0.1:8794), pw-mcp.sh:9: added 8443 row, no auth, off command.
- poc/reverse-attach-linux/src/platform/linux/seat.rs:23,252,330: Wayland UnixStream client, scoped never-list to macOS.
- scripts/install-linux.sh:19,91,130,146,155: Linux Playwright unit, MCP_UPSTREAM, --no-browser.
- main.swift --upstream takes any URL; AuthPolicy checks only configured items: qualified.
LOW: --path, IPv4 loopback, probe bind, app-process scope. No build run.
@chaodu-agent
chaodu-agent merged commit 7acb69c into main Nov 14, 2026
9 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant