Ports & Firewalls

The short answer: one port in, nothing else in, and every outbound path opt-in. Nodes and clients dial the control plane; the control plane never dials anything on its own. A node opens no port at all, and that is what makes nodes work behind NAT, on laptops, and on machines with no public address.

Listening

The bind address is HOST, default 0.0.0.0 (all interfaces, IPv4). That default is why the origin allowlist exists: anything that can reach the port can knock, and the allowlist decides which browser origins get answered. tmux, which actually runs the panes, communicates over local Unix sockets and opens nothing.

The built-in TRUSTED_ORIGINS default carries two localhost Vite ports (5174 and Vite's default 5173) so a development browser session can sign in; they name no listener until one is started.

Test ports are listed so you can ignore them: the Playwright suite boots its own backend on 3199 (fake registry 3198, onboarding fixture 3200), and the CLI end-to-end suite uses 31996–31999 with throwaway homes. None of it touches :3080, and none of it runs outside a test.

Outbound, derived from code

What the control plane reaches for, and the switch each path answers to:

What a node reaches for is shorter still:

• Its control plane: one WebSocket to the configured address (wss:// when the plane is HTTPS). This is the only connection the node keeps, and it is always outbound.
• Its own updates only: subshell update reads the same release list directly from its own SUBSHELL_RELEASE_URL (default GitHub) because a node key can do nothing on the plane's REST API, and empty disables it, leaving --from. When the plane drives the update instead, the node downloads from the plane itself over a single-use token: the URL inside the signed command names the control plane's own download route, so an update the browser started adds no outbound destination on the node.

What your firewall actually needs

For a plain LAN install: allow the machines that need to reach Subshell to reach the control plane's port, and nothing else in either direction. Nodes need no inbound rule; clients are just browsers. If you reach the plane over a mesh network (Tailscale and friends), "the port" is the address the mesh gives the host; see Networking for which spellings of it a browser may use.

What each feature you enable adds:

• Update fetching / artifact fetching (server and nodes): outbound TCP 443 from each host that updates to the release source you configured.
• Registry plugin installs: outbound TCP 443 from the control-plane host to the registry.
• A network plugin: whatever that vendor's client needs (most mesh daemons need outbound 443 plus their discovery/relay traffic). It changes which address the one port is reachable at; it never adds a listening port for Subshell itself. A Cloudflare Tunnel is the unusual shape, an outbound-only connection to Cloudflare's edge, which is why it needs no port forward, and why it counts as public exposure.
• Push notifications: outbound TCP 443 to the push services. None of it is payload-bearing beyond what Notifications documents.

Reverse proxies change the address, not the port arithmetic: terminate TLS wherever you like and send it to the one port, then name the public origin in APP_BASE_URL / TRUSTED_ORIGINS so the browser checks agree.

See also

• Networking: HOST vs APP_BASE_URL vs the origin allowlist.
• Running as a Service: what binds the port, and the pane-safety of restarting it.
• Docker: the published port and the bind that breaks proxies.
• Environment Variables: SERVER_PORT, HOST, SUBSHELL_RELEASE_URL.
• Security Model: the trusted-network posture this page presumes.

Edit on GitHub