Configuration

Observer is configured entirely through environment variables loaded from /etc/vaultguardian/observer.env. The installer populates required values interactively; everything else has sensible defaults.

Environment variables

Variable	Default	Description
`LLM_URL`	`https://api.openai.com`	LLM API endpoint (OpenAI-compatible)
`LLM_MODEL`	`gpt-5-nano-2025-08-07`	Model identifier used for classification
`LLM_API_KEY`	(required)	API key for your LLM provider
`LLM_SLOTS`	`4`	Maximum concurrent LLM classification requests
`DOCKER_SOCKET`	`/var/run/docker.sock`	Docker socket path. Observer only tries Docker if this exists.
`DATA_DIR`	`/var/lib/observer`	Pattern store + SQLite persistence directory
`EXCLUDE_CONTAINERS`	(empty)	Comma-separated container names to skip
`RESEND_API_KEY`	(required for email)	Resend API key for email alerts
`ALERT_EMAIL_TO`	(required for email)	Alert recipient email address
`API_TOKEN`	(auto-generated)	Bearer token for dashboard API auth. Stored in `/etc/vaultguardian/dashboard.key`.
`REC_ENABLED`	`false`	Enable Response Evidence Capture (HTTP response sniffing)
`REC_NS_CONTAINER`	(empty)	Container name for namespace capture (e.g., `captain-nginx`)
`REC_FLOW_MAX_STATES`	`50000`	Max tracked TCP flows for request/response pairing
`REC_FLOW_RESP_ORPHAN_TIMEOUT`	`2s`	Response orphan expiry before inserting as unpaired
`REC_FLOW_REQ_EXPIRE_TIMEOUT`	`30s`	Request expiry when no response arrives
`JOURNALD_EXCLUDE_UNITS`	(empty)	Additional systemd units to suppress beyond the defaults

After editing /etc/vaultguardian/observer.env, restart the service to pick up changes:

vaultguardian restart

Minimum viable configuration

The absolute smallest config that gets Observer running with email alerts:

# /etc/vaultguardian/observer.env
LLM_API_KEY=sk-proj-...
RESEND_API_KEY=re_...
ALERT_EMAIL_TO=alerts@yourcompany.com

That's it. Docker auto-detection, journald monitoring, policy engine, seed patterns, and the full LLM pipeline all work with default values for everything else.

Common configurations

Bare metal server, no Docker

LLM_API_KEY=sk-proj-...
RESEND_API_KEY=re_...
ALERT_EMAIL_TO=alerts@yourcompany.com

# Prevent Observer from trying to connect to a Docker socket that doesn't exist
DOCKER_SOCKET=

Observer will watch journald only — sshd, sudo, kernel, systemd services. Policy engine handles SSH login alerts, user creation, and privilege changes.

Docker host with HTTP response evidence

LLM_API_KEY=sk-proj-...
RESEND_API_KEY=re_...
ALERT_EMAIL_TO=alerts@yourcompany.com

# Capture response bodies from the nginx container for evidence-aware verdicts
REC_ENABLED=true
REC_NS_CONTAINER=captain-nginx

With REC enabled, Observer sniffs the HTTP response inside the nginx container's network namespace before firing an alert. Attacks that got a 404 are downgraded; attacks that got a 200 OK with sensitive data are escalated.

Air-gapped with local Ollama

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

# Still need email for alerts (or configure an internal SMTP later)
RESEND_API_KEY=re_...
ALERT_EMAIL_TO=alerts@yourcompany.com

No traffic leaves the host. Accuracy drops compared to gpt-5-nano, but the pattern cache carries 97%+ of events once warm, so the LLM is only consulted on truly novel log lines.

Quiet noisy containers

EXCLUDE_CONTAINERS=redis,prometheus,grafana,loki

Observer will skip these containers entirely. Useful for known-chatty infrastructure services that generate large volumes of uninteresting logs. Note that this is different from suppression — excluded containers aren't even collected.

Trusted IPs

SSH logins from unknown source IPs fire an email alert by default. To mark IPs as trusted (your office, your VPN exit, your home IP), add them via the dashboard or the CLI. This is stored in Observer's SQLite database, not the env file — trusted IPs are runtime state, not configuration.

Trusted IP entries support:

Exact IP — 203.0.113.42
CIDR ranges — 203.0.113.0/24, 10.0.0.0/8
IPv6 — 2001:db8::/32

Any SSH login from an IP that matches a trusted entry is suppressed silently. All other SSH logins fire an immediate email.

See the Policy Engine section for the full list of host events that bypass or trigger on the trusted IP allowlist.

Data directory layout

Observer stores persistent state in DATA_DIR (default /var/lib/observer):

/var/lib/observer/
├── findings.db           # SQLite — all classifications, evidence, verdicts
├── patterns.db           # Pattern cache — exact / prefix / regex / substring tiers
├── catchalls.db          # Verified catch-all fingerprints
└── observer.state        # Runtime state (coordinator, reconciler cursors)

All files use SQLite in WAL mode with versioned migrations. Backups are a matter of copying these files; they're self-contained. State is preserved across binary updates.

Security notes

/etc/vaultguardian/observer.env contains API keys. The installer sets it to chmod 600 owned by root. Don't world-read it.
/etc/vaultguardian/dashboard.key contains the dashboard bearer token. Also chmod 600. This token authenticates dashboard connections to your Observer API.
Observer runs as root. This is required for journald access, Docker socket access, and AF_PACKET namespace capture. A future release may support capability-restricted operation.
The REST API on port 9090 requires bearer token auth. The installer generates a random token and stores it in /etc/vaultguardian/dashboard.key. The hosted dashboard uses this token via a server-side proxy — your token never leaves your browser or VaultGuardian's servers.

Configuration

On this page