Configuration

For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to page URLs.

Set LOOKOUT_CONFIG to a JSON configuration file. Unknown keys and invalid values fail closed. Relative paths resolve from the configuration file’s directory.

LOOKOUT_CONFIG=/etc/lookout/lookout.json lookout config-check

Start from config/lookout.example.json in a source checkout.

Top-level sections

Section	Purpose
`server`	Bind address, port, loopback administration, approved client addresses, and optional TLS files
`storage`	Data directory, encryption requirement, event retention, and audit retention
`auth`	Bearer credential registry, legacy token environment reference, and optional Tailscale identity auth
`collectors`	Collector key registry and continuous Tailscale log collection
`secrets`	Allowlisted environment-variable and owner-only file references
`export`	Explicit opt-in raw event export
`consoleSync`	Raw-log-free topology, coverage, case, and sensor-health synchronization
`webhook`	Durable Alert delivery over HTTPS

Minimal local configuration

{
  "schemaVersion": 1,
  "server": {
    "host": "127.0.0.1",
    "port": 4173,
    "allowLoopbackAdmin": true,
    "approvedSourceAddresses": ["127.0.0.1", "::1", "::ffff:127.0.0.1"]
  },
  "storage": {
    "dataDirectory": "../data",
    "requireEncryption": false,
    "retentionDays": 14,
    "auditRetentionDays": 90
  },
  "auth": {
    "credentialsFile": null,
    "legacyTokenEnvironment": null
  }
}

A non-loopback bind requires a credential file or legacy token reference. Production deployments should also require storage encryption and terminate TLS before exposing the service to a network.

Secret references

Configuration stores references, not secret values. Map a logical name to an environment variable or an owner-only file, then use the logical name from the feature configuration.

{
  "secrets": {
    "environment": {
      "webhook-token": "LOOKOUT_WEBHOOK_TOKEN"
    },
    "files": {
      "tailscale-token": "/etc/lookout/tailscale-token"
    }
  }
}

Literal credentials in export, console sync, and webhook settings are rejected.

Storage encryption

Generate an owner-only 256-bit master key:

lookout storage-keygen /etc/lookout/master-key

Then set storage.requireEncryption to true and provide the key at runtime:

LOOKOUT_MASTER_KEY_FILE=/etc/lookout/master-key \
LOOKOUT_CONFIG=/etc/lookout/lookout.json \
lookout doctor

Tailscale collection

{
  "collectors": {
    "tailscale": {
      "enabled": true,
      "tailnet": "example.com",
      "credentialReference": "tailscale-token",
      "authMode": "api-token",
      "baseUrl": "https://api.tailscale.com",
      "modes": ["network-flow", "configuration-audit"],
      "pollIntervalSeconds": 15,
      "initialLookbackSeconds": 300,
      "ingestionDelaySeconds": 30
    }
  }
}

Use read-only logs:network:read and logs:configuration:read scopes for the selected modes. Network-flow availability also depends on the tailnet plan and logging settings.

Alert webhook

{
  "webhook": {
    "enabled": true,
    "type": "https",
    "endpoint": "https://hooks.example.test/lookout",
    "credentialReference": "webhook-token",
    "batchSize": 50,
    "maxPending": 10000,
    "flushIntervalSeconds": 15,
    "cooldownSeconds": 300
  }
}

Delivery uses a durable outbox, stable idempotency keys, bounded retry, and cooldown suppression. Fix a blocked endpoint or credential, then run lookout webhook-resume.

Validate before restart

LOOKOUT_CONFIG=/etc/lookout/lookout.json lookout config-check
LOOKOUT_CONFIG=/etc/lookout/lookout.json \
LOOKOUT_MASTER_KEY_FILE=/etc/lookout/master-key \
lookout preflight-upgrade

Get started

Configure

Understand Lookout

Detection engineering

Operate

Maintain these docs

Top-level sections

Minimal local configuration

Secret references

Storage encryption

Tailscale collection

Alert webhook

Validate before restart

​Top-level sections

​Minimal local configuration

​Secret references

​Storage encryption

​Tailscale collection

​Alert webhook

​Validate before restart

Top-level sections

Minimal local configuration

Secret references

Storage encryption

Tailscale collection

Alert webhook

Validate before restart