Dashboard

What Is a Reverse Proxy? Why Your App Hides Behind One

A reverse proxy sits in front of your app and forwards requests to it. Here is a working nginx config and the three failures AI-generated setups usually hit.

Cecilia Iona
Cecilia Iona
Senior Editor, AI & Product
28 October 20261 min read

A reverse proxy is a server that sits in front of your app, accepts requests from the internet, and passes them on to your app behind it. Visitors talk to the proxy. The proxy talks to your app and relays the answer back. Nginx, Caddy, Traefik and the routing layer inside most hosting platforms are all reverse proxies.

If you built your app with AI and deployed it to a plain server, you will meet one sooner or later, because your app probably listens on port 3000 and browsers expect ports 80 and 443.

What a reverse proxy actually does

A normal ("forward") proxy acts on behalf of the user, for example a company network that filters what staff can visit. A reverse proxy acts on behalf of the server. The visitor never learns which machine or port really handled the request.

In practice that gives you four jobs in one place:

  • One public door. Port 443 serves several apps. / goes to the website, /api goes to the backend.

  • TLS in one spot. The proxy holds the certificate, so your app speaks plain HTTP on the inside. This is how HTTPS usually reaches an app that knows nothing about certificates.

  • Protection. The app is not exposed directly, and you can cap request sizes and connections before they reach your code.

  • Buffering and compression. The proxy can absorb slow clients so your app is not tied up waiting on them.

A working nginx config

Here is the smallest useful config for an app listening on port 3000 on the same machine:

nginx
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The server_name is where DNS points. Everything inside location / exists because of a failure someone hit. The next section maps each one.

Three failures and the line that fixes each

1. 502 Bad Gateway: the proxy cannot reach the app

A 502 means the proxy answered but the thing behind it did not. The usual cause in AI-generated deploys is the app listening on the wrong address. A dev server started with defaults often binds to localhost only, which is fine on a laptop and wrong inside a container, where the proxy reaches it over a different network address. Check three things in order: is the app running, which address and port is it bound to, and does proxy_pass point at exactly that. Our guide to the 500-family errors covers reading the app side of this.

2. The redirect loop: X-Forwarded-Proto

Your app often redirects HTTP to HTTPS. Behind a proxy, the app only ever sees plain HTTP from the proxy, so it concludes every request is insecure and redirects forever. The fix is the X-Forwarded-Proto header, which tells the app the original scheme, plus a setting in your framework that says to trust it. Without the header line above, you get the loop. Without the framework setting, you get the loop anyway.

3. Dead websockets and streaming

A websocket starts life as a normal request that asks to upgrade. Two header lines (Upgrade and Connection) carry that request through, and proxy_http_version 1.1 is required for the handshake. The nginx documentation lists the defaults and the buffering behaviour in its proxy module reference. If chat messages or live updates work locally and stall after deploy, this is the first place to look. The tradeoffs between the two approaches are in WebSockets vs polling.

Timeouts the proxy adds without telling you

The nginx documentation gives proxy_read_timeout a default of 60 seconds, measured between two successive reads from the app, not for the whole response. A slow AI call that sends nothing for a minute gets cut off by the proxy even though your app is still working. Raise the value deliberately for long routes, and prefer fixing the slow route to raising it everywhere.

Do you need to set one up yourself?

Often not. Managed platforms put a reverse proxy in front of your app for you, which is why the same app can work there and break on a rented server. If you are on a platform, you configure it through dashboard settings. If you are on your own server, you write the config above. The decision between the two is part of deploying an app built with AI, and the broader picture sits in the guide to building an app with AI.

A proxy is also the natural place for rate limiting, since it sees every request before your code does. For a mental model of what is different between your laptop and the live site, see why an AI-built app works locally but fails after deploy.

Frequently asked questions

What is the difference between a proxy and a reverse proxy?

A proxy represents the client and hides users from servers. A reverse proxy represents the servers and hides them from users. Mozilla's proxy server glossary entry describes both.

Is a reverse proxy the same as a load balancer?

A load balancer is a reverse proxy that spreads requests across several copies of an app. A reverse proxy in front of a single app is the simpler case.

Why do I get 502 Bad Gateway behind nginx?

The proxy could not get a valid response from your app. The app is stopped, bound to a different address or port, or crashing on start. Check the app's own logs first.

Do I need nginx, or will Caddy do?

Either works. Caddy obtains certificates automatically and has shorter config files, which suits small projects. Nginx is more common and better documented for unusual cases.

How did this land?

About the author

Cecilia Iona
Cecilia Iona

Senior Editor, AI & Product

Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.

Share

Get the next post in your inbox

One email a month. Product updates, engineering posts, and the best of Built with Swarmz.

I agree to receive emails about AI building tips and Swarmz product news. Unsubscribe any time.