# Installing Add-ons

- [Introduction](#introduction)
- [First-Party Add-ons](#first-party-add-ons)
    - [Free Add-ons](#free-add-ons)
    - [Paid Add-ons](#paid-add-ons)
- [Installing Add-ons](#installing-add-ons)
    - [Installing Add-ons Using AI](#installing-add-ons-using-ai)
    - [Removing Add-ons](#removing-add-ons)
    - [Installing Add-ons Manually](#installing-add-ons-manually)
- [Licence Keys](#licence-keys)
    - [Entering Keys](#entering-keys)
    - [Trials](#trials)
- [Turning Add-ons On and Off](#turning-add-ons-on-and-off)

## Introduction

Add-ons extend NiceTryBot with new pages, rule fields, gym obstacles, and more. Under the hood, an add-on is simply a Composer package that the control panel discovers on its own. Some add-ons ship with NiceTryBot and are free, while others are available from the [NiceTryBot marketplace](https://nicetrybot.com/marketplace).

Add-ons are built into the control panel's image before it runs, so nothing is ever installed from inside the control panel itself. Instead, you install add-ons on your server using the `nicetrybot` command.

## First-Party Add-ons

### Free Add-ons

The following add-ons ship with every NiceTryBot installation:

| Add-on | Description |
| --- | --- |
| **Lockdown** | Close every site behind a maintenance page in one click, then let people back in. Administrators get through using an IP allowlist or a signed pass. |
| **Privacy mode** | Redact the control panel before you share your screen. Swaps hostnames for stand-ins, masks IP addresses, and hides the words you choose. Toggle it from the top bar or with <kbd>⌘</kbd> + <kbd>/</kbd>. |
| **Rule packs** | Ready-made rules and gym routines, tested on real traffic. Packs cover scanners, PHP exploits, AI crawlers, browser impostors, and form scripts. Installed rules only tag, and installed routines start off. |
| **Tarpit** | Make the worst bots wait a little longer with every request, held at the edge. |
| **Transfer** | Move an origin, along with its sites, secret, rules, and gym routines, from one NiceTryBot installation to another. Requires the Origins add-on on both installations. |

### Paid Add-ons

The following add-ons are available from the [marketplace](https://nicetrybot.com/marketplace). Each is licensed per installation and includes a year of updates:

| Add-on | Description |
| --- | --- |
| **Captchas** | Puzzles people solve in a second and bots get lost in, as a new gym obstacle. |
| **Fingerprints** | A device fingerprint taken inside the gym, so you can spot one machine hiding behind a thousand home IP addresses. |
| **Request Monitor** | See what your origin answered, and catch watchwords in what visitors send. Adds the **Captures** page and the `response` rule fields. |
| **Threats** | Watch the pages that matter, graded from calm to severe against their normal traffic. |
| **Origins** | One backend, hundreds of sites. Protect every domain an application serves, and add new ones automatically. |

The marketplace also sells **More domains** packs. These aren't packages at all, just licence keys, and each adds 100 domains to your installation's [domain limit](https://docs.nicetrybot.com/docs/0.x/domains.md#domain-limits).

## Installing Add-ons

To install marketplace add-ons, SSH into your server and pass their names to `nicetrybot addons add`:

```shell
nicetrybot addons add captchas threats
```

The first time you install a paid add-on, the command asks for the Composer token from your account on nicetrybot.com. It then rebuilds the control panel's image with the add-ons included and restarts the stack. Building needs about 2 GB of memory, so on a small server, the build may take a little while.

You may list the add-ons built into your installation at any time:

```shell
nicetrybot addons
```

Your choices are stored in your `.env` file, so they survive updates. Every time you run `nicetrybot update`, your add-ons are rebuilt with the newest versions your licences allow:

```ini
NICETRY_ADDONS="nicetry/captchas nicetry/threats"
NICETRY_COMPOSER_TOKEN=ntbc_...
```

If you set `NICETRY_ADDONS=all`, NiceTryBot installs every add-on your token may install, so new purchases arrive on the next update without any extra steps.

> [!NOTE]
> Your Composer token is passed to the build as a Docker build secret. It never ends up in the image, its layers, or the running containers.

### Installing Add-ons Using AI

If you would like help choosing add-ons, or an agent has access to your server, you may give it the following prompt:

```text
Read https://docs.nicetrybot.com/docs/0.x/addons.md. Then look at my NiceTryBot installation with `nicetrybot status`, suggest which add-ons would help with the traffic I describe, and install the ones I choose. Ask me for my Composer token rather than guessing it.
```

### Removing Add-ons

To remove an add-on, use `nicetrybot addons remove`:

```shell
nicetrybot addons remove threats
```

### Installing Add-ons Manually

If you manage the stack with Docker Compose yourself, add the add-ons build file to `COMPOSE_FILE`, set `NICETRY_ADDONS` and `NICETRY_COMPOSER_TOKEN` in your `.env` file, and rebuild the app image:

```shell
echo "COMPOSE_FILE=compose.yml:compose.addons.yml" >> .env

docker pull ghcr.io/nicetrybot/app:latest
docker compose build app
docker compose up -d
```

If you run the control panel without Docker, set the same environment variables and run the `addons:install` Artisan command, then run your migrations and rebuild your front-end assets:

```shell
php artisan addons:install
php artisan migrate --force
npm run build
```

## Licence Keys

Paid add-ons and **More domains** packs are unlocked using licence keys, which you will find in your account on nicetrybot.com after purchasing. A key keeps working after its year of updates ends; it simply stops receiving new versions.

Keys are checked offline against NiceTryBot's public key, then confirmed once a day. If nicetrybot.com can't be reached, your add-ons keep working.

### Entering Keys

Administrators may enter keys from **Admin → Add-ons** in the control panel using **Enter licence key…**. You may also enter any missing keys from your server:

```shell
nicetrybot addons keys
```

The **Add-ons** page shows each add-on's state: **Free**, **Licensed**, **Trial**, **Trial ended**, or **Licence revoked**.

### Trials

You may try any paid add-on before buying it. Without a key, a paid add-on runs for a 14 day trial from the first time NiceTryBot sees it, then turns itself off until you enter a key.

## Turning Add-ons On and Off

Administrators may turn any installed add-on off, and back on, from **Admin → Add-ons**. The change reaches every server on its next request, with no rebuild needed.

Turning an add-on off hides its pages, menus, and hooks, and its routes return `404`. Its data stays put, and NiceTryBot keeps honouring its retention and erasure duties for any visitor data it stored, so turning it back on picks up right where you left off.