# Configuration reference

All knobs can be set via environment variables. The agent loads `.env` through `dotenv` on boot (`server/core/keys.js`). Copy `.env.example` to get started.

```bash
cp .env.example .env
```

---

## Agent identity

| Variable | Default | Description |
|----------|---------|-------------|
| `SERVER_SEED` | *auto-generated* | 32-byte secret as **64 hex** chars. Root of HMAC capabilities + admin proofs. **Keep offline / mode 0600.** |
| `SERVER_PUBLIC_KEY` | *derived* | 32-byte public key as **64 hex**. Clients dial this. Auto-synced to `.env` when seed loads. |
| `SERVER_KEY` | — | Alias accepted for `SERVER_SEED` (legacy). Prefer `SERVER_SEED`. |

Treat `SERVER_SEED` like a root password. Prefer `pd1.` invites for operators.

---

## Roles & access control

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_DEFAULT_ROLE` | `viewer` | Baseline role: `viewer` \| `operator` \| `admin` |
| `PEARDATA_ADMIN_KEYS` | empty | Comma-separated peer pubs always elevated to **admin** |
| `PEARDATA_ALLOWLIST` | empty | If **non-empty**, only listed peers may connect |
| `PEARDATA_INSECURE_OPEN_ADMIN` | off | `1` → every peer is admin. **Dev only.** |

---

## Runtime paths & limits

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_DATA_DIR` | `./data` | Peer policy JSON + `audit.log` |
| `PEARDATA_HOME` | OS home | Root for client identity + bookmarks (`~/.config/peardata/`) |
| `PEARDATA_STORAGE` | — | Electron/Pear storage dir override (bookmarks prefer `Pear.config.storage`) |
| `PEARDATA_RATE_LIMIT_RPM` | `120` | Per-peer RPC requests per minute |
| `PEARDATA_MAX_RECONNECT` | `20` | Client manager reconnect attempts per peer |
| `PEARDATA_JOURNAL` | **on** | Host `journalctl` for Logs / `queryLogs` (Linux). Set `0` to disable. Installer adds `peardata` to `systemd-journal` and sets unit `SupplementaryGroups` |

```
data/
├── peer-policy.json
├── retention.json      # Data Manager policy (after first boot / Save)
├── audit.log
└── corestore/          # HyperDB warm history
```

Permissions: directory `0700`. Do **not** commit `data/` or `.env`.

---

## Metrics pipeline

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_SAMPLE_MS` | `1000` | Collector interval |
| `PEARDATA_TIER0_POINTS` | `3600` | High-res ring size (~1h @ 1s); seeds Data Manager |
| `PEARDATA_TIER1_POINTS` | `1440` | Downsampled ring size; seeds Data Manager |
| `PEARDATA_TIER1_EVERY` | `60` | Samples per tier1 average (also HyperDB warm flush) |
| `PEARDATA_WARM_RETENTION_MS` | `7776000000` (90d / **3m**) | Soft age limit for HyperDB warm points (seed; default preset **3 months**) |
| `PEARDATA_WARM_MAX_BYTES` | `1073741824` (1 GiB) | Soft corestore budget; set `0` for unlimited |
| `PEARDATA_WARM_MAX_POINTS` | `0` | Cap on warm points (`0` = unlimited) |
| `PEARDATA_AUTO_PRUNE` | on | `0` disables scheduled prune on boot |
| `PEARDATA_WARM_ALL_CHARTS` | off | `1` flushes high-cardinality instance charts (disk/net/cgroup/docker) to HyperDB; default is static catalog only |

Live retention is edited in the desktop **Settings → Data** tab (admin) and persisted to `$PEARDATA_DATA_DIR/retention.json`. Env values only seed the file on first boot. UI walkthrough: [user-guide/settings.md](../user-guide/settings.md).

---

## HyperDB storage & sync

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_HYPERDB` | on | `0` / `off` disables HyperDB |
| `PEARDATA_SWARM` | off | `1` enables Hyperswarm Corestore replication |
| `PEARDATA_DOCKER` | off* | `1` enables Docker Engine collector (socket + per-container cpu/mem + **human names**). *Installer sets `1` when Docker is detected and adds `peardata` to the `docker` group |
| `PEARDATA_DOCKER_SOCKET` | auto | Socket path for names + API (`/var/run/docker.sock`, `/run/docker.sock`, Podman). Installer writes the detected path. See [user-guide/containers.md](../user-guide/containers.md) |
| `PEARDATA_CGROUPS` | on (Linux) | `0` disables cgroup v2 CPU/mem/IO charts; `1` forces on |
| `PEARDATA_CGROUPS_MAX` | `32` | Max cgroup instances to chart |
| `PEARDATA_SENSORS` | on (Linux) | `0` disables hwmon/thermal charts |
| `PEARDATA_DISK_PARTITIONS` | off | `1` charts partition devices (higher cardinality) |
| `PEARDATA_IRQ_MAX` | `24` | Max per-IRQ interrupt charts |
| `PEARDATA_PROCESSES` | **on** (Linux) | Top process charts (`processes.top_*`). Set `0` to disable. Processes **tab** works whenever `/proc` is readable |
| `PEARDATA_PROCESSES_TOP` | `8` | How many processes to keep in top charts (max 32) |
| `PEARDATA_MYSQL` | off | MySQL/MariaDB TCP probe (+ optional stats URL) |
| `PEARDATA_MYSQL_URL` | `127.0.0.1:3306` | MySQL host:port |
| `PEARDATA_MYSQL_STATS_URL` | — | Optional HTTP key=value stats |
| `PEARDATA_APACHE` | off | Apache `server-status?auto` |
| `PEARDATA_APACHE_URL` | `http://127.0.0.1/server-status?auto` | |
| `PEARDATA_MEMCACHED` | off | Memcached `stats` |
| `PEARDATA_MEMCACHED_URL` | `127.0.0.1:11211` | |
| `PEARDATA_MONGODB` | off | MongoDB TCP probe |
| `PEARDATA_MONGODB_URL` | `127.0.0.1:27017` | |
| `PEARDATA_RABBITMQ` | off | RabbitMQ management API |
| `PEARDATA_RABBITMQ_URL` | `http://guest:guest@127.0.0.1:15672` | |
| `PEARDATA_PROMETHEUS` | off | Generic Prometheus text scrape |
| `PEARDATA_PROMETHEUS_URLS` | — | Comma-separated scrape URLs |
| `PEARDATA_STATSD` | off | StatsD UDP ingest on localhost |
| `PEARDATA_STATSD_PORT` | `8125` | |
| `PEARDATA_SMART` | off | `smartctl` disk SMART |
| `PEARDATA_NVIDIA` | off | `nvidia-smi` GPU metrics |
| `PEARDATA_IPMI` | off | `ipmitool sensor` |
| `PEARDATA_EBPF` | on (Linux) | Embedded eBPF-family helper / JS fallback; `0` disables |
| `PEARDATA_EBPF_PATH` | — | Optional external NDJSON bridge path |
| `PEARDATA_HELPER_DIR` | tmp/helpers | Where embedded helpers are extracted |
| `PEARDATA_IOPING` | off | Active disk latency probe |
| `PEARDATA_ZFS` | auto | ZFS ARC/pool when kstat present |
| `PEARDATA_BCACHE` | auto | BCache when `/sys/fs/bcache` exists |
| `PEARDATA_DMCACHE` | auto | dm-cache when device-mapper cache present; `0` disables |
| `PEARDATA_FS_STATS` | on (Linux) | ext4/xfs lifetime IO stats; `0` disables |
| `PEARDATA_KAFKA` | off | Kafka exporter scrape |
| `PEARDATA_KAFKA_URL` | `http://127.0.0.1:9308/metrics` | |
| `PEARDATA_NATS` | off | NATS `/varz` |
| `PEARDATA_NATS_URL` | `http://127.0.0.1:8222` | |
| `PEARDATA_UNBOUND` | off | Unbound stats |
| `PEARDATA_SOCKETS` | on (Linux) | TCP/UDP socket state charts |
| `PEARDATA_PARENT` | off | `1` enables parent peer fleet aggregator |
| `PEARDATA_PARENT_PEERS` | empty | Comma-separated child agent public keys (64 hex) |
| `PEARDATA_PARENT_PEERS_FILE` | — | Optional file with one child pubkey per line |
| `PEARDATA_PARENT_SEED` | — | Optional `SERVER_SEED` of children for admin proof dial |
| `PEARDATA_PARENT_POLL_MS` | `5000` | How often parent polls children |
| `PEARDATA_NGINX` | off | `1` enables nginx stub_status collector |
| `PEARDATA_NGINX_URL` | `http://127.0.0.1/nginx_status` | stub_status URL |
| `PEARDATA_REDIS` | off | `1` enables Redis INFO collector |
| `PEARDATA_REDIS_URL` | `127.0.0.1:6379` | Redis host:port or `redis://` URL |
| `PEARDATA_POSTGRES` | off | `1` enables Postgres TCP probe (+ optional stats URL) |
| `PEARDATA_POSTGRES_HOST` | `127.0.0.1` | Postgres host |
| `PEARDATA_POSTGRES_PORT` | `5432` | Postgres port |
| `PEARDATA_POSTGRES_STATS_URL` | — | Optional HTTP key=value stats sidecar |
| `PEARDATA_EXPORT_DIR` | — | Write `snapshot-*.json` from export job/RPC |
| `PEARDATA_PUSHGATEWAY_URL` | — | POST Prometheus text (Pushgateway-compatible) |
| `PEARDATA_WEBHOOK_URL` | — | POST anomaly JSON on alert fire |
| `PEARDATA_WEBHOOK_SECRET` | — | HMAC key for `X-PearData-Signature` |
| `PEARDATA_WEBHOOK_SIGN` | on (if secret) | `0` disables HMAC signing |
| `PEARDATA_WEBHOOK_LEGACY_SECRET` | off | `1` also send plaintext `X-PearData-Secret` |
| `PEARDATA_NOTIFY_CLEARS` | off | `1` also webhook when anomaly clears |
| `PEARDATA_NOTIFY_MIN_SEVERITY` | `warning` | `warning` \| `critical` |
| `PEARDATA_ANOMALY_MODE` | `threshold` | `threshold` \| `zscore` \| `hybrid` |
| `PEARDATA_ANOMALY_WINDOW` | `120` | Rolling samples for z-score / retrain |
| `PEARDATA_ANOMALY_WARN_Z` | `2` | Warn at \|z\| ≥ this |
| `PEARDATA_ANOMALY_CRIT_Z` | `3` | Critical at \|z\| ≥ this |
| `PEARDATA_REST_TUNNEL` | off | `1` expose REST over HyperDHT (holesail-style) |
| `PEARDATA_REST_TUNNEL_SEED` | — | 64-hex seed for stable tunnel public key |
| `PEARDATA_PEARDOCK` | off | `1` enable PearDock bridge (remap remote docker charts) |
| `PEARDATA_PEARDOCK_PEERS` | empty | Comma-separated dock/agent public keys |
| `PEARDATA_PEARDOCK_PEERS_FILE` | — | One pubkey per line |
| `PEARDATA_PEARDOCK_SEED` | — | Optional admin seed for dial |
| `PEARDATA_PEARDOCK_POLL_MS` | `5000` | Bridge poll interval |

Storage: `$PEARDATA_DATA_DIR/corestore` (named core `peardata-meta`).

Full guide: [STORAGE-HYPERDB.md](./STORAGE-HYPERDB.md).

```bash
npm run build:db   # regenerate spec/ after schema edits
```

---

## REST API (agent-style)

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_REST` | on | Set `0` / `off` to disable HTTP API |
| `PEARDATA_REST_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` exposes LAN — firewall!) |
| `PEARDATA_REST_PORT` | `18888` | HTTP port |
| `PEARDATA_REST_CORS` | `*` | `Access-Control-Allow-Origin` |

See [REST-API.md](./REST-API.md).

---

## Logging

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `LOG_JSON` | off | `1` → JSON lines |

---

## Healthcheck / soak / tests

| Variable | Default | Description |
|----------|---------|-------------|
| `PEARDATA_HEALTH_KEY` | `SERVER_PUBLIC_KEY` | Key for remote ping |
| `HEALTHCHECK_TIMEOUT_MS` | `8000` | Dial timeout |
| `SOAK_DURATION_MS` | `60000` | Soak length |
| `SOAK_INTERVAL_MS` | `500` | Soak RPC interval |
| `SKIP_INTEGRATION` | off | `1` skips DHT integration test |

---

## npm scripts

| Script | Purpose |
|--------|---------|
| `npm start` / `npm run dev` | Pear desktop |
| `npm run start:server` | Agent (P2P + REST) |
| `npm run start:server:bin` | `bin/peardata-server.mjs` |
| `npm test` | brittle suite |
| `npm run mint-invite -- [role] [ttlMs]` | Offline `pd1.` invite |
| `npm run build:db` | Regenerate HyperDB `spec/` |
| `npm run healthcheck` | Liveness |
| `npm run soak` | Load exercise |

---

## systemd

Unit: `deploy/peardata.service`  
WorkingDirectory: `/opt/peardata`  
EnvironmentFile: `/opt/peardata/.env`