`app.proxy`

When `true`, Koa trusts proxy headers such as `X-Forwarded-For` and `X-Forwarded-Proto` to determine the real client IP and protocol.

Since Koa 2 Spec ↗

Syntax

app.proxy = true | false

Parameters

Name	Type	Required	Description
`value`	`boolean`	Yes	Set to `true` when the app runs behind a trusted reverse proxy (nginx, AWS ALB, Cloudflare, etc.). Defaults to `false`.

Returns

void — Setter; returns nothing.

Examples

import Koa from 'koa';

const app = new Koa();
app.proxy = true;

app.use(async (ctx) => {
  // ctx.ip now reflects X-Forwarded-For, not the proxy socket IP
  ctx.body = { ip: ctx.ip, secure: ctx.secure };
});

app.listen(3000);

Output

{"ip":"203.0.113.42","secure":true}

Notes

Only enable when you control the proxy and trust it to set the forwarded headers correctly. Enabling this on an app directly exposed to the internet allows clients to spoof their IP address. You can also pass `{ proxy: true }` to the `Koa` constructor.