Skip to Content
Skilder

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 example skilder.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, set SKILDER_HTTP_PORT=127.0.0.1:8080 in .env so the port listens on that machine only. Otherwise set SKILDER_HTTP_PORT=8080, or any other free port, and close it in the firewall of the network, such as a cloud security group. Run docker compose up -d proxy to apply it.

What your proxy must do

It mustBecauseWithout 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 ConnectionThe 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 themThe 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 MBFiles 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 sentThe 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-SecurityBrowsers 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.

  1. Open https://skilder.example.com/ in a browser.
  2. 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 of SKILDER_SUBNET: 172.20.0.1 by default. Docker can relay other clients from that address too, so trust it only with the port closed as in Before you start.
  3. Set SKILDER_TRUSTED_PROXIES to that address in .env, or to the subnet of a load balancer whose addresses change, and run docker 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:8080 in .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:

Caddyfile
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:

/etc/nginx/conf.d/skilder.conf
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.json

The 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.

On this page