> For the complete documentation index, see [llms.txt](https://docs.bountysecurity.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bountysecurity.ai/burp-bounty-server/configuration.md).

# Configuration reference

Look up CLI flags, environment variables, limits and logging defaults.

Run the binary with `--help` for its flag descriptions. CLI options use Go flag syntax, including `--history=false` for a false boolean and durations such as `168h`.

## Listener, MCP and startup limits

| Flag                  | Default     | Meaning                                                                                                                                        |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ip`                | `localhost` | Main listener address. Use a local interface address or `0.0.0.0` to listen on all IPv4 interfaces.                                            |
| `--port`              | `8081`      | Main REST/MCP port.                                                                                                                            |
| `--mcp`               | `false`     | Mount `/mcp` and approval endpoints; does not disable REST.                                                                                    |
| `--profiles-dir`      | Unset       | Direct directory of catalogue `.bb` files; validated when specified.                                                                           |
| `--mcp-allow-targets` | Empty       | Comma-separated hosts automatically approved by the MCP workflow. Others wait for approval.                                                    |
| `--scan-concurrency`  | `50`        | Initial shared in-flight request limit before scan budgets take effect.                                                                        |
| `--scan-rps`          | `0`         | Initial shared request rate; zero is unlimited.                                                                                                |
| `--update`            | `false`     | Apply an available executable update from the platform's Server channel, then exit.                                                            |
| `--update-profiles`   | `false`     | Install/update the official catalogue from `server-profiles-stable` into `--profiles-dir`, then exit. Stop servers using that directory first. |
| `--debug`             | `false`     | Detailed REST/MCP diagnostics and debug-level per-scan logs.                                                                                   |

The two `--scan-*` flags are **initial caps**, not immutable administrative ceilings. New scans use their submitted budgets. With omitted scan settings the current bootstrap uses **concurrency 10**, **RPS 200** and **payload strategy `only_once`**. The strictest budget among live scans, including paused scans, governs the shared server limit. There is no automatic aggregate cap across separate server processes.

## Persistent findings

| Flag                           | Default                                                | Meaning                                                                    |
| ------------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `--history`                    | `true`                                                 | Enable retained summaries and finding evidence.                            |
| `--history-dir`                | OS user config directory + `burpbounty-server/history` | Durable storage, outside temporary logs; one running server per directory. |
| `--history-max-bytes`          | `2147483648` (2 GiB)                                   | Quota, including atomic-write temporary files.                             |
| `--history-max-issue-bytes`    | `33554432` (32 MiB)                                    | Maximum uncompressed retained issue size.                                  |
| `--history-evidence-retention` | `168h` (7 days)                                        | Evidence retention after completion.                                       |
| `--history-summary-retention`  | `720h` (30 days)                                       | Scan and finding summary retention.                                        |

Quota must be at least 1 MiB. The issue limit must be positive and no larger than the quota. Evidence retention must be at least one second and must not exceed summary retention. These bounds do not limit temporary scan logs or the source profile directory.

## Logging

| Flag                | Default                 | Meaning                                                                       |
| ------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `--scan-logs-dir`   | New temporary directory | Per-scan workspace/log location.                                              |
| `--scan-logs-save`  | `false`                 | Preserve that workspace after shutdown.                                       |
| `--server-logs-fmt` | `console`               | `console` or `json` for the HTTP server logger.                               |
| `--server-logs-lvl` | `info`                  | `error`, `info`, `verbose`, `debug`. Debug also enables detailed diagnostics. |
| `--server-logs-out` | Standard output         | File destination for the HTTP server logger.                                  |
| `--v`               | Off                     | Warning/error scan log verbosity.                                             |
| `--vv`              | Off                     | Info/warning/error scan log verbosity.                                        |
| `--vvv`             | Off                     | Debug/info/warning/error scan log verbosity.                                  |

Normal startup prints the banner, product information, data locations, initial caps and listener address. Request diagnostics, missing-header authentication logs and MCP catalogue/approval configuration lines require debug. Actual failures are still returned to clients. Per-scan files and the console are different logging outputs; `--server-logs-fmt=json` does not convert the banner/startup messages into JSON.

## Environment configuration

The configuration loader uses the `BURPBOUNTY` prefix and nested Go field names (without automatically inserting underscores inside a field name). CLI flags generally replace corresponding loaded values. The startup caps and bootstrap scan defaults described above have explicit initialization.

| Variable                                                  | Purpose / default                                                                   |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `BURPBOUNTY_LICENSE_KEY`                                  | Required runtime license key for the commercial executable.                         |
| `BURPBOUNTY_SERVER_HOST`, `BURPBOUNTY_SERVER_PORT`        | Listener defaults.                                                                  |
| `BURPBOUNTY_SERVER_ENABLEMCP`                             | Enable MCP (`true`/`false`).                                                        |
| `BURPBOUNTY_SERVER_PROFILESDIR`                           | Catalogue directory.                                                                |
| `BURPBOUNTY_SERVER_MCPALLOWTARGETS`                       | Comma-separated auto-approval hosts.                                                |
| `BURPBOUNTY_SERVER_CERTFILE`, `BURPBOUNTY_SERVER_KEYFILE` | Enable TLS when both are present.                                                   |
| `BURPBOUNTY_SERVER_READTIMEOUT`                           | Main HTTP read timeout, `10s`.                                                      |
| `BURPBOUNTY_SERVER_READHEADERTIMEOUT`                     | Header read timeout, `10s`.                                                         |
| `BURPBOUNTY_SERVER_WRITETIMEOUT`                          | HTTP write timeout, `10s`; consider streaming clients when deploying a proxy.       |
| `BURPBOUNTY_SERVER_IDLETIMEOUT`                           | Idle connection timeout, `10s`.                                                     |
| `BURPBOUNTY_SERVER_SHUTDOWNTIMEOUT`                       | Graceful HTTP shutdown timeout, `1m`.                                               |
| `BURPBOUNTY_MONITORING_ADDRESS`                           | Metrics listener address, `127.0.0.1`.                                              |
| `BURPBOUNTY_MONITORING_PORT`                              | Metrics port, `8082`. Zero requests an ephemeral port; it does not disable metrics. |

Engine blind-host settings are deployment inputs, not MCP `create_scan` fields: `BURPBOUNTY_MANAGER_SCAN_BLINDHOSTID`, `BURPBOUNTY_MANAGER_SCAN_BLINDHOSTDOMAIN` and `BURPBOUNTY_MANAGER_SCAN_BLINDHOSTPRIVATEKEY`. All three are needed for the configured provider workflow. Supplying a callback-looking hostname alone does not configure interaction polling.