> 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/installation.md).

# Installation and first start

Choose your executable, start the listener and verify authenticated access.

## Select the executable

| Platform            | Release executable                    |
| ------------------- | ------------------------------------- |
| macOS Apple Silicon | `burpbounty-server-darwin-arm64`      |
| macOS Intel         | `burpbounty-server-darwin-amd64`      |
| Linux x86-64        | `burpbounty-server-linux-amd64`       |
| Windows x86-64      | `burpbounty-server-windows-amd64.exe` |

Use a binary matching the host architecture. Release contents and licensing terms come from your distribution channel; this guide does not imply an unlimited device entitlement.

## License and listener

The executable reads `BURPBOUNTY_LICENSE_KEY` at startup. Clients authenticate with the **same value** in `X-BURPBOUNTY-LICENSE`. Configure the real key through your shell or service environment; do not commit it into scripts or documentation.

{% tabs %}
{% tab title="macOS / Linux (Bash)" %}
Prompt for the key without writing it into shell history:

```bash
read -r -s -p 'License key: ' BURPBOUNTY_LICENSE_KEY
printf '\n'
export BURPBOUNTY_LICENSE_KEY
chmod +x ./burpbounty-server-darwin-arm64
./burpbounty-server-darwin-arm64 --ip 127.0.0.1 --port 8081
```

Substitute the Linux or Intel binary where appropriate.
{% endtab %}

{% tab title="Windows (PowerShell)" %}
Set `$env:BURPBOUNTY_LICENSE_KEY` through your normal secret-management process and launch:

```powershell
.\burpbounty-server-windows-amd64.exe --ip 127.0.0.1 --port 8081
```

{% endtab %}
{% endtabs %}

Both annual and monthly **Burp Bounty Server** subscriptions activate Server. **Burp Bounty Pro** subscriptions also include Server access, using the Pro license key. A Server-only subscription does not activate the Burp Bounty Pro extension.

Each license is for **one individual user**, with **10 registered activations in total**. A Pro license shares that allowance across Pro and Server; a Server-only license uses it for Server. See [users, products and activations](/licensing.md).

Startup can activate the device when required, subject to the license's device limits and subscription status. Header authentication checks that the client supplies the server's configured key; it is distinct from subscription validation.

### Validation while running

Server rechecks the subscription every **15 minutes**, without reactivating a revoked device. A confirmed expiry, disabled license or removed activation blocks new scans and resumes, and cancels active/paused scans. The HTTP service stays available so authenticated clients can retrieve retained results. Existing cancelled work is not automatically resumed.

Temporary validation outages allow a **24-hour grace period from the last successful check**. Further failures do not extend it. When an online check succeeds again, new scans are allowed automatically. MCP `server_info.scan_access` reports whether scanning is allowed and, when blocked, the reason.

## Verify REST availability

From a terminal that has the key configured:

```bash
curl --fail --silent --show-error -o /dev/null -w '%{http_code}\n' \
  -H "X-BURPBOUNTY-LICENSE: ${BURPBOUNTY_LICENSE_KEY}" \
  http://127.0.0.1:8081/health
```

{% hint style="success" %}
**Expected result**

A healthy authenticated call returns `200` with an empty body. A request missing the header returns `401`, including ordinary browser visits.
{% endhint %}

## Enable MCP and a catalogue

```bash
./burpbounty-server-darwin-arm64 \
  --ip 127.0.0.1 --port 8081 \
  --mcp \
  --profiles-dir "/absolute/path/BurpBountyData/profiles" \
  --mcp-allow-targets example.test
```

Use the actual directory on the **server host** and your approved target hosts. An explicitly supplied empty, inaccessible or invalid catalogue stops startup with an error. Omit `--profiles-dir` if clients will upload profiles and do not need catalogue discovery. REST remains enabled when MCP is on.

## Stop and update

Ctrl+C initiates shutdown: HTTP/MCP connections are cancelled, scans stop and result writes finish before temporary cleanup. A second Ctrl+C forces exit if needed. Retained history survives normal shutdown; active work is not resumed after restart.

Executable and profile updates are independent. Both commands require the license environment variable, perform the requested update and exit without starting REST/MCP listeners. Run them separately, then restart the service yourself.

Startup checks for a compatible executable update but does not install it. The available-version notice is shown with `--debug`; a quiet normal startup does not prove that you have the latest release. Profiles are updated only through the explicit profile command below or by managing their files yourself.

{% tabs %}
{% tab title="Executable" %}

```bash
./burpbounty-server-darwin-arm64 --update
```

The updater requests the channel for its platform, such as `server-stable-darwin-arm64` or `server-stable-linux-amd64`. It checks the downloaded executable's platform and retains the previous executable beside it with a leading dot and `.old` suffix for rollback.

The transition from the development Server 2.0.0 line to the first commercial Server 1.0.0 requires a manual replacement. The old updater does not select the new channels. Later 1.x releases use the new updater normally.
{% endtab %}

{% tab title="Official profiles" %}

```bash
./burpbounty-server-darwin-arm64 \
  --update-profiles \
  --profiles-dir "/absolute/path/BurpBountyData/profiles"
```

All platforms use the `server-profiles-stable` channel. The destination may be new or empty. Each downloaded ZIP must contain `version.txt` and `profiles/*.bb`; the version must match the published release. The updater validates the profiles before replacing the catalogue.

The installed catalogue has its own `version.txt` and hidden `.burpbounty-profiles.json` manifest. Custom files are preserved. Locally modified official files, or conflicting filenames in an unmanaged catalogue, stop the update with an error. Preserve those customizations separately and resolve the conflict before retrying; do not remove the manifest. An empty destination is the simplest initial migration from a manually maintained pack.

A replaced catalogue is retained as `profiles.backup-<UTC timestamp>`. To roll back, stop the service, move the current catalogue aside and restore the backup under the original directory name, including its manifest and version file. Backups accumulate until you remove them.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Update between scans**

Stop every server using the catalogue before updating it. Current servers hold shared catalogue locks; updates require exclusive access. The parent directory must be writable for the lock file, staging and backups. Older servers do not enforce this lock and must also be stopped. Profiles are never updated automatically while scanning.
{% endhint %}

Executable and profile updates use the same license as Server, whether it belongs to a Server or Pro subscription. The publisher must make the corresponding release available for that license product.

No message is printed when no update or compatible release is published. Other update-check failures can still produce a warning; that warning does not by itself invalidate a working license. A mismatched channel or invalid package is reported rather than used as a fallback download. Pro's existing updater and combined Pro/profile version remain unchanged.