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

# kanari agent

> Continuous monitoring daemon with local logging or cloud alerts

## Overview

`kanari agent` runs a continuous monitoring loop. On each cycle it collects metrics and either logs them locally (local mode) or sends them to the Kanari backend for persistent monitoring and alerts (API mode).

```bash theme={null}
# Local mode — log metrics as structured JSON, no external calls
kanari agent --local

# API mode — after running kanari login, no flags needed
kanari agent
```

Stop with `Ctrl+C` or `SIGTERM`. The agent handles both gracefully.

***

## Flags

| Flag | Default | Description |
| - | - | - |
| `--config`, `-c` | — | Path to a YAML config file |
| `--interval` | `15` | Seconds between collection cycles |
| `--local`, `-l` | off | Log metrics locally, skip all API calls |
| `--token` | — | API key override (usually not needed after `kanari login`) |
| `--no-color` | off | Disable ANSI colors in log output |

***

## API key resolution

The agent finds your API key automatically in this order:

1. `--token` flag
2. `KANARI_API_KEY` environment variable
3. `~/.kanari/config` — saved by `kanari login` ← **recommended**
4. `api_key` in your `kanari.yaml`

After running `kanari login`, you never need to set an API key manually.

***

## Local mode

The best way to verify what the agent collects before connecting it to the backend.

```bash theme={null}
kanari agent --local
```

Each cycle emits structured JSON to stdout:

```json theme={null}
{
  "timestamp": "2026-06-15T14:22:01Z",
  "total_pending": 47,
  "total_active": 6,
  "saturation_pct": 37.5,
  "redis_connected": true,
  "celery_connected": true,
  "queues": [
    {"name": "celery", "depth": 12, "oldest_task_age_seconds": 3.2},
    {"name": "emails", "depth": 35, "oldest_task_age_seconds": 88.1}
  ],
  "workers": [
    {"name": "api-worker", "active_tasks": 3, "concurrency": 8, "is_alive": true}
  ]
}
```

Pipe to `jq` for filtering:

```bash theme={null}
kanari agent --local | jq '.queues[] | select(.depth > 100)'
```

***

## API mode

API mode sends metrics to the Kanari backend on every cycle. The backend evaluates findings and sends Slack/email alerts when thresholds are breached.

```bash theme={null}
# After kanari login — API key is loaded from ~/.kanari/config automatically
kanari agent

# Or with an explicit token
kanari agent --token sk_your_key_here
```

On startup the agent validates the API key. If invalid, it exits immediately with a clear error.

***

## Running as a background service

### systemd

```ini theme={null}
# /etc/systemd/system/kanari-agent.service
[Unit]
Description=Kanari Agent — Celery queue monitor
After=network.target

[Service]
User=app
EnvironmentFile=/etc/kanari/env
ExecStart=/usr/local/bin/kanari agent --config /etc/kanari/kanari.yaml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

```bash theme={null}
sudo systemctl enable --now kanari-agent
```

### Docker

```dockerfile theme={null}
FROM python:3.12-slim
RUN pip install kanari
CMD ["kanari", "agent", "--local"]
```

```bash theme={null}
docker run -e REDIS_URL=redis://your-redis:6379/0 \
           -e CELERY_BROKER_URL=redis://your-redis:6379/0 \
           -e KANARI_API_KEY=sk_your_key \
           kanari-agent
```

### Docker Compose

```yaml theme={null}
services:
  kanari:
    image: python:3.12-slim
    command: sh -c "pip install kanari && kanari agent"
    environment:
      REDIS_URL: redis://redis:6379/0
      CELERY_BROKER_URL: redis://redis:6379/0
      KANARI_API_KEY: sk_your_key
    depends_on:
      - redis
    restart: unless-stopped
```


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