Projects, environments and keys

Where a run lands is decided entirely by the key that sent it. Nothing in the SDK names a project or an environment, because the key already does.

#Workspace

A workspace is created with your account. It owns the plan, the members, their roles and every project. Its slug is the first segment of every in-app URL: /<workspace>/<project>/traces.

Roles are owner, admin, member and viewer. See Feedback, comments and sharing.

#Projects

A project is one agent or product surface — "Support Agent", "Docs RAG". It owns its environments, keys, runs, saved views and settings.

• Create one from the project switcher or the command palette. Creating, renaming, archiving and deleting projects is owner and admin only.
• The Free plan allows three active projects. Sample projects do not count.
• Project settings renames, re-slugs, describes and recolours a project. The colour is the dot beside its name everywhere in the app.
• Deleting a project deletes everything under it.

#The sample project

Every new workspace gets a Support Agent (sample) project with synthetic runs that went through the real ingest pipeline, so the dashboard, traces and cost views have something true to show before you connect anything.

Sample projects do not accept API keys. You can reset or remove the sample, or create it again later, from the project list. Samples stay outside onboarding completion, the project limit and metering.

#Environments

Each project is created with three environments:

Every run belongs to exactly one environment. The environment picker in the header filters the dashboard, traces and every Analyze page, and your choice is saved per user and project. Custom environments are not available yet.

#Ingest keys

An ingest key selects the project and the environment.

• Create one in project setup, or in Project settings → API keys. Creating and revoking keys is owner and admin only; every role can see the key list without its secrets.
• The secret is shown once, in the response that creates it. Save it then.
• Revoke a key at any time; it stops working on the next request.
• Rotate without downtime by creating the new key before revoking the old one.

Keys are server credentials. Never put one in browser code, a NEXT_PUBLIC_ variable, or a repository.

TRACEHATCH_API_KEY=th_test_…

The browser never asks you to paste an existing secret back in: setup keeps the new secret in component memory only, masks it by default, and says explicitly when copying will include it. Leaving the page or switching projects discards it.

#Agents

An agent is a named actor inside a project, taken from the nearest package.json name or TRACEHATCH_AGENT. Several agents can share one project — a planner and a worker, or a web server and a queue consumer — and the dashboard breaks runs, failure rate and cost down per agent once more than one is named.

#Personal access tokens

Personal access tokens (th_pat_…) are for reading your own data from scripts and dashboards. They act as you, with the scopes you choose, and they are not ingest keys — they cannot send spans.

Create them in Account → Tokens. See HTTP API.

#Plan and usage

Settings → Plan & usage shows the workspace's trace count for the current UTC month against its allowance, and explains the sampling and hard-stop policy. A meter appears in the sidebar at 50% of the allowance, and the workspace owner is emailed at 80% and 100%. See Plans, quotas and retention.