Operations runbook

Where the data lives

The engine resolves the database path in this order: LOGGERHEAD_DB_PATH, then DATA_DIR/loggerhead.db, then the per-OS default. On a Mac the default is:

~/Library/Application Support/Loggerhead/loggerhead.db

The schema is versioned and migrates at start. There is no manual migration step.

Reset the database

1. Quit Loggerhead.
2. Delete the database file.
3. Open Loggerhead. It creates a new file.

Look at the file directly

DuckDB allows one process on the file. While the engine runs, a second opener fails, even read-only. Query the API or the MCP server instead. To open the file in the DuckDB CLI, quit Loggerhead first.

Retention

The engine keeps retention_days of data and runs cleanup on a schedule. Run it now with POST /api/cleanup.

Troubleshooting

Nothing shows up. Check GET /api/health for the effective ports. Confirm the producer or the branch sends to that port. Confirm the branch stamps loggerhead.collector.id. GET /api/collectors shows last-seen and error counts per collector.

The port moved. Another program holds 14317 or 14318. The root moved along the ladder. Copy the effective port from the Collectors page. See Ports and the effective port.

A remote branch is rejected. The token on the branch does not match ingest_token, or the branch does not trust the engine’s certificate. Loopback producers are exempt, so if it works locally and not remotely, the token or TLS is the difference.

The app shows Disconnected. The engine is not running, or the app cannot reach the API port. Quit and reopen the app. The app reads the effective API port from the engine at start.