HTTPS and networking

The normal layout is:

clients → HTTPS :443 → Caddy → HTTP 127.0.0.1:7770 → vsync-server

Create a DNS record such as builds.example.com pointing at the VPS. Allow ports 80 and 443 through the firewall, but do not allow public access to port 7770.

Caddy configuration

builds.example.com {
    reverse_proxy 127.0.0.1:7770
    request_body {
        max_size 256MB
    }
}

Reload Caddy and verify the public endpoint:

sudo systemctl reload caddy
curl https://builds.example.com/healthz

Caddy obtains and renews the TLS certificate automatically when DNS and ports 80/443 are correct.

The proxy is the security boundary: Vsync decides admin cookie security and, when email is disabled, builds invite links from the Host and X-Forwarded-Proto headers it receives. Emailed links use the configured public_url. Caddy makes the headers trustworthy by construction - it only forwards requests whose Host matches the site, and it sets X-Forwarded-Proto itself, ignoring the client's. If you use a different proxy, it must do the same: route or reject by Host, and overwrite X-Forwarded-Proto rather than passing the client's value through.

Private-network alternative

For a server that must not be reachable from the public internet, place the server and every client on a private network such as Tailscale. Bind Vsync to the private interface and use the private address as VSYNC_SERVER.

Authentication is still required. If you use plain HTTP on a trusted private network, remember that the desktop updater and browser security features may still require HTTPS for their own endpoints.

Connection checks

Every server serves a self-service connection check at /diag: latency, jitter, and throughput measured against this server over the same transfer path a sync uses. The page runs anonymously - handy for people who have no account or CLI yet.

Anonymous public checks share an hourly transfer budget. Signed-in checks and direct private-network checks are not metered. This classification relies on the documented proxy layout, so keep the plain-HTTP port private and overwrite X-Forwarded-Proto at the proxy.

Webhooks

When webhook is configured, the server posts build publications to that incoming webhook, naming the stream the build went into. Treat the webhook URL like a credential: limit who can read the server configuration and rotate the URL if it leaks.