DOCS · DEPLOYMENT

Serve Cortex over HTTPS with nginx

If nginx already fronts services on your server, Cortex can sit behind it cleanly. Keep Cortex bound to 127.0.0.1:7331, terminate TLS at nginx, and forward the original host and scheme to Cortex.

Start Cortex in explicit proxy mode

cortex --listen 127.0.0.1:7331 \
  --trust-proxy \
  --public-origin https://cortex.example.com

Reverse proxy

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name cortex.example.com;

    ssl_certificate     /etc/letsencrypt/live/cortex.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cortex.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7331;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

The forwarded scheme matters for secure Cortex session cookies and Google OAuth callback URLs. Cortex ignores forwarding headers by default. In explicit proxy mode it accepts a single forwarded scheme and client address only from its direct loopback peer; remote peers and ambiguous chains fail closed. The configured public origin pins Host, secure-cookie, OAuth callback and same-origin behavior.

HTTP redirect

server {
    listen 80;
    listen [::]:80;
    server_name cortex.example.com;
    return 301 https://$host$request_uri;
}

Use your normal certificate workflow, such as Certbot, to provision and renew the certificate. Test the nginx configuration before reloading it.

Long-running agent requests

Cortex streams agent activity while work is running. The configuration above disables proxy response buffering and gives long-running requests a generous read timeout so the proxy does not make an active coding session appear stalled or terminate it prematurely.

Keep the backend private.The recommended setup leaves Cortex on its default loopback listener and exposes only nginx on ports 80 and 443. Cortex is a high-authority development service; do not unnecessarily publish port 7331 alongside the reverse proxy.

WebSockets

The Upgrade and Connection headers are included for proxy compatibility with WebSocket endpoints. nginx does not forward these hop-by-hop headers automatically, so they must be supplied explicitly when WebSocket tunnelling is needed.

More about nginx

See the nginx documentation for HTTP proxying and WebSocket proxying.