Multi-Hoster-Upload/docs/remote-diagnostics-setup.md

Remote Diagnostics Setup (read-only)

This guide explains how to let Claude Code run read-only diagnostics against a Multi-Hoster-Uploader instance running on a remote Windows server, through the local stdio MCP gateway in gateway/.

The gateway is an MCP server to Claude and a WebSocket client to a diagnostic agent inside the app. It never touches the screen, never injects input, and never writes anything on the server.

---

1. Enable diagnostics on the server and copy the code

On the server (the machine running the app):

1. Open the app's Settings.
2. Enable "Diagnose-Zugriff".
3. Copy the connection code. It looks like mhu1_<base64url...>.

The code carries the host, port and a one-time auth token (mhu1_<base64url{v,h,p,t,n}>). The bridge dials the host from the code, so you usually just hand over the code. Treat the code as a secret: anyone with the code and network reach to the agent can read diagnostics.

Two visibility modes (Settings → Diagnose-Zugriff → Sichtbarkeit):

• Nur lokal (default): the agent binds to 127.0.0.1. Reach it through a tunnel (next step).
• Im Netzwerk: the agent binds to 0.0.0.0 but is gated by a fail-closed IP allowlist — only source IPs/CIDRs you list may connect (loopback is always allowed), in addition to the token. An empty allowlist means loopback only. This is the mode to use with Tailscale: set the allowlist to your tailnet (e.g. 100.64.0.0/10) and put the server's Tailscale IP / MagicDNS name into the code address — then the bridge connects straight over the tailnet, no SSH forward needed.

Transport note: the agent speaks plaintext ws://. The token and the diagnostic data are not encrypted on the wire by the agent itself — confidentiality comes from the tunnel (Tailscale/WireGuard/SSH) you reach it through. In network mode the IP allowlist + token are the access gate; only bind to the network behind a private tunnel you trust (a tailnet, a VPN, or a trusted LAN). (A future build may add wss/TLS with cert pinning via an fp field in the code; it is not active today.)

---

2. Reach the agent over a tunnel

The agent's default port is 9110. Pick the path that matches your setup.

Tailscale (recommended for many servers)

Put every server and your gateway machine on the same tailnet. On each server, set Sichtbarkeit = Im Netzwerk, allowlist your tailnet (100.64.0.0/10, or the specific Tailscale IPs you'll connect from), and set the code address to that server's Tailscale IP or MagicDNS name. The bridge then connects straight to <tailscale-name>:9110 — WireGuard (Tailscale) encrypts the transport, and the allowlist + token gate access. No SSH forward, no per-session tunnel command.

SSH local port-forward (keep the agent loopback-only)

With Sichtbarkeit = Nur lokal:

ssh -L 9110:127.0.0.1:9110 user@server

Leave that session open. Now 127.0.0.1:9110 on your machine is forwarded to the server's loopback. The code address is 127.0.0.1 (your local end of the tunnel).

WireGuard (manual, alternative)

Bring up a WireGuard tunnel and either bind the agent to the network with the peer's WG IP in the allowlist, or forward loopback over the tunnel and connect to 127.0.0.1.

In Nur lokal mode the agent is unreachable except through a tunnel to loopback. In Im Netzwerk mode the fail-closed IP allowlist (plus the token) is the access gate — only bind to the network behind a tunnel/VPN you trust (a tailnet, WireGuard, or a trusted LAN). The transport is plaintext; the tunnel is what encrypts it.

---

3. Install the gateway and register it with Claude (one time)

On the machine running Claude Code:

cd gateway
npm install

Register the gateway as an MCP server (one time):

claude mcp add --transport stdio mhu-diag -- node "C:\Users\ploet\Desktop\Claude Projekte\multi-hoster-uploader\gateway\index.js"

Adjust the absolute path if your checkout lives elsewhere.

---

4. Usage

With the tunnel up, tell Claude:

server prod-3 at 127.0.0.1, code mhu1_<...>

Claude will:

1. call connect_server(code:"mhu1_...", host:"127.0.0.1"),
2. immediately read the app version via get_system_info,
3. remember the server under its label in registry.json.

Next time you can just say:

connect_server(label:"prod-3")

with no code — the gateway dials it from the registry. Then ask Claude "what's wrong?" — it will typically start with server_health, the one-shot hub that aggregates errors, queue, rotation and system info in a single call. Other read-only tools: read_log, list_logs, list_errors, get_queue_state, get_history, get_config_redacted, get_rotation_state, get_app_events.

---

5. Failure → meaning

When a connect or a request fails, the gateway returns a human-readable cause. Quick reference:

Symptom / signal	What it means / what to do
ECONNREFUSED	app not running / wrong port / inbound firewall closed
ETIMEDOUT	firewall DROP / NAT not forwarded / tunnel down
close code 4001	auth timeout, retry
close code 4002	stale or rotated code — re-copy the current code from the server
close code 4003	brute-force lockout, wait 60s
connected but no auth-ok	old app version without the diagnostic agent — update that server
wss fingerprint mismatch	reserved for the future TLS mode (not active today) — re-copy the code

If you tunnel and still get ECONNREFUSED, check that the SSH session is up and that the agent is actually listening on 127.0.0.1:9110 on the server (Diagnose-Zugriff enabled).

---

6. What this is — and is not

• It is READ-ONLY. It reads logs, errors, queue/history, redacted config, rotation and system info. No screen capture. No input injection. No writes or config changes.
• The code is a secret (it carries the auth token). Don't paste it into public channels.
• gateway/registry.json stores tokens for remembered servers and is git-ignored — never commit it.