# Get started with Sentinel

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

This guide takes you from nothing to a verified widget submission in about 15 minutes. You run Sentinel locally in Docker, sign in to the admin UI, create an API key, protect a form, and see the result in the request logs.

## Prerequisites

- Docker on amd64 or arm64.
- A Sentinel trial license. Register at [ALTCHA Cloud](https://cloud.altcha.org/) and create a **Sentinel V2** trial license in the **Licenses** section as an activation key (`SENT-…`). This guide uses the key; a license file needs the deployment ID of a running Sentinel first (see [Licensing](/docs/sentinel/v2/configure/licensing/)).
- A web page with a form, and a backend that handles its submissions.

## Step 1 — Write a configuration file

Sentinel reads its settings from `sentinel.toml`. Create a working directory with this file:

```toml
# sentinel.toml

[license]
key = "${SENTINEL_LICENSE_KEY}"   # SENT-… activation key, read from the environment

[server.admin_ui]
enabled = true
host = "0.0.0.0"                  # listen on all interfaces inside the container

[bootstrap]
root_password = "${ROOT_PASSWORD}"   # used on first start only
```

- **License.** Without an active license, Sentinel starts, but the widget and detection endpoints, including `/v2/challenge`, return `403 LICENSE_NOT_ACTIVE`. An activation key needs outbound access to the license server. If you downloaded a license file instead, mount it and use `file = "/home/nonroot/sentinel.license"` in place of `key`; `key` and `file` can't be combined. See [Licensing](/docs/sentinel/v2/configure/licensing/).
- **Admin UI.** The admin UI is off by default and binds to `127.0.0.1`, which isn't reachable from outside a container. It runs on its own listener, port `3002`. See [`[server.admin_ui]`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui).
- **Root password.** On first start, Sentinel creates the `root` user with this password (at least 8 characters). The setting is ignored once a user exists. See [`[bootstrap]`](/docs/sentinel/v2/reference/configuration/#bootstrap).

Everything else uses its default: an embedded SQLite database and key-value store in the data directory, and secrets generated into `data/secrets.json` on first start. This is fine for a trial; for production, see [Install](/docs/sentinel/v2/install/).

## Step 2 — Start Sentinel

Run the image with the configuration file and a volume for the data directory. The container's working directory is `/home/nonroot`, so the file goes to `/home/nonroot/sentinel.toml` and the data to `/home/nonroot/data`:

```bash
docker run -d --name sentinel \
-p 3000:3000 -p 3002:3002 \
-e SENTINEL_LICENSE_KEY='SENT-…' \
-e ROOT_PASSWORD='choose-a-long-password' \
-v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
-v sentinel-data:/home/nonroot/data \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1
```

- Port `3000` serves the API, including the widget endpoints. Port `3002` serves the admin UI.
- v2 images are tagged by version, `2.0.0-beta.x` during the beta. Use the newest beta tag; `latest` still points to Sentinel v1. See [Install](/docs/sentinel/v2/install/) for the available tags.

Check that the server is up:

```bash
curl http://localhost:3000/
```

```json
{"ok":true}
```

The log shows the license and the root user:

```bash
docker logs sentinel 2>&1 | grep -E 'licensed to|root user'
```

<Callout type="tip" title="Lost the root password?">

Without `[bootstrap] root_password`, Sentinel generates a password on first start and logs it once as a warning: `created root user with generated password; change it username="root" password=…`. Run `docker logs sentinel` to find it.

## Step 3 — Sign in to the admin UI

Open [http://localhost:3002](http://localhost:3002) and log in with the username `root` and the password from step 1.

The root user is a member of the **Default Account** that Sentinel creates on first start. Accounts, API keys, and security groups belong to an account; see [Accounts & users](/docs/sentinel/v2/concepts/accounts-users/).

## Step 4 — Create a security group and an API key

The widget authenticates with a `public` API key. The key's security group sets its access level and the rules every request must pass. Create both in one step:

1. Open **Dashboard**. In the **Get started** card, click **Quick setup**. The card appears while the account has no security group or no API key.
2. Review the **Quick setup** dialog. It creates a security group named `Website` with **Public access** and the **Recommended** template, and an API key named `Website` with request logging on.
3. Click **Create**.
4. Copy the **Challenge URL** and the **API key secret** from **Your API key is ready**. The secret is also shown later on the **API Keys** page.

The Recommended preset blocks IPs listed by threat intelligence, rate-limits each device, and gives risky or misbehaving clients a code challenge and a harder proof-of-work. To create the group yourself instead, use **Security Groups → Create security group**, set **Access** to `public`, and apply **Recommended** from the **Templates** tab of the rules editor. See [Security groups](/docs/sentinel/v2/concepts/security-groups/) and [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/).

Check that the key serves challenges:

```bash
curl -i 'http://localhost:3000/v2/challenge?apiKey=key_…'
```

The response is `200` with a challenge whose `configuration.verifyUrl` is `/v2/verify`. Because `curl` is a command-line client, the Recommended preset escalates it, so this response also contains a `codeChallenge`; browsers normally get a plain proof-of-work.

## Step 5 — Add the widget to your form

Load the widget script, then set the widget's `challenge` attribute to the challenge URL you copied:

```html
<form method="POST" action="/submit">
<input type="email" name="email" required>
<altcha-widget
challenge="http://localhost:3000/v2/challenge?apiKey=key_…"
></altcha-widget>
<button type="submit">Send</button>
</form>
```

Full setup instructions (npm install, CDN script, configuration options) are on the [Widget Integration](/docs/integration/widget/) page.

The admin UI builds the challenge URL from the listener widgets call: the main API on port `3000` here, or `[server.public_api]` when you enable it, and that listener's `base_url` when set. In production, set `base_url` so the URL uses Sentinel's public address; see [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/). The widget sends the solution to `/v2/verify` on the same host and adds the signed result to the form as the `altcha` field. Widget options are on the [widget integration](/docs/integration/widget/) page; Sentinel-specific options are in [Embed the widget](/docs/sentinel/v2/integrate/widget/).

## Step 6 — Verify the submission on your backend

The `altcha` field passes through the browser, so your backend must check its signature with the API key secret before it trusts the submission. In Node.js, install `altcha-lib` 2.9.0 or later:

```bash
npm install altcha-lib
```

```js
import { verifyServerSignature } from 'altcha-lib';

// `altcha` is the submitted form field; `secret` is the API key secret (sec_…).
export async function verifyAltcha(altcha, secret) {
try {
const { verified, verificationData } = await verifyServerSignature({ payload: altcha, hmacSecret: secret });
return verified ? verificationData : null;
} catch {
return null; // tampered payload, e.g. an unsupported algorithm
}
}
```

`verifyServerSignature` checks the signature, that Sentinel verified the solution, and that the payload hasn't expired. Reject the submission when `verifyAltcha` returns `null`. Otherwise, `verificationData.classification` is `GOOD`, `NEUTRAL`, or `BAD`, and you decide what to do with each. Keep the secret on your server, for example in an environment variable. For PHP, Python, Go, .NET and other languages, see the [server libraries](/docs/integration/server/#libraries).

To prevent a payload from being reused, or to verify without the secret, call `POST /v2/verify/signature` with a `restricted` key instead; the libraries do that with their `verifyServer` function. See [Verifying submissions](/docs/sentinel/v2/integrate/verification/).

## Verify it works

Submit the form in a browser. Then open **Logs** in the admin UI: the API key's **Challenge** and **Verify** requests are listed with their status, result, client, and the security-group rules that matched.

Requests appear because Quick setup turned on request logging for the key (**Verification**: challenge and verify requests). A key's request logging is **Off** by default, so keys you create on the **API Keys** page log nothing until you change it. See [Request logs](/docs/sentinel/v2/operations/request-logs/).

If the widget shows an error instead, check the response of `/v2/challenge` in the browser's network panel and look up its `code` in [Error codes](/docs/sentinel/v2/reference/errors/). The usual ones:

| HTTP | Code | Meaning |
|---|---|---|
| 403 | `LICENSE_NOT_ACTIVE` | No active license; `data.status` says why. Check `[license]` and the server log. |
| 401 | `API_KEY_REQUIRED` | The challenge URL has no `apiKey`, or the key doesn't start with `key_`. |
| 403 | `BEARER_AUTH_PUBLIC_API_KEY` | The key's security group isn't `public`. |

## Next steps

- [Concepts](/docs/sentinel/v2/concepts/): how accounts, API keys, security groups, and scoring fit together.
- [Install](/docs/sentinel/v2/install/): production requirements, then [Install with Docker](/docs/sentinel/v2/install/docker/).
- [Server configuration](/docs/sentinel/v2/configure/): the configuration file, secrets, and listeners.
- [Use cases](/docs/sentinel/v2/use-cases/): recommended rules and backend code for forms, sign-ups, and logins.
- [Production checklist](/docs/sentinel/v2/security/production-checklist/): what to change before you go live.
