Agent Installation

The Basira agent runs near your database, collects telemetry, and ships it to the Basira API.

Prerequisites

Network access from the agent to your database
A Basira API key (available from the dashboard)
A dedicated monitoring database user — see PostgreSQL Setup or ClickHouse Setup

Install

The simplest way to run the agent. Works anywhere Docker is available.

1. Create a config file:

config.yaml

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_your_api_key

databases:
  - name: primary-pg
    dsn: postgres://basira_monitor:password@pg-primary:5432/app?sslmode=require
    poll_interval: 10s

2. Run the agent:

docker run -d \
  --name basira-agent \
  --restart unless-stopped \
  -v $(pwd)/config.yaml:/config.yaml \
  -e BASIRA_CONFIG=/config.yaml \
  ghcr.io/usebasira/basira-agent:latest

3. Verify:

docker logs basira-agent --tail=20

To monitor more databases, add entries under databases in your config file and restart the container.

For Kubernetes clusters with Helm 3+.

1. Create a values file:

values.yaml

apiKey: "dbm_ak_your_api_key"
apiEndpoint: "https://api.usebasira.com"
healthListenAddr: ":8081"
databases:
  - name: primary-pg
    dsn: postgres://basira_monitor:password@pg-primary:5432/app?sslmode=require
    pollInterval: 10s

2. Install with Helm:

helm install basira-agent oci://ghcr.io/usebasira/charts/basira-agent \
  -f values.yaml

3. Verify:

kubectl get pods -l app.kubernetes.io/name=basira-agent
kubectl logs deployment/basira-agent --tail=20

The default chart enables /healthz on port 8081:

kubectl port-forward deployment/basira-agent 8081:8081
curl -s http://localhost:8081/healthz | jq .

Multiple Databases

To monitor more databases, add entries under databases in your config file:

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_your_api_key

databases:
  - name: primary-pg
    dsn: postgres://basira_monitor:password@pg-primary:5432/app?sslmode=require
  - name: analytics-ch
    dsn: clickhouse://basira_monitor:password@ch-analytics:9000/analytics
    poll_interval: 30s

If using Helm, the same structure applies but field names use camelCase (e.g. pollInterval instead of poll_interval). See the Helm values reference below.

The full YAML config format is documented in Agent Configuration.

Helm values.yaml Reference

Field	Required	Description
`apiKey`	Yes	Basira API key
`apiEndpoint`	No	Basira API URL. Defaults to `https://api.usebasira.com` in the chart
`healthListenAddr`	No	Health endpoint listen address
`databases`	Yes	List of databases to monitor
`databases[].name`	Yes	Name shown in logs and health output
`databases[].dsn`	Yes	PostgreSQL or ClickHouse connection string
`databases[].engine`	No	Override engine detection if needed
`databases[].pollInterval`	No	Collection interval. Defaults to `10s`

Engine is auto-detected from the DSN prefix: clickhouse:// or tcp:// → ClickHouse, everything else → PostgreSQL.

Existing Secrets (Helm)

If you manage secrets externally (e.g. Sealed Secrets, External Secrets), the secret must contain a config.yaml key with the full YAML config:

kubectl create secret generic basira-agent-config \
  --from-file=config.yaml=./config.yaml

helm install basira-agent oci://ghcr.io/usebasira/charts/basira-agent \
  --set existingSecret=basira-agent-config \
  --set 'databases[0].name=placeholder'

The placeholder entry forces the chart to skip its own Secret creation. The real config comes from your secret. Your API key should live inside config.yaml under api.key.

Once the agent is running, open Basira and confirm the database appears and starts reporting telemetry.