Quick start

The shortest path from the delivery archive to a working login: one Linux host, Docker, your existing QRadar Console and an authorized-service token, one run of deploy.sh.

Prerequisites

Item	Requirement
Host	Ubuntu 20.04 / 22.04 / 24.04 or equivalent Linux, 2 vCPU / 4 GB / 20 GB+
Runtime	Docker Engine 24+ and Docker Compose v2
QRadar	Your existing 7.5.x (REST API 20.0), Console port 443 reachable from the gateway host
Token	An authorized-service SEC token (Admin → Authorized Services) whose security profile covers the log sources to query and whose user role can read Ariel / Offenses / Rules / Log Sources
LLM	URL / API key / model name of an OpenAI-compatible endpoint (`ark-code-latest` on the Volcengine Ark coding plan)
Hostname	A domain name (e.g. `copilot.corp.local`), not a bare IP (an IP is not a valid TLS SNI and some browsers refuse the handshake); without internal DNS, add a hosts entry on the analysts' machines

Inbound: only 443 (80 for the redirect, optional). Outbound: the LLM endpoint on 443, the QRadar Console on 443, license.reallysec.com on 443 (not needed for offline installs, see Licensing).

Install

Install Docker (if missing)

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # log out and back in
docker compose version

Unpack the delivery archive

The archive RST-Qradar-AI-Copilot-<version>.tar.gz carries the images; no registry access is needed.

sha256sum -c RST-Qradar-AI-Copilot-<version>.tar.gz.sha256
tar xzf RST-Qradar-AI-Copilot-<version>.tar.gz
cd RST-Qradar-AI-Copilot-<version>

Run `deploy.sh`

./deploy.sh

It checks Docker, generates state/machine-id and state/server_guid (the licence's hardware fingerprint - never regenerate them), docker loads the images, asks for the auth mode (1, built-in login), then the LLM URL / key / model, timezone, QRadar Console URL and SEC token, whether the Console certificate is trusted, the site hostname and an admin password, writes the generated internal secrets to .env (mode 600), and runs docker compose up -d until everything is healthy.

It prints the URL at the end. About two minutes end to end.

Verify

curl -k https://copilot.corp.local/healthz   # {"status":"ok"}
curl -k https://copilot.corp.local/readyz    # qradar / qradar_version

qradar in readyz must be ok; qradar_version is what the Console reports. On a 503 the qradar field carries the reason: not_configured means no Console yet; a 401 means the token is invalid or expired; a connection error means the gateway host cannot reach the Console on 443 or the URL is wrong.

Log in

Open https://copilot.corp.local/v2/, accept the self-signed certificate (swap in your own for production by editing Caddyfile), user admin, the password you just set.

You land on the Ask AI home; the parts of the screen are explained in A tour of the UI.

Token permissions

What the gateway can see is decided by the security profile and user role behind the token; the gateway adds nothing on top. Minimum:

Security profile: the log sources (or log-source groups) and networks to query; offenses outside that scope are invisible
User role: Ariel search, Offenses (with write if close / note / assign are wanted), view rules, log-source management (read)

Create a dedicated authorized service with just these rights rather than reusing an admin token. Details in QRadar token permissions.

Recommended: set RST_LOG_SOURCE_WHITELIST=WinCollect @ *,PaloAlto-* in .env as a second fence on top of the token: the model can only mention whitelisted sources, and every Ariel search is checked against it before it runs.

After install

Activate a licence: the paid engines need one; trials are free.
/v2/settings: log-source whitelist, masking mode, audit forwarding.
Backups: copy the whole ./state/ directory; export the gateway_state volume with the bundled scripts/backup.sh (it covers the volume only, not ./state/).

Upgrading

Unpack the new archive into the same directory and run ./deploy.sh again, choosing "keep existing .env" - it loads the new image, switches GATEWAY_IMAGE_TAG and restarts. To roll back, restart on the previous tag; licence state lives in state/ and the volume and survives.

Never regenerate state/machine-id or state/server_guid, and never docker compose down -v. Changing either is a new host to the licence, which then has to be re-activated.

Troubleshooting

Symptom	Where to look
`/v2/` does not open	`docker compose -f docker-compose.prod.yml logs caddy gateway`; 443 open, `CADDY_SITE_ADDRESS` is a hostname
TLS handshake fails	`CADDY_SITE_ADDRESS` is a bare IP; use a hostname + hosts entry
`readyz` 503 with a 401	Token invalid, expired, or the authorized service was disabled
`readyz` 503 with a connection error	Wrong `QRADAR_URL`; gateway host cannot reach the Console on 443; certificate verification on but the Console uses a private CA and `RST_QRADAR_CA_CERT` is not set
Queries fail with `qradar_forbidden`	The token's user role lacks Ariel, or its security profile does not cover the target log source
Offense list stays empty	Security profile covers no log source / network; no OPEN offense within `RST_OFFENSE_INGEST_LOOKBACK` (default 7d)
Licence suddenly invalid	Was `state/machine-id` / `state/server_guid` regenerated?

On this page