Quick start

Install the gateway on a single Linux host, connect it to an existing QRadar Console and sign in.

A single-host install needs a Linux host, Docker, your existing QRadar Console and one authorized-service token, plus one run of the installer or deploy.sh. For SSO and air-gapped activation, see Installation.

Prerequisites

Ubuntu 20.04, 22.04, 24.04 or an equivalent Linux, with at least 2 vCPU, 4 GB RAM and 20 GB disk.
Docker Engine 24 or later and Docker Compose v2.
QRadar 7.5 or later, with the Console reachable on 443 from the gateway host.
An authorized-service SEC token, created under Admin > Authorized Services in the Console. Permissions are listed below.
An OpenAI-compatible LLM endpoint with an API key and a model name. On the Volcengine Ark coding plan, the model name is ark-code-latest.
A hostname such as copilot.corp.local. A bare 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, open 443 only; 80 serves the redirect and is optional. Outbound, the gateway needs the LLM endpoint on 443 and the QRadar Console on 443. Online activation of a commercial license also needs license.reallysec.com on 443. Online update also needs github.com on 443, because the release manifest and content packs are read from GitHub Releases.

Installation

Install Docker

Skip this step if Docker 24 or later is already installed.

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # takes effect after you log in again
docker compose version

Download the archive and run deploy.sh

Starting with 1.0.1, one command downloads the archive, verifies its SHA-256, unpacks it and deploys. Run it from an interactive terminal:

curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-QRadar/releases/latest/download/install.sh | sudo bash

The script unpacks the archive into /opt/rst-ai-copilot-for-qradar and runs deploy.sh there. Every edition uses the same archive; without a license it runs as Community.

To install without the script, download RST-AI-Copilot-for-QRadar-<version>.tar.gz and its .sha256 file from GitHub Releases. Every edition uses the same archive:

sha256sum -c RST-AI-Copilot-for-QRadar-<version>.tar.gz.sha256
tar xzf RST-AI-Copilot-for-QRadar-<version>.tar.gz
cd RST-AI-Copilot-for-QRadar-<version>
sudo ./deploy.sh

The archive carries every image, so installation needs no registry access. Other options and air-gapped installs are covered in Installing from the archive.

Answer the deployment prompts

Choose 1 for authentication (built-in login), then enter the LLM settings, the timezone, the QRadar Console URL and SEC token, whether the Console certificate is trusted, the hostname and an admin password of at least 8 characters. The script generates internal secrets, writes them to .env (mode 600), starts the containers and prints the URL. The run takes about two minutes.

The script also generates state/machine-id and state/server_guid. These two files are the license's hardware fingerprint and cannot be regenerated.

Verify

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

In readyz, qradar is ok and qradar_version is the version the Console reports. On a 503, the qradar field gives the reason: not_configured means no Console has been entered; any other value is the error from connecting to the Console.

Open https://copilot.corp.local/v2/ and sign in as admin with the password you set during installation. The default certificate is self-signed; for production, edit Caddyfile to use your own certificate.

Sign-in page

The Ask AI home page opens after sign-in. See UI overview.

Token permissions

What the gateway can see is decided by the security profile and user role behind the token.

Item	Requirement
Security profile	The log sources and networks to query. Offenses outside this scope are not shown
User role	Ariel search, Offenses, view rules, read-only log sources. Closing, noting and assigning offenses needs write access to Offenses

Create a dedicated authorized service for the gateway instead of reusing an admin token. See QRadar token permissions.

Next steps

To use the paid features, an administrator imports a license on the License page; no reinstall is needed. Without one the gateway runs as Community; see Editions for the differences.
Configure the log-source whitelist, masking mode and audit in Settings.
Back up the ./state/ directory, and export the gateway_state volume with scripts/backup.sh from the archive. The script does not back up ./state/.

Upgrade

Run the install command again, or unpack the new archive into the same directory and run sudo ./deploy.sh, choosing to keep the existing .env. The script loads the new image, switches GATEWAY_IMAGE_TAG to the new version and restarts. See Upgrade, rollback and backup.

Do not regenerate state/machine-id or state/server_guid, and do not run docker compose down -v. The license treats a change to either file as a hardware change, which requires reactivation.

Troubleshooting

/v2/ does not open

Run docker compose -f docker-compose.prod.yml logs caddy gateway to read the logs. Open 443 in the firewall or security group, and set CADDY_SITE_ADDRESS to a hostname.

The HTTPS handshake fails

CADDY_SITE_ADDRESS is a bare IP. Change it to a hostname and add a hosts entry on the analysts' machines.

readyz returns 503 with a connection error in qradar

The gateway host cannot reach the Console on 443, or QRADAR_URL is wrong. If the Console uses a private CA and certificate verification is on, put the CA certificate in ./certs and set RST_QRADAR_CA_CERT.

The license suddenly becomes invalid

state/machine-id or state/server_guid was regenerated. Restore the original files from backup.

For other symptoms, see the FAQ.

On this page