Reverse proxy

When Stravia is behind an HTTPS terminator, the Server can recover the public request origin from forwarding headers sent by its trusted immediate TCP peer. Configure the direct proxy address and an exact management origin; neither setting is a substitute for proxy API authentication or CORS configuration.

Minimum configuration

The Server defaults to 127.0.0.1:23471. For a proxy on the same machine, bind it to loopback and trust that direct peer:

stravia-server \
  --host 127.0.0.1 \
  --port 23471 \
  --data-dir <data-directory> \
  --trusted-proxy 127.0.0.1 \
  --admin-origin https://your-domain.example

--trusted-proxy accepts the proxy's immediate TCP peer IP or CIDR; it does not mean an arbitrary upstream client address. --admin-origin must be the exact management origin, including scheme and any non-default port. Omitted --trusted-proxy trusts no forwarding peer; omitted --admin-origin leaves management-origin restriction unrestricted. Repeat either option for multiple values. Their environment variables are STRAVIA_TRUSTED_PROXIES and STRAVIA_ADMIN_ORIGINS.

Prerequisites

Terminate public HTTPS at a proxy whose direct TCP address is stable and restrict the Server listener to that proxy. Choose the exact public management origin before setting --admin-origin.

For a trusted peer, Stravia uses one X-Forwarded-Proto (http or https) and one X-Forwarded-Host value as origin metadata. Do not send Forwarded; Stravia rejects it on the management-entry path. X-Forwarded-For is not part of this management-origin decision and is not required by this guide.

Nginx example

This example assumes Nginx and Stravia share a host, Nginx connects over loopback, and HTTPS terminates at Nginx. Replace the hostname, certificate paths, and Server port for your deployment.

server {
    listen 443 ssl;
    server_name your-domain.example;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://127.0.0.1:23471;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header Forwarded "";
    }
}

Disabling buffering and cache allows streaming responses to pass through; proxy_read_timeout should match the expected longest interval without upstream data for your workload. Nginx must send X-Forwarded-Proto and X-Forwarded-Host consistent with the public origin configured in --admin-origin.

If the proxy is not on the same host, set --trusted-proxy to the actual direct TCP peer address or narrow CIDR and restrict network access to the Server listener accordingly. Do not copy the loopback trust value for a remote proxy.

Origin policy scope

--admin-origin applies to the management-entry routes such as setup, login, and settings. Health endpoints and the /v1, /v1beta, and /mcp API namespaces bypass this management-origin gate and use their own behavior/authentication. This setting does not configure API-key authorization, proxy API CORS, TLS, or firewall rules.

Before setup is complete, /readyz may return 503; that is not proof the reverse proxy is misconfigured. After setup, verify access to the management UI and perform an authenticated test request using the protocol you intend to expose. Do not depend on specific log message text as a configuration check.

Troubleshoot proxy requests

If the management UI rejects a request, confirm the direct TCP peer matches --trusted-proxy, the proxy sends one X-Forwarded-Proto and one X-Forwarded-Host, and the resulting origin exactly matches --admin-origin. Health and API routes bypass this management-origin gate and should be diagnosed under their own authentication behavior.

Next steps

Review Storage and Databases for persistence planning. Use Diagnostics when investigating a real failed request.