Quick start

A single-host install needs a Linux host, Docker, your existing Zabbix and one Zabbix API token, plus one run of the installer or deploy.sh. For SSO and offline activation, see Installation.

Prerequisites

• A Linux host that runs Docker (Ubuntu 22.04 or later, Kylin, UOS and similar), with 2 vCPU, 4 GB RAM and 20 GB disk recommended.
• Docker Engine 24 or later and Docker Compose v2.
• Zabbix 6.0, 6.4, 7.0, 7.2 or 7.4, with the frontend's api_jsonrpc.php reachable from the gateway host.
• A Zabbix API token, preferably belonging to a read-only account. Permissions are listed below.
• An OpenAI-compatible LLM endpoint with an API key and a model name.
• A hostname such as copilot.corp.local. Without internal DNS, add a hosts entry on the users' machines.

Inbound, open 443 only; 80 serves the redirect and is optional. Outbound, the gateway needs the LLM endpoint and Zabbix. 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

curl -fsSL https://get.docker.com | sudo sh
docker compose version

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

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

curl -k https://copilot.corp.local/healthz   # {"status":"ok"}
curl -k https://copilot.corp.local/readyz    # {"status":"ready","zabbix":"ok","zabbix_major":"7.0"}

Zabbix permissions

What the gateway can see is decided by the user group and user role of the account that owns the API token.

Create a dedicated account for the gateway instead of reusing a Super admin. See Zabbix permissions for the details.

Next steps

1. To use the paid features, import a license under Settings > License; no reinstall is needed. Without a license the gateway runs as Community. See Editions for the differences and License for the steps.
2. Configure the host group allowlist, field masking and audit in Settings.
3. Back up regularly with scripts/backup.sh from the archive. It saves both the gateway_state volume and state/machine-id.

Upgrade

Run the install command again, or unpack the new archive into the same directory and run sudo ./deploy.sh. When asked whether to keep the existing .env, enter y. Gateways on 2.0.1 or older cannot update online to 2.0.2 and need this manual upgrade once; the install script reuses the old directory /opt/rst-zabbix-ai-copilot. See Upgrade, rollback and backup.

Troubleshooting

/v2/ does not open

Check the logs with docker compose -f docker-compose.prod.yml logs caddy gateway. Open 443 in the firewall or security group and check CADDY_SITE_ADDRESS.

Signing in as admin from a browser returns 403

.env has no RST_ADMIN_PASSWORD_HASH, and the factory password only works from the gateway host itself. Generate a hash, write it to .env (every $ written as $$), then run docker compose -f docker-compose.prod.yml up -d:

docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<password>'

If a password is forgotten, another administrator resets it on the Users page.

readyz returns 503

ZABBIX_URL must end in /api_jsonrpc.php. Then check that the token is valid and that the gateway host can reach Zabbix. On Zabbix older than 6.0 the code is zabbix_version_unsupported.

The license suddenly stops working

state/machine-id was regenerated or the gateway_state volume was lost. Restore them from a backup.

For other symptoms, see the FAQ.