> ## Documentation Index
> Fetch the complete documentation index at: https://devlookout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the server, storage, collectors, secrets, exports, and Alert delivery.

> For the complete documentation index, see [llms.txt](https://devlookout.com/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.

```sh theme={null}
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

```json theme={null}
{
  "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
  }
}
```

<Warning>
  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.
</Warning>

## 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.

```json theme={null}
{
  "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:

```sh theme={null}
lookout storage-keygen /etc/lookout/master-key
```

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

```sh theme={null}
LOOKOUT_MASTER_KEY_FILE=/etc/lookout/master-key \
LOOKOUT_CONFIG=/etc/lookout/lookout.json \
lookout doctor
```

## Tailscale collection

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```sh theme={null}
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
```