Reverse proxy and HTTPS
Put your own reverse proxy and TLS in front of a self-hosted Skilder.
Pilot release. Self-hosting Skilder is a pilot.
The bundled proxy service serves plain HTTP on SKILDER_HTTP_PORT and holds no certificate. HTTPS comes from a reverse proxy or load balancer that you run in front of it and that terminates TLS. Set PUBLIC_URL to its https origin (The public URL).
Before you start
- Point a DNS name at the machine that runs your reverse proxy. It is the host of
PUBLIC_URL, for exampleskilder.example.com. With Caddy's automatic certificates, the name must also reach the machine from the internet on ports 80 and 443. - Move the bundled proxy off port 80, which your reverse proxy needs, and close its port to everything but your reverse proxy: it serves plain HTTP, Docker publishes it on every interface, and Docker bypasses host firewalls such as
ufw. Where your reverse proxy runs on the same machine, outside a container or in one on the host network, setSKILDER_HTTP_PORT=127.0.0.1:8080in.envso the port listens on that machine only. Otherwise setSKILDER_HTTP_PORT=8080, or any other free port, and close it in the firewall of the network, such as a cloud security group. Rundocker compose up -d proxyto apply it.
What your proxy must do
| It must | Because | Without it |
|---|---|---|
| Send every path to the bundled proxy, at one address | /, /api, /mcp and /.well-known/ share one origin, and the bundled proxy routes them. Authorization servers also fetch <PUBLIC_URL>/api/oauth/client-metadata.json from the internet, so keep it public. | The paths you route elsewhere do not work. |
Upgrade websockets: forward Upgrade and Connection | The app's live data runs over a websocket at /api/graphql-ws. | The app stays on Loading workspace.... |
Pass /mcp and /api/chat responses on as they arrive, and wait up to an hour for them | The MCP endpoint streams. It sends a keepalive comment every 15 seconds on an idle stream, and answers each request as a stream. /api/chat streams Studio's answers, and sends nothing while a tool call runs, however long it takes. | A buffering proxy withholds what the server sends on an idle stream. A proxy that waits less than a tool call takes cuts the answer, and Studio shows a network error. nginx waits 60 seconds by default. |
| Accept request bodies of at least 101 MB | Files upload up to 100 MB. | Your reverse proxy answers 413 to any file above its own limit. nginx's default is 1 MB. |
Set X-Forwarded-For to the client's address, not to what the client sent | The bundled proxy takes the member's address from it once you trust your proxy. | Every member shares your reverse proxy's address. |
Redirect HTTP to HTTPS and send Strict-Transport-Security | Browsers then keep to HTTPS. | Members can reach the app over plain HTTP. |
Skilder reads every public URL from PUBLIC_URL, never from a request. The Host and X-Forwarded-Proto headers change nothing, and both examples below send them anyway.
Trust your proxy
Without SKILDER_TRUSTED_PROXIES, every member arrives from your reverse proxy's address and shares one rate limit, sign-in included. Name only your reverse proxy.
- Open
https://skilder.example.com/in a browser. - Run
docker compose logs proxy. Each access log line starts with an address, the one the bundled proxy sees your reverse proxy at. Where your reverse proxy reaches the published port from the same machine, it is the gateway of the Compose network, the first address ofSKILDER_SUBNET:172.20.0.1by default. Docker can relay other clients from that address too, so trust it only with the port closed as in Before you start. - Set
SKILDER_TRUSTED_PROXIESto that address in.env, or to the subnet of a load balancer whose addresses change, and rundocker compose up -d proxy.
Each access log line then starts with the member's own address.
Example configurations
Two complete configurations, each doing everything in What your proxy must do. Pick the one for the proxy you run, or adapt it to another. Both assume:
- the reverse proxy runs on the same machine as Skilder, with
SKILDER_HTTP_PORT=127.0.0.1:8080in.env; - your name in place of
skilder.example.com.
Caddy
Caddy gets and renews the certificate, redirects HTTP to HTTPS, upgrades websockets, passes streams on as they arrive and sets no body limit. It also sends X-Forwarded-For with the client's address, plus X-Forwarded-Proto and Host. The Caddyfile adds the HSTS header and names the upstream:
skilder.example.com {
header Strict-Transport-Security "max-age=63072000"
reverse_proxy 127.0.0.1:8080
}Start Caddy 2 with it. In a container, keep /data on a volume so the certificate survives, and start it with --network host: 127.0.0.1:8080 is then this machine's loopback, and Caddy listens on its ports 80 and 443.
nginx
Run nginx 1.30.7 or a later 1.30 release, 1.31.9 or later, or a distribution package with the fix backported. Versions 1.9.5 to 1.30.6 and 1.31.0 to 1.31.8 let a client run code on the machine as root over HTTP/2. If you cannot update yet, leave http2 off your listen lines and remove any http2 on; line, as in the example below.
Put your name in both server_name lines and your certificate files at the two ssl_certificate paths. A port 80 block still naming skilder.example.com loses to nginx's default site, which answers 404 instead of redirecting:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name skilder.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name skilder.example.com;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
add_header Strict-Transport-Security "max-age=63072000" always;
client_max_body_size 101M;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
location / {
proxy_pass http://127.0.0.1:8080;
}
location /mcp {
proxy_pass http://127.0.0.1:8080;
proxy_buffering off;
proxy_read_timeout 1h;
}
location /api/chat {
proxy_pass http://127.0.0.1:8080;
proxy_buffering off;
proxy_read_timeout 1h;
}
}Run nginx -t, then nginx -s reload.
Check it works
Run these once Skilder is started:
curl -sI http://skilder.example.com/ | head -n 1
curl -sI https://skilder.example.com/ | grep -i strict-transport-security
curl -s https://skilder.example.com/.well-known/oauth-protected-resource/mcp
curl -s https://skilder.example.com/api/oauth/client-metadata.jsonThe first answers a redirect to the https address, and the second prints the HSTS header. The third prints JSON whose resource is https://skilder.example.com/mcp, and the fourth JSON whose client_id is its own address. Then connect an agent: it signs in and asks you to approve over the same https address.

