> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Zabbix

> Connect Zabbix so agents can triage active problems, read host metrics and logs, and schedule maintenance through your Approvals

Connect Zabbix to let CloudThinker agents triage active problems, read host metrics and log items, review triggers, templates, and dashboards, and, if you allow it, acknowledge events or schedule maintenance. The connection signs in to the Zabbix API with an API token or a username and password, and agents can do only what that Zabbix user is allowed to do.

## Prerequisites

* A Zabbix frontend reachable from CloudThinker over the internet, such as `https://zabbix.example.com`. If a firewall guards it, or it must stay private, see [Reaching private services](https://docs.cloudthinker.io/guide/connections/overview.md#reaching-private-services).
* A Zabbix Super admin who can create a user, a user group, and an API token.
* Zabbix 5.4 or later if you want to use an API token. Older versions use username and password.
* The **Admin** role in the CloudThinker workspace, which you need to add connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

## Setup

**1. Create a role with API access**

Go to **Users → User roles** (in Zabbix 6.x, **Administration → User roles**) and click **Create user role**. Name it `CloudThinker`, set **User type** to **User** (or **Admin** for writes, see [Required permissions](#required-permissions)), make sure **Access to API** is enabled, and click **Add**.

**2. Create a user group with host group access**

Go to **Users → User groups** (in 6.x, **Administration → User groups**) and click **Create user group**. Name it `CloudThinker`. On the **Host permissions** tab (**Permissions** in 6.x), select the host groups agents should see, choose **Read**, and click **Add**.

**3. Create the user**

Go to **Users → Users** (in 6.x, **Administration → Users**) and create a user named `cloudthinker` in the `CloudThinker` group. On the **Permissions** tab, pick the `CloudThinker` role, then click **Add**.

**4. Create an API token (Zabbix 5.4+)**

Go to **Users → API tokens** (in Zabbix 5.4 to 6.x, **Administration → General → API tokens**) and click **Create API token**. Select the `cloudthinker` user, set **Expires at** to match your rotation schedule, and click **Add**. Copy the token. Zabbix shows it only once.

On a version older than 5.4, skip this step and use the user's password instead.

**5. Add the connection in CloudThinker**

In the sidebar, click **More → Workspace settings → Connections**, select **Zabbix**, and fill in:

* **ZABBIX\_URL**: your Zabbix frontend URL, such as `https://zabbix.example.com`.
* **ZABBIX\_AUTH\_TYPE**: switch it to **API Token**. The default is **Username & Password**, but a token can expire and be revoked without changing a password.
* **ZABBIX\_TOKEN**, or **ZABBIX\_USERNAME** and **ZABBIX\_PASSWORD**: the credentials from the steps above. CloudThinker shows only the fields for the auth type you picked.

Click **Connect**. CloudThinker signs in and lists hosts to check the credentials.

**Success state:** the connection shows a **Connected** status. That only proves the sign-in, so run the prompt in [Verify the connection](#verify-the-connection) in a new chat to check that the hosts you expect are visible.

## Connection details

The form shows these field names as they are written below.

| Field | Description | Example |
| - | - | - |
| **ZABBIX\_URL** | Your Zabbix frontend URL | `https://zabbix.example.com` |
| **ZABBIX\_AUTH\_TYPE** | **Username & Password** (default) or **API Token** | **API Token** |
| **ZABBIX\_TOKEN** | Zabbix API token. Shown for **API Token** | From **API tokens** |
| **ZABBIX\_USERNAME** | Zabbix username. Shown for **Username & Password** | `cloudthinker` |
| **ZABBIX\_PASSWORD** | That user's password. Shown for **Username & Password** | |

## Required permissions

Zabbix decides access in two places: the user's role (what kind of user it is, and whether it can use the API) and its user group (which host groups it can read or change). Agents see only hosts in host groups the user group can read.

| You want agents to | Role | Host group permission |
| - | - | - |
| Investigate problems, metrics, logs, triggers, templates, and dashboards | **User** type, API access enabled | **Read** |
| Also acknowledge events, enable or disable hosts and triggers, link templates, and create maintenance windows | **Admin** type, API access enabled | **Read-write** |
| Also create host groups or users | **Super admin** type | All |

> [!WARNING]
>
> Avoid Super admin. It ignores host group permissions and can create and change users, so one mistaken approval, by a person or by AI judgment, can reach every host and account. If you must use it, choose **Manual** so a person approves every change. Once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace, a **Deny** [Rule](https://docs.cloudthinker.io/guide/approvals/rules.md) for Zabbix user creation can block that one operation outright.

> [!TIP]
>
> Start with a User-type role and Read on the host groups you care about. Every write still goes through [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md), but a read-only Zabbix user means no approval, mistaken or automatic, can change anything.

## Agent capabilities

| Capability | What agents can do |
| - | - |
| **Discovery** | Report the Zabbix version, hosts, host groups, active problems, and templates |
| **Problems and events** | List active problems by severity, host, or host group, and read event history |
| **Metrics and logs** | List a host's items, read recent values, and tail log items |
| **Configuration** | Read triggers, templates, actions, maintenance windows, dashboards, and users, and export host or template configuration |
| **Writes (through Approvals)** | Acknowledge events; create, update, enable, disable, or delete hosts; enable or disable triggers and actions; link or unlink templates; create or delete maintenance windows; create host groups and users; import configuration |

Agents use Zabbix's severity scale: Not classified, Information, Warning, Average, High, Disaster.

Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself.

So on the default mode, an agent could create a maintenance window, delete a host, or create a user without a person seeing it. Choose **Manual** so a person approves every change — that is the control that works today. Once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace, an **Ask first** [Rule](https://docs.cloudthinker.io/guide/approvals/rules.md) can narrow the wait to just those operations: in a chat, type `/create-policy Ask first for maintenance windows, host deletes and user creation on the Zabbix connection`, then accept it under **Approvals → Rules → Needs review**.

> [!WARNING]
>
> A maintenance window created by an agent starts immediately, and alerts for those hosts stay suppressed until it ends. You can't give it a future start time, so ask when the work begins. Check the host list and duration in the approval request before you approve it. Deleting a host or unlinking a template with its data can't be undone.

### Verify the connection

Ask CloudThinker in a new chat:

```text theme={null}
Run Zabbix discovery and summarize the version, host count, host groups, and active problems by severity
```

Expect the Zabbix server version, a host count with a sample, your host groups, and active problems grouped by severity. If hosts are missing, the user's group can't read their host group.

### Example prompts

```text theme={null}
List active Zabbix problems at High or Disaster and tell me which hosts they're on
Is db-prod-01 running out of disk? Show the trend from its recent disk values
Schedule a 2-hour Zabbix maintenance window for the hosts in Database servers
```

The last prompt needs an Admin-type role with **Read-write** on that host group, and it goes through your [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On **Manual** it waits for a person; on the default Auto mode, AI judgment can let it run without asking.

## Troubleshooting

> [accordion] Failed to connect to Zabbix
>
> CloudThinker couldn't sign in or list hosts. Check that **ZABBIX\_URL** is the frontend address and reachable from CloudThinker, that **ZABBIX\_AUTH\_TYPE** matches the credentials you entered, and that the user's role has API access enabled.

> [accordion] 401, or the session expired
>
> The token expired or was deleted, or the password changed. Create a new token under **API tokens** and update **ZABBIX\_TOKEN**, or update the password.

> [accordion] Hosts or problems are missing
>
> The user's group has no permission on that host group, so Zabbix leaves those hosts out. Grant **Read** on the host group in the user group's permissions.

> [accordion] A write fails with a permission error (403)
>
> The user is a User-type role or has only **Read** on the host group. Change the role to Admin type and grant **Read-write** if you want agents to make that change.

> [accordion] 429, 500, or 503 errors
>
> The Zabbix API is rate limiting, failing, or in maintenance. Wait a minute, then ask a narrower question scoped to one host or host group.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Prefer an API token**: a token belongs to one user, carries its own expiry, and can be revoked without changing a password.
- **Scope by host group**: give the CloudThinker user group permissions only on the host groups agents need.

## Related

> [card] [Approval rules](https://docs.cloudthinker.io/guide/approvals/rules.md)
>
> Decide which Zabbix writes run, wait for a person, or are refused.

> [card] [Webhook integrations](https://docs.cloudthinker.io/guide/incident/webhook-integrations/overview.md)
>
> Send Zabbix alerts into Resolve as incidents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.