Troubleshooting & FAQ

Common issues when running Bhairava, and answers to frequently asked questions.

Services won't start

If the stack comes up unhealthy or a container keeps restarting, start with the API logs — they surface most misconfiguration and dependency errors.

docker compose -f /opt/bhairava/docker-compose.yml logs api-1 --tail 80

The most common cause on a fresh install is the database still initializing on first boot — give it 2–3 minutes and the API will connect on its own.

502 Bad Gateway in the browser

A 502 from the reverse proxy almost always means the API containers are still starting and not yet accepting connections. Wait ~3 minutes after docker compose up, then refresh the page.

Self-signed certificate warning

This is expected with the default bundled certificate — click Advanced → Proceed to continue. To replace it with your own certificate, copy the cert and key into /opt/bhairava/traefik/certs/ then restart the proxy:

docker compose -f /opt/bhairava/docker-compose.yml restart traefik

Agent won't connect

If an endpoint agent never appears in Agent Fleet, work through three checks:

• Add -k to the install one-liner to bypass the self-signed certificate during enrollment.
• Verify the enrollment token is still valid and has not expired or been revoked.
• Check the agent service status on the host:

sudo systemctl status bhairava-agent

Rate limiting (HTTP 429)

Repeated 429 Too Many Requests responses mean the rate-limit counters have tripped — usually during testing or a burst of logins. Flush the Redis counters to reset them:

docker compose -f /opt/bhairava/docker-compose.yml exec redis redis-cli FLUSHALL

OpenSearch won't start

OpenSearch requires a raised virtual-memory map count on the host. Set it before (or after) starting the stack:

# set now, and persist across reboots in /etc/sysctl.conf
sudo sysctl -w vm.max_map_count=262144

Out of disk space

Disk pressure is usually the Wazuh alert log ballooning under a high alert volume. Check how much the Docker data directory is using:

df -h /var/lib/docker

It is safe to truncate the already-processed alert log — Bhairava has already indexed these events downstream:

docker exec bhairava-wazuh-manager truncate -s 0 /var/ossec/logs/alerts/alerts.json

Reset the admin password

If you are locked out, reset a user's password by running a short snippet inside the API container. Pass the target email and new password as environment variables:

docker exec -e SEED_EMAIL="admin@example.com" -e SEED_PASS="NewPassword123!" \
  bhairava-api-1-1 python3 - <<'EOF'
import asyncio, os, bcrypt
# hash the new password and write it back via the ORM
# updates the matching user's hashed_password column
EOF

Frequently asked questions

Is an AI/LLM key required?

No. Bhairava has rule-based fallbacks for triage and correlation, so the pipeline keeps working without any model provider. Adding an Anthropic key enables the AI L1/L2 investigation on top of those fallbacks.

Is Keycloak required?

No. Local JWT authentication is the default and always available; Keycloak SSO is an optional add-on.

Can I run everything on one server?

Yes. The default Docker Compose deployment runs the full stack on a single host — 8 GB RAM minimum.

Which operating systems do agents support?

Linux, Windows, macOS, and Docker, all via zero-touch enrollment tokens.

How do I add threat-intel or notification keys?

Add them to /opt/bhairava/.env (or through the Integrations / Settings pages), then restart the API.