Signing in
How Prosody uses Caddy and Tailscale to admit your own devices without accounts or passwords.
Prosody has no user accounts and no login form. Instead, it relies on Tailscale to verify which device made each request.
How a request is checked
Your browser connects to Caddy over your tailnet.
Caddy sends a
forward_authsubrequest to Prosody's/authendpoint with the client's IP address inX-Prosody-Peer.Prosody asks the host's Tailscale daemon (
tailscaled.sock) which node owns that address.If the node is an untagged machine owned by the same Tailscale user as the host, Prosody returns
200with the machine's Tailscale name inX-Prosody-Device. Otherwise it returns403.Caddy copies
X-Prosody-Deviceonto the proxied request and forwards it to the app.
That device name is what appears under On the nightstand beside Last read on <device>, <date>.
Caddy configuration
Run Caddy directly on the host (or with host networking) so it can reach the relay on loopback:
prosody.example.com {
forward_auth 127.0.0.1:3023 {
uri /auth
header_up X-Prosody-Peer {remote_host}
copy_headers X-Prosody-Device
}
reverse_proxy 127.0.0.1:3023
}If you changed PROSODY_RELAY in .env, replace 127.0.0.1:3023 with your value.
X-Prosody-Peertells Prosody which client address to look up in Tailscale.copy_headers X-Prosody-Deviceoverwrites any header a browser might have sent. Requests without it are rejected.Do not expose the relay on a second hostname or port that bypasses
forward_auth, as anything reaching it directly could forgeX-Prosody-Device.
DNS and TLS
Point prosody.example.com at the host's Tailscale IP address, not its LAN IP. Requests arriving over a local network come from non-tailnet addresses and are refused.
Because the hostname only needs to resolve inside your tailnet, a DNS-01 challenge lets Caddy obtain a TLS certificate without opening any ports to the public internet.
Who is admitted
Prosody admits requests that meet both conditions:
The device belongs to the same Tailscale user as the host.
The device has no Tailscale tags.
Tagged nodes, devices shared from another tailnet and cross-site subrequests are refused. If you want to change who is admitted, docs/hosting.md in the repository points to the file that implements the rule.
Common refusal responses
| What you see | Cause and fix |
|---|---|
403 "Prosody admits only your own devices." | The request did not come from an untagged tailnet device owned by the host's user. Check that prosody.example.com resolves to the host's Tailscale IP (not its LAN IP) and that the client device is untagged. |
401 "Signed out" | The request reached the Api without X-Prosody-Device, meaning Caddy's forward_auth block was bypassed or misconfigured. |
| Refusals right after restarting Tailscale on the host | Brief and expected. The Api container checks /var/run/tailscale/tailscaled.sock every 10 seconds and Docker swarm replaces it automatically once the socket changes. |