Guides

Networking, HTTPS & IT deployment

HTTP by design#

Pinman serves its API and web UI over plain HTTP on port 7466 (http://<machine>:7466), intended for localhost and trusted LAN use. 7466 is the default. Pinman also uses 7467-7470 locally; pinman system port <n> moves the whole block if any of them clash with something else on the machine. This is deliberate:

Pinman ships no certificates and no TLS configuration. Self-signed certificates can't be made trusted on the phones and laptops that connect to a machine without a manual root-CA install on every device — a poor experience that adds little real security on a home LAN.
On the machine itself, browsers treat http://localhost as a secure context, so features like PWA install work there with no certificate.
Your browser will show a "Not secure" label in the address bar when you connect from another device (http://<machine>:7466). That's expected — the browser is noting plain HTTP, not a pinman problem. It's a passive label, not a warning page, and it disappears behind either recipe below.
If you genuinely require HTTPS, add it in front of pinman with standard infrastructure — a reverse proxy or a VPN — using certificates and policy your IT already owns. Recipes below.

Threat model#

Pinman assumes a trusted local network: a home or venue LAN behind a router/firewall. Traffic between your phone/laptop and the machine is unencrypted HTTP on that LAN.

Do not port-forward pinman directly to the internet. For remote access or encryption in transit, use one of the recipes below.

Recipe 1 — TLS-terminating reverse proxy#

Run a reverse proxy on the machine (or a gateway host) that speaks HTTPS to clients using your certificate, and plain HTTP to pinman on localhost.

Caddy (simplest)#

machine1.example.com {
    reverse_proxy localhost:7466
}

Caddy obtains and renews certificates automatically (internal CAs work too, via tls internal or explicit cert paths).

nginx#

server {
    listen 443 ssl;
    server_name machine1.example.com;

    ssl_certificate     /etc/ssl/certs/machine1.crt;
    ssl_certificate_key /etc/ssl/private/machine1.key;

    location / {
        proxy_pass http://localhost:7466;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

IIS (Windows)#

Use Application Request Routing (ARR) + URL Rewrite:

Install the ARR and URL Rewrite modules.
Bind your certificate to a site on port 443.
Add a reverse-proxy rewrite rule targeting http://localhost:7466/{R:1}.
In ARR proxy settings, enable proxying and preserve the host header.

Notes for all proxies#

Point the proxy at http://localhost:7466 on the machine running pinman.
Forward X-Forwarded-Proto (and X-Forwarded-For) headers.
Behind an HTTPS proxy the browser sees a secure context again — PWA install and other secure-context features return automatically; no pinman configuration is needed.
If the proxy is the only intended entry point, firewall port 7466 to localhost (or the proxy host).

This keeps cipher policy, certificate lifecycle, client certificates, and WAF rules entirely in IT's hands — pinman needs no TLS settings at all.

Recipe 2 — VPN / Tailscale#

For remote access without exposing anything publicly:

Tailscale (or a similar WireGuard-based mesh): install it on the machine and on your phone/laptop, then reach the machine at its tailnet address from anywhere. With Tailscale HTTPS (tailscale cert / Tailscale Serve), the machine gets a real, publicly-trusted certificate for its tailnet name — which also restores full secure-context/PWA behavior in browsers, with zero pinman configuration.
Traditional VPN (WireGuard/OpenVPN/IPsec on your router or corporate concentrator): once tunneled onto the LAN, use pinman exactly as at home — http://<machine>:7466.

Quick chooser#

Need	Answer
Home/venue LAN use	Nothing to do — `http://<machine>:7466`
Encryption in transit on an untrusted/shared LAN	Reverse proxy (Recipe 1)
Org policy requires HTTPS with corporate PKI	Reverse proxy with IT's certificates (Recipe 1)
Remote access from outside the network	VPN / Tailscale (Recipe 2)
PWA install on remote devices	Either recipe (both restore a secure context)
Public internet exposure	Don't — use a VPN