Skip to main content

Install the connector

The Vesper Connector is a single static Go binary that runs on your Wazuh node and gives the agent its hands and eyes. It is strictly outbound: it dials Vesper over mTLS and keeps that session alive. Nothing ever connects into your network, and the Wazuh credentials it uses never leave the machine.

Requirements​

  • A Linux host on the Wazuh deployment (the connector targets localhost by default, so install it on the Wazuh node itself).
  • x86_64 or arm64.
  • systemd, curl (or wget), and root to install.
  • Outbound HTTPS/WSS egress to dl.vesper.wazuh.com (download) and connect.vesper.wazuh.com (the connector session). No inbound rules.

Install​

Copy the install command from the environment's card in the console (it embeds the environment's single-use enrollment token; see Environments):

curl -fsSL https://dl.vesper.wazuh.com/install.sh | sudo bash -s -- \
  --token=<ENROLLMENT_TOKEN> --connect=wss://connect.vesper.wazuh.com

The installer, all locally and outbound-only:

  1. downloads the static vesper-connector binary for your architecture (and verifies its published SHA-256 checksum when sha256sum is available),
  2. creates the service state directory and stages the connector CA,
  3. writes /etc/vesper/connector.yaml with localhost targets and blank credentials (they are auto-discovered on the host; see configuration),
  4. enrolls once with the token, which issues the connector's mTLS identity and stores it locally, and
  5. installs and starts the vesper-connector systemd service, which from then on runs tokenless.

Optional flags:

  • --enable-exec allows the agent to run gated shell commands on this host (off by default; see configuration before using it).
  • VESPER_DOWNLOAD_BASE=<mirror> overrides the download base for staging or air-gapped mirrors.

Verify​

systemctl status vesper-connector
journalctl -u vesper-connector -f

Within a heartbeat interval (30 seconds) the environment should show online in the console, along with the cluster metadata the connector reported.

Troubleshooting enrollment​

enrolment failed (token expired or already used? mint a new one) means exactly that: tokens are single-use. Mint a fresh one from the environment card and re-run the installer; an existing /etc/vesper/connector.yaml is kept, not clobbered.

Uninstall​

curl -fsSL https://dl.vesper.wazuh.com/uninstall.sh | sudo bash            # keep config
curl -fsSL https://dl.vesper.wazuh.com/uninstall.sh | sudo bash -s -- --purge  # remove everything