Installation & Setup

Stand up a full Bhairava manager on a fresh Linux server with a single command, then enroll endpoint agents across your fleet.

Prerequisites

Bhairava runs as a self-hosted Docker stack on a single Linux host (or a Kubernetes cluster for larger fleets). Provision a server that meets at least the minimum below — telemetry volume, agent count, and retention drive the recommended tier.

Server installation

The recommended path is the one-command installer. It runs on any supported distribution, detects and installs its dependencies, generates every secret, and brings the full stack online end-to-end.

# Ubuntu 20.04+ / Debian 11+ / RHEL 8+
curl -fsSL https://raw.githubusercontent.com/bhairava-soc/bhairava/main/deploy/scripts/install.sh \
  | sudo bash -s -- --domain soc.example.com

What the installer does

• detects your OS and installs Docker
• auto-generates all secrets (JWT key, DB password, encryption key, MinIO, Grafana)
• provisions a self-signed TLS certificate
• writes /opt/bhairava/.env and the compose file
• starts the full stack
• creates the admin user
• installs a systemd service
• prints your dashboard URL and credentials

Other methods

Docker Compose — clone the repo and bring the stack up manually (set your secrets in bhairava/.env first):

git clone https://github.com/bhairava-soc/bhairava.git && cd bhairava
sudo docker compose up -d

Kubernetes (Helm) — deploy the chart into a dedicated namespace:

helm install bhairava . -n bhairava --create-namespace -f values-production.yaml

Ansible — provision one or more hosts from your control node:

ansible-playbook -i inventory/production.yml site.yml

Air-gap — build a self-contained bundle, transfer it to the isolated host, and install offline:

bash deploy/airgap/bundle.sh --version 1.0.0
# transfer the bundle to the air-gapped host, then:
sudo ./install.sh --offline

Endpoint agents

Agents stream telemetry from your hosts back to the manager. Generate an enrollment token in the dashboard (Agent Fleet → Deploy Agent), then run the one-liner for the host's operating system.

Linux (systemd)

curl -k -sSL https://soc.example.com/api/agents/managed/setup/install.sh \
  | sudo bash -s -- --token <ENROLLMENT_TOKEN>

Windows (Scheduled Task)

# PowerShell (Administrator)
$env:BHAIRAVA_ENROLLMENT_TOKEN="<TOKEN>"; curl.exe -k -L https://soc.example.com/api/agents/managed/setup/install.ps1 -o "$env:TEMP\bhi.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\bhi.ps1"

macOS (launchd)

curl -k -sSL https://soc.example.com/api/agents/managed/setup/install-macos.sh \
  | sudo bash -s -- --token <ENROLLMENT_TOKEN>

Docker

docker run -d --name bhairava-agent --restart unless-stopped \
  --network host --pid host --privileged \
  -e BHAIRAVA_SERVER_URL=https://soc.example.com \
  -e BHAIRAVA_ENROLLMENT_TOKEN=<TOKEN> \
  bhairava/agent:latest

Each agent runs the security, system, network, and response modules (plus optional yara, osquery, and suricata collectors) and appears in Agent Fleet within ~30 seconds.

Configuration

All settings live in /opt/bhairava/.env (mode 600). The installer generates the secrets automatically; the integration keys are optional and unlock additional enrichment when set.

After editing, apply the changes by restarting the API replicas:

docker compose -f /opt/bhairava/docker-compose.yml restart api-1 api-2

Upgrading & uninstalling

Upgrade in place to a target version, then run any pending database migrations:

bash /opt/bhairava/upgrade.sh 1.2.0
docker compose exec api-1 python -m alembic upgrade head

To remove Bhairava entirely, stop the service, tear down the stack, and delete its data directories:

systemctl stop bhairava && systemctl disable bhairava
docker compose -f /opt/bhairava/docker-compose.yml down -v
rm -rf /opt/bhairava /var/lib/bhairava /var/log/bhairava