LAN vs TLS proxy

By the end of this page you have made the one decision every deployment makes — how the connection is protected — and applied it. The daemon binds 127.0.0.1:8137 by default: loopback only, nothing to decide. The moment you want other machines to reach it, you must also say how the traffic is protected. A 0.0.0.0 bind without an answer refuses to boot rather than serve auth tokens and pairing secrets unencrypted by accident:

bind address 0.0.0.0 without TLS would expose auth tokens and pairing
secrets as cleartext on the network — front the daemon with a
TLS-terminating reverse proxy and set --trusted-proxy, or accept
cleartext on a trusted network with --allow-insecure-lan

Which one?

	Cleartext LAN	TLS reverse proxy
Fits	A home network or lab you trust end to end	Anything beyond that: shared offices, VPS, internet-reachable hosts, teams
Traffic	`http://` / `ws://`, readable to anyone on the network path	`https://` / `wss://`, encrypted to the proxy
Extra moving parts	None	A reverse proxy (Caddy or nginx) and a domain name
Daemon bind	`0.0.0.0`	Stays on `127.0.0.1` when the proxy runs on the same machine
Extension, desktop, CLI clients	Work from any machine on the network	Work from anywhere the domain resolves
The served web app in a browser	Only on the server’s own machine, at `http://127.0.0.1:8137/`, or through an SSH tunnel to it	From any browser, at `https://<your-host>/`
Claiming the server	On the server itself, with no setup code	From any browser, with the setup code from `ohd status`

Tokens are required on every non-loopback connection in both postures — the decision is about encryption on the wire, not about whether auth exists. The web-app row is the browser’s rule, not the daemon’s: the Workbench needs crypto.subtle to mint its identity, and browsers withhold it on plain-HTTP origins that are not loopback, so a LAN URL like http://<server>:8137/ loads and then refuses to start. It binds the served web app alone — the extension and desktop app speak ws://<server>:8137 in either posture, which is why a headless server with no browser on it is a perfectly ordinary deployment.

Option A — cleartext on a trusted LAN

An explicit acknowledgment that cleartext on a trusted network is acceptable:

ohd install --bind-address 0.0.0.0 --allow-insecure-lan
ohd restart        # a running daemon keeps its old bind until restarted

ohd status lists the LAN join URLs the running daemon actually answers at. If clients still cannot connect, check that the host firewall (ufw/firewalld) admits port 8137 — the daemon logs every connection it refuses, so a client that fails while the log stays silent never reached the process at all. The daemon warns at boot as a standing reminder of the posture:

serving cleartext HTTP/WS on all interfaces (allowInsecureLan) — auth
tokens and pairing secrets are readable by anyone on the network path;
use a TLS-terminating reverse proxy for anything beyond a trusted LAN

Undo it any time with ohd install --no-allow-insecure-lan and a restart.

Option B — TLS terminated at a reverse proxy

TLS is reverse-proxy-first: terminate wss:// at Caddy or nginx and forward plain ws:// to the daemon on loopback. The daemon stays bound to 127.0.0.1 when the proxy runs on the same machine — only the proxy is reachable from outside.

ohd install --trusted-proxy --allowed-host oh.example.com
ohd restart

Two flags, two jobs:

--trusted-proxy makes auth logs, rate limits, and the claim’s loopback test use the client address the proxy appends to X-Forwarded-For instead of the proxy’s own — without it a proxy on the same machine would make every remote browser look local and the setup code would gate nothing. Never set it without a proxy in front — clients could then spoof the header.
--allowed-host admits the proxy’s domain on the browser-facing routes. IP addresses, localhost, and mDNS *.local names always work; any other hostname — a reverse-proxy domain, an intranet name — must be declared, or its requests are refused.

Caddy (automatic certificates; WebSocket upgrades and X-Forwarded-For are handled by default):

oh.example.com {
    reverse_proxy 127.0.0.1:8137
}

nginx:

server {
    listen 443 ssl;
    server_name oh.example.com;
    ssl_certificate     /etc/ssl/oh.example.com.crt;
    ssl_certificate_key /etc/ssl/oh.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:8137;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Clients then dial wss://oh.example.com with a paired token, exactly like a LAN join.

Switching later

Both postures persist through daemon.json, so switching is a re-install plus restart — for example, from cleartext LAN to a proxy:

ohd install --bind-address 127.0.0.1 --no-allow-insecure-lan --trusted-proxy --allowed-host oh.example.com
ohd restart

Existing tokens keep working; clients just dial the new URL.

Server

Run it

Operate it

Which one?

Option A — cleartext on a trusted LAN

Option B — TLS terminated at a reverse proxy

Switching later

​Which one?

​Option A — cleartext on a trusted LAN

​Option B — TLS terminated at a reverse proxy

​Switching later

Which one?

Option A — cleartext on a trusted LAN

Option B — TLS terminated at a reverse proxy

Switching later