Networking/tunnel footprint review: what does agentwire own, and should it?

[dotdevdotdev]

Umbrella: shed the service-router tunnel business

Owner-approved 2026-06-18. Review (comment) established: agentwire ships zero tunnel-provider code. The phone→portal "from anywhere" path is already 100% bring-your-own (cloudflared/tailscale, docs-only). The only "tunnel" code is an internal SSH service-router (agentwire tunnels * / tunnels.py) — outbound ssh -L port-forwards auto-spawned at portal startup to reach a service on another box. It only ever served remote-GPU TTS/STT, which is now unused (TTS default = browser/OS voice, STT default = in-process shim). It's inert on single-box installs.

Target posture

agentwire owns the portal's local security boundary (127.0.0.1 default, token-gated LAN opt-in, self-signed TLS — see #396) and SSH-based remote session management (machines list, /api/sessions/remote, ssh -t … tmux attach). It does not own internet exposure or service-routing tunnels — those are bring-your-own, documented but never code.

KEEP (untouched): portal bind/token/TLS (#396); machine add/remove/list; cross-machine sessions + remote terminal-attach (plain SSH, independent of tunnels.py).

Follow-ups

• Cut the SSH service-router auto-spawn — remove ensure_tunnels from portal startup (__main__.py:802); delete-vs-thin-helper for agentwire tunnels * / tunnels.py / network.py tunnel paths
• Reframe docs/wiki/deployment/remote-access.md as provider-agnostic BYO-tunnel guide; strip personal solodev.dev specifics; state agentwire ships no tunnel code
• Strip reverse-tunnel guidance (autossh -R, ~/.local/bin/agentwire-tunnels) from machine add/remove output — keep pure session management
• Scope network status / network_status to read-only diagnostics (decouple from tunnel management)
• Single "Exposing the portal" posture doc — what agentwire owns (local boundary) vs BYO (internet exposure), linked from quickstart

Verification

After the cut: a single-box portal starts with no auto-spawned ssh processes; cross-machine session listing + remote terminal-attach still work; docs state the BYO posture plainly.

[dotdevdotdev]

Networking/tunnel footprint review (audit-only — no code changes)

Read the actual code. Headline finding: agentwire ships zero tunnel-provider integration. There is no cloudflared/ngrok/tailscale code anywhere — grep -rE 'cloudflared|ngrok|tailscale' agentwire/ over non-.md, non-node_modules files returns only CORS-origin comments. The phone→portal tunnel that #295 markets and #396 wants to harden is already 100% bring-your-own — it exists only as documentation (remote-access.md walks you through your own cloudflared). The owner "sets up their own tunnel personally" is the current product.

What agentwire does own is two unrelated things that the word "tunnel" keeps conflating:

1. The portal's local security boundary (bind host + token + TLS) — the real attack surface.
2. An internal SSH service-router (agentwire tunnels *) — machine→machine ssh -L forwards to reach a service (TTS/portal) running on another box. Nothing to do with the any-device path.

Touchpoint inventory

#	Touchpoint	Code	What it actually is
A	agentwire tunnels up/down/status/check + MCP tunnels_up/down/status	tunnels.py (385 LOC) + network.py (206) + CLI handlers (~200)	SSH -L port-forward manager (create/track-PID/health/teardown) to reach remote services. Driven by services.<name>.machine. Auto-invoked at portal startup (ensure_tunnels, __main__.py:802).
B	agentwire network status + MCP network_status	__main__.py:6637	Read-only diagnostic: machine SSH reachability + service health + tunnel rows + worker sessions.
C	Portal bind/host/token/TLS	config.py (ServerConfig.host="127.0.0.1", token, SSLConfig), server.py	The actual boundary. 127.0.0.1 default; non-loopback bind requires ~/.agentwire/portal.token; self-signed TLS.
D	Remote-machine wiring	machines.json, machine add/remove/list (__main__.py:6007), MCP machine_add/remove/machines_list	SSH-based remote session management (name@machine). Legit core feature. But machine add prints autossh -M 0 -f -N -R 8765:... reverse-tunnel instructions; machine remove pkills autossh.* and references a ~/.local/bin/agentwire-tunnels startup script.
E	Tunnel-provider integration	none	Cloudflare/Zero-Trust is doc-only (remote-access.md). No code.

Key fact about A: get_required_tunnels() returns empty unless a service has .machine set and it's non-local. For the default single-box install, none of the tunnel machinery ever fires. It's only live in a multi-machine service split (e.g. remote-GPU TTS) — a scenario that got materially rarer now that STT default = in-process shim and TTS default = browser/OS voice. The remote-GPU-over-ssh -L case is increasingly vestigial.

Docs / where it's promised to users

• docs/wiki/deployment/remote-access.md — the big one. Cloudflare Tunnel + Zero Trust + SSH forwards + failsafe SSH/VNC. Hard-coded to the owner's personal solodev.dev domain throughout (ssh.solodev.dev, vnc.solodev.dev, agentwire.solodev.dev). This reads as product docs but is really the owner's personal runbook.
• docs/wiki/deployment/remote-machines.md — machine add/remove/list, portal UI flow.
• quickstart.md — L125-126 "Phone/LAN access needs server.host: 0.0.0.0 + certs + the portal token"; L205/207 link out to remote-machines + remote-access.
• gtm: launch spikes — write assets + pull the trigger (Show HN, X, r/ClaudeAI, ads) #295 launch copy — markets "Talk to your AI coding agents. From anywhere." but the honest under-a-minute path it sells is local Chrome, "no certs/GPU/models." The "from anywhere" is the hook, not the default setup. It also pre-commits to the "127.0.0.1-default → bearer-token-on-LAN-opt-in" model — which is C, already implemented.

Classification

Touchpoint	Verdict	Rationale
C — portal bind/token/TLS	KEEP (and it's the only thing #396 should harden)	This is serving HTTP securely, not "tunnel business." Real boundary.
E — Cloudflare/provider	already hand-off-to-user	No code to cut. Just reframe the doc.
remote-access.md	SCOPE-DOWN	Reframe as provider-agnostic BYO-tunnel reference (Cloudflare/Tailscale/ngrok — pick your own). Move solodev.dev personal specifics to owner's private notes. agentwire ships no tunnel code; the doc says so plainly.
A — agentwire tunnels * SSH router	CUT (or scope-down to a thin doc'd helper)	An SSH-process manager agentwire spawns at portal startup is exactly the "in the networking business" the owner wants out of. If a user splits services across machines, they BYO the forward (ssh -L/autossh) — same as they already do for the portal. Highest-value removal: drop ensure_tunnels at portal start so the portal never auto-spawns SSH processes.
B — network status	SCOPE-DOWN	Keep as read-only "is my stuff up" diagnostic (machine reachability + service health + sessions). Decouple from tunnel management (drop the create-missing coupling).
D — machine add/remove/list	KEEP, scope-down the print	Remote session mgmt is core and distinct from tunnels. Strip the autossh -R reverse-tunnel instructions and ~/.local/bin/agentwire-tunnels references from command output — that's networking the user should own.

Proposed target posture

agentwire owns the portal's local security boundary (127.0.0.1 default, token-gated LAN opt-in, self-signed TLS) and SSH-based remote session management. It does not own internet exposure or service-routing tunnels — those are bring-your-own, documented but never code.

The owner's instinct is correct and the codebase already 80% agrees: the marketed tunnel is already BYO. The work is to (a) stop auto-spawning SSH forwards (A), (b) make the docs state the BYO posture explicitly, and (c) narrow #396.

Overlap with #396 (coordinated)

This shrinks #396 substantially. #396 framed the job as hardening "any-device→tunnel→shell." Per this review:

• The tunnel segment is the user's tunnel — agentwire can't and shouldn't harden Cloudflare. agentwire's responsibility ends at "the portal refuses unauthenticated requests regardless of what's in front of it."
• Remote-access security hardening: audit + lock down the any-device→tunnel→shell path #396 should harden exactly C — bind default, token/bearer on non-loopback, per-device auth + command scoping, TLS. That's it.
• Remote-access security hardening: audit + lock down the any-device→tunnel→shell path #396 should not spend effort hardening A (agentwire tunnels *), because A is slated to be cut/scoped-down. Hardening it = the exact wasted work this issue was opened to prevent.

Recommend #396 be re-scoped to "portal auth/bind/TLS boundary" and explicitly de-scoped of the SSH service-router and any provider-tunnel wrapping.

Proposed follow-up issues (titles + one-line scope — NOT created)

1. Cut the SSH service-router auto-management — remove ensure_tunnels from portal startup; decide delete-vs-keep-as-thin-doc'd-helper for agentwire tunnels * / tunnels.py / network.py tunnel paths.
2. Reframe remote-access.md as provider-agnostic BYO-tunnel guide — strip personal solodev.dev specifics; state agentwire ships no tunnel code; list Cloudflare/Tailscale/ngrok as user-owned options.
3. Strip reverse-tunnel guidance from machine add/remove output — drop autossh -R next-steps and ~/.local/bin/agentwire-tunnels references; keep pure session-management.
4. Scope network status / network_status to read-only diagnostics — decouple from tunnel management.
5. Re-scope Remote-access security hardening: audit + lock down the any-device→tunnel→shell path #396 to the portal auth/bind/TLS boundary only — de-scope SSH service-router + provider-tunnel hardening; update the issue body.
6. Single "Exposing the portal" posture doc — one page stating what agentwire owns (local boundary) vs BYO (internet exposure), linked from quickstart.

— review only; no code touched in this pass.