Workspaces and environments

Loggerhead keeps more than one project on one Mac, and more than one deployment of each project, without the telemetry mixing. Three words carry the model.

Word	Meaning	Owns
Workspace	One project.	One receiver port pair.
Environment	One deployment of that project: Local, Staging, Production, or a name you choose.	One database file, its alerts, and its lint findings.
Tag	The resource attribute deployment.environment.name on a record. The older key deployment.environment works too.	The choice of environment inside a workspace.

The app reads one environment at a time. Every page shows that environment and nothing else. The page caption says which one: “Loggerhead · Local”.

How a record finds its environment

1. The sender picks the workspace by the port it exports to. Each workspace owns one port pair from the ladder: 4317/4318 for the first, 4319/4320 for the second, and so on. See Ports and the effective port.
2. The sender picks the environment with the resource attribute deployment.environment.name, the name OpenTelemetry semantic conventions 1.27 gave it. The older deployment.environment works too; when a record carries both, the new key wins. A record tagged staging lands in the Staging database and nowhere else.
3. A record with no tag lands in Local.
4. A record whose tag matches no environment lands in Local too, and the Linting page reports it as “Unknown environment” with a one-click “Create environment” action. See What it checks.

Set the tag on the exporter, or on the branch collector in that deployment. The Docker branch example shows the snippet.

Switch with one click

The workspace button sits at the top of the sidebar. It shows the workspace tile, the name, and the current environment. Under it, one chip per environment: click a chip to switch. The pages load the other database at once and keep the row you had selected in the sidebar.

Click the button for the full list: every workspace with its environments, a search field, “New workspace…”, and “Manage workspaces…”.

Create a workspace or an environment

“New workspace…” asks for a name, an icon, a colour, and the first environment. It shows the receiver ports it picked for the workspace. “Add environment” asks for a name and a kind, and shows the tag the name gives: deployment.environment.name = staging.

The Workspaces page under MANAGE lists every workspace with its ports, and every environment with its tag, its database size, and whether it received records in the last minute. It renames, re-tags, and deletes. A delete asks first and names the size that goes away.

Free and Pro

Free has one workspace with one environment, and no Workspaces page. Pro has unlimited workspaces and environments. A Pro licence that lapses keeps every workspace readable; only a new one is blocked, and nothing is deleted. See Pricing.

Production

You can create a Production environment. Choosing it shows a caution, and the caution is the whole story: Loggerhead is not designed for production traffic yet. It keeps working, but one Mac holds the data, retention is short, and there is no on-call. Keep your production platform for production.

Where the files are

Every environment has its own file. The app is sandboxed, so the files are in the app container:

~/Library/Containers/com.rubics.Loggerhead/Data/Library/Application Support/Loggerhead/workspaces/<workspace>/<environment>/loggerhead.db

The folder names are the workspace and environment names in lower case. Each space or other mark becomes a hyphen. Settings › Data shows the path of the open environment in the Storage card.

The first start after the update moves the single database you had into workspace “Default”, environment “Local”, on ports 4317/4318. Nothing is copied and nothing is lost.

Ask your AI tool

Every MCP tool takes optional workspace and environment arguments. Omitted, they mean the pair the app shows. Call list_environments for the names. See Tools reference.