---
title: "Workspaces and environments"
description: "One workspace per project, one environment per deployment. Each workspace owns a port pair, each environment owns a database, and the app reads one environment at a time."
source: "https://getloggerhead.com/docs/getting-started/workspaces-and-environments/"
---

# Workspaces and environments

> One workspace per project, one environment per deployment. Each workspace owns a port pair, each environment owns a database, and the app reads one environment at a time.

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](/docs/getting-started/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](/docs/telemetry-linting/what-it-checks/).

Set the tag on the exporter, or on the branch collector in that deployment. The [Docker branch example](/docs/collectors/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](/#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:

```text
~/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](/docs/mcp-server/tools-reference/).