Installation

Observer runs as a single Go binary managed by systemd. The installer sets up the service, prompts for required credentials, and starts Observer in under a minute on any reasonably modern Linux distribution.

One-command install

curl -fsSL https://raw.githubusercontent.com/VaultGuardian/observer/main/install.sh | sudo bash

The installer will:

1. Detect your platform (systemd required) and install the binary to /usr/local/bin/observer
2. Create the /etc/vaultguardian/observer.env config file
3. Prompt for required credentials (see Configuration)
4. Install and enable the observer.service systemd unit
5. Start Observer immediately

Once the installer finishes, verify the service is running:

sudo systemctl status observer
vaultguardian logs

Connect to the hosted dashboard

The hosted dashboard at vaultguardian.io/dashboard gives you a web UI for viewing events, managing patterns, correcting classifications, and monitoring pipeline health — all without SSH.

1. Sign up

Create a free account at vaultguardian.io/signup. No credit card required.

2. Get your API token

The installer generates a bearer token at /etc/vaultguardian/dashboard.key. This token authenticates the dashboard's connection to your Observer instance.

sudo cat /etc/vaultguardian/dashboard.key

Copy this token — you'll paste it in the next step.

3. Add your instance

In the dashboard, click Add Instance and enter:

• Instance Name — a label for this server (e.g., "Production", "Staging")
• API URL — your server's Observer API endpoint: http://YOUR_SERVER_IP:9090
• Bearer Token — the contents of /etc/vaultguardian/dashboard.key

The dashboard tests the connection before saving. If the test fails, make sure port 9090 is open in your firewall and Observer is running.

4. You're connected

The dashboard will start polling your Observer instance every 30 seconds. You'll see live pipeline stats, security events, pattern cache data, and the human correction workflow.

Prerequisites

Before you install, have these ready:

• Root or sudo access on the target server
• A Linux distribution with systemd (Ubuntu, Debian, Rocky, RHEL, Arch, etc.)
• An OpenAI API key — or an OpenAI-compatible endpoint URL (Ollama, vLLM, self-hosted)
• An alert email address where confirmed threats will be delivered
• A Resend API key if you want email alerts via Resend (recommended)
• A VaultGuardian account (optional) — sign up free at vaultguardian.io/signup to connect the hosted dashboard

Docker is optional

Observer auto-detects Docker and monitors container logs via the Docker socket API if present. If Docker isn't installed, Observer still runs — it watches the host through journald, catches SSH logins, user creation, privilege changes, and any credential or key material that appears in log streams. Bare metal with just sshd is a fully supported deployment.

Manual install

If you prefer to inspect the installer before running it, or need to customize placement on locked-down systems:

# 1. Download the binary from the latest release
curl -fsSL https://github.com/VaultGuardian/observer/releases/latest/download/observer \
  -o /usr/local/bin/observer
sudo chmod +x /usr/local/bin/observer

# 2. Create the config directory and env file
sudo mkdir -p /etc/vaultguardian /var/lib/observer
sudo touch /etc/vaultguardian/observer.env
sudo chmod 600 /etc/vaultguardian/observer.env

# 3. Populate the env file with required variables
#    See: /docs/observer/configuration for the full list
sudo nano /etc/vaultguardian/observer.env

# 4. Install the systemd unit file
#    (available in the repo at scripts/observer.service)

# 5. Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable --now observer

After the first start, tail the logs to confirm the pipeline is initializing:

sudo journalctl -u observer -f

You should see lines reporting the journald watcher starting, the Docker socket connecting (if applicable), the pattern store loading, and the first LLM health check.

Air-gapped / self-hosted LLM

Observer works with any OpenAI-compatible inference endpoint. To run fully air-gapped, point it at a local Ollama or vLLM instance:

LLM_URL=http://localhost:11434
LLM_MODEL=llama3.1:8b-instruct-q4_K_M
LLM_API_KEY=unused

Accuracy is lower than gpt-5-nano on smaller open models, but the cache carries most of the load once it's warm. In production, the LLM is called on less than 3% of events — the pattern store handles the rest deterministically.

See Configuration for the full environment variable reference.

Updating

Observer ships updates as GitHub releases. Use the CLI to update to the latest or a specific version:

vaultguardian update          # latest release
vaultguardian update v1.0  # specific version

The CLI downloads the binary, replaces it at /usr/local/bin/observer, and restarts the service. State in /var/lib/observer (SQLite findings, pattern store) is preserved across updates.

Uninstalling

vaultguardian uninstall

This stops the service, removes the systemd unit and binary, and prompts before deleting state. If you want to leave the findings database in place for forensic review, choose "keep" when prompted.