---
title: "Operations runbook"
description: "Where the data lives, how to reset it, and what to do when something does not show up."
source: "https://getloggerhead.com/docs/reference/operations-runbook/"
---

# Operations runbook

> Where the data lives, how to reset it, and what to do when something does not show up.

## Where the data lives

Each environment has its own database file in the data directory. The app is sandboxed, so on a Mac the data directory is in the app container:

```text
~/Library/Containers/com.rubics.Loggerhead/Data/Library/Application Support/Loggerhead/
├── workspaces.json
└── workspaces/<workspace>/<environment>/loggerhead.db
```

**Settings › Data** shows the path of the open environment in the **Storage** card, and **Open folder** shows the file in Finder.

`DATA_DIR` moves the whole data directory. `LOGGERHEAD_DB_PATH` names one database file, and the app opens that file in place of the file of the open environment.

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

## Reset the database

To delete every log, trace, and metric of the open environment, open **Settings › Data** and press **Clear all data** in the **Storage** card. The finding history stays.

To start again with a new file:

1. Quit Loggerhead.
2. Delete `loggerhead.db` and `loggerhead.db.wal` in the folder of the environment.
3. Open Loggerhead. It creates a new file.

## Look at the file directly

DuckDB allows one process on the file. While Loggerhead runs, a second opener fails, even read-only. Read the data through the [MCP server](/docs/mcp-server/what-the-server-exposes/) instead. To open the file in the DuckDB CLI, quit Loggerhead first.

## Retention

The app keeps `retention_days` of data and runs cleanup on a schedule. Change the number in **Settings › Data**. To empty the database now, open **Settings › Data › Storage** and press **Clear all data**. That step deletes every log, trace, and metric, and you cannot undo it.

## Troubleshooting

**Nothing shows up.** Read the effective ports on the **Collectors** page, or ask your AI coding tool to call `get_receiver_info`. Confirm the producer or the branch sends to that port. Confirm the branch stamps `loggerhead.collector.id`. The **Collectors** page shows last-seen and error counts for each collector.

**The port moved.** Another program holds 4317 or 4318. The root moved along the ladder: 4317 to 14317 to 24317, and 4318 to 14318 to 24318.

The app tells you when this happens. The root node on the **Collector map** shows a warning triangle and the line "The preferred port was busy. Open Collectors to see the ports in use." The **Add a source** sheet shows a "Port moved" badge. Copy the effective port from **Collectors › Loggerhead receiver › Connection**. See [Ports and the effective port](/docs/getting-started/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 receiver's certificate. Loopback producers are exempt, so if it works locally and not remotely, the token or TLS is the difference.

**A page says "Database not open".** The app could not open its database file. Another copy of Loggerhead may hold it, because DuckDB allows one writer. Quit every copy, then open the app again.