> ## Documentation Index
> Fetch the complete documentation index at: https://verifyngo.chocolatemoo53.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core config.json fields

> Configure listen address, upstream URL, cookie settings, trusted proxies, whitelist, default action, and path bypass rules in config.json.

verifyngo reads all of its settings from a single `config.json` file in the current directory. If you want to store the file somewhere else, pass the path with the `-config` flag when you start verifyngo (e.g. `-config /etc/verifyngo/config.json`). This page covers the core fields that control how verifyngo listens for incoming connections, where it forwards verified requests, and which requests skip the challenge entirely.

## Fields

**listen\_addr** `string`

The address and port verifyngo binds to. Change this if you need verifyngo to listen on a different interface or port — for example, `"0.0.0.0:8080"` to accept connections on all interfaces. A common value is `"127.0.0.1:8080"`.

**upstream\_url** `string` *required*

The URL of the service that verifyngo proxies verified requests to. Set this to the address your application is listening on, e.g. `"http://127.0.0.1:3000"`.

**cookie\_secret** `string` *required*

A secret value used to sign the verified cookie. Anyone who knows this value can forge verified cookies, so keep it private. Generate a strong value with:

```bash theme={null}
openssl rand -hex 32
```

**Never commit this value to source control.**

**cookie\_name** `string` (default: cp\_verified)

The name of the cookie that verifyngo sets in the visitor's browser after they successfully complete a CAPTCHA.

**cookie\_ttl** `string` (default: 168h)

How long the verified cookie stays valid before the visitor must complete the challenge again. Uses Go's duration format — valid examples are `"24h"`, `"48h"`, `"168h"`. Note that `"7d"` is **not** valid; use `"168h"` for 7 days instead.

**default\_action** `string` (default: challenge)

What verifyngo does when a request doesn't match any rule. Accepted values are:

* `"allow"` — let the request through without a challenge.
* `"challenge"` — show the CAPTCHA challenge page.
* `"deny"` — block the request outright.

**whitelist** `string[]`

A list of IP addresses or CIDR blocks that always bypass the challenge, regardless of rules or the default action. Useful for your own monitoring systems, internal tooling, or trusted partners.

```json theme={null}
"whitelist": ["203.0.113.10", "198.51.100.0/24"]
```

**bypass\_paths** `string[]`

A list of regular expressions matched against the request path. Any path that matches is proxied directly to the upstream without any challenge check — it won't count toward walk-away limits either. Set to `[]` to disable the bypass list entirely.

```json theme={null}
"bypass_paths": ["\\.(?:css|js|png|jpg|gif|svg|webp|woff2?)$"]
```

If you omit this field, verifyngo uses the built-in default list (see the note below).

**always\_pass\_paths** `string[]`

A list of regular expressions matched against the request path. Any path that matches is always allowed through, even if a rule would otherwise deny it. Use this for health-check or status endpoints that must remain reachable at all times.

```json theme={null}
"always_pass_paths": ["^/health$", "^/healthz$", "^/status$"]
```

**trust\_real\_ip** `boolean` (default: false)

When set to `true`, verifyngo reads the client's IP address from the `X-Forwarded-For` header instead of the direct connecting IP. Enable this when verifyngo sits behind another reverse proxy (such as nginx or Caddy) that sets this header.

**trusted\_proxies** `string[]`

A list of IP addresses or CIDR blocks that are trusted to supply an accurate `X-Forwarded-For` header. This field is only relevant when `trust_real_ip` is `true`. If your upstream proxy connects from a non-private, non-loopback address, you must list it here — otherwise verifyngo will warn you and fall back to trusting only loopback and private-range IPs.

```json theme={null}
"trusted_proxies": ["10.0.0.1", "172.16.0.0/12"]
```

> [!NOTE]
>
> When `bypass_paths` is omitted from your config, verifyngo uses a built-in default list that covers `favicon.ico`, `robots.txt`, `sitemap.xml`, `/.well-known/*`, common manifest files (`manifest.json`, `site.webmanifest`), `browserconfig.xml`, Apple touch icons, and all static asset extensions: `.css`, `.js`, `.mjs`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico`, `.woff`/`.woff2`, `.ttf`, `.otf`, `.eot`, `.wasm`, `.mp4`, and `.webm`. Requests to these paths never count toward walk-away limits.

## Minimal example

The following `config.json` shows the smallest set of fields you need to get verifyngo running with sensible defaults:

```json config.json theme={null}
{
  "listen_addr": "127.0.0.1:8080",
  "upstream_url": "http://127.0.0.1:3000",
  "cookie_secret": "replace-with-output-of-openssl-rand-hex-32",
  "cookie_name": "cp_verified",
  "cookie_ttl": "168h",
  "default_action": "challenge",
  "whitelist": ["203.0.113.10", "198.51.100.0/24"],
  "bypass_paths": [],
  "always_pass_paths": ["^/health$"],
  "trust_real_ip": false,
  "trusted_proxies": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.