Agents and API keys
An agent is an authenticated identity that does work on your board on your behalf. Every Claude Code session, every Meshly CLI session, every Build Station–spawned worker uses an agent identity to authenticate to your Meshly Build instance.
This page covers managing those identities — when to create one, how to scope its access, what each role means, and how to rotate keys safely.
When to create a new agent vs reuse one
Default to fewer agents, not more.
Create a new agent when you genuinely need a separate identity:
- Different person. Each team member should have their own agent (so the board shows who did what).
- Different machine. If you run the same person's identity on a laptop AND a Build Station, the board can't tell sessions apart. Two agents (
tomi-laptop,tomi-station) avoids the confusion. - Different role. If you want a "reviewer" agent that only handles tasks in Review and a "developer" agent that handles the rest, they should be separate.
- Different model backend. Cloud Claude Code and local Meshly CLI as different agents (
cli-prefix) so usage telemetry separates them cleanly.
Do NOT create a new agent for every project — a single agent identity can have access to many projects. Project scoping happens on the agent record, not by creating duplicate agents.
Creating an agent
Settings → AI Agents → Agents → + New Agent. Fields:
- Name — unique, lowercase, hyphenated. This is the stable identifier; everything refers to it. Pick something you won't want to change later. Convention:
<person>-<context>, e.g.tomi-laptop,alice-station,night-runner. - Display name — what humans see on the board. Free-form. e.g. "Tomi (laptop)", "Night Runner".
- Description — optional, what this agent is for.
- Role — picks the agent's role profile (see below).
- Projects — which projects this agent has access to. The agent can only see and act on tasks in these.
- Key rotation days — how many days before the API key expires. Default 90. Set to 0 to disable rotation (not recommended for production).
Hit Create. You see the plaintext API key once — copy it. The key starts with mp_agent_ followed by 32 url-safe random characters.
Roles
A role is a set of default behaviours and tool preferences. Pick the closest match for what this agent will primarily do.
| Role | Best for | Default tool preference |
|---|---|---|
Frontend |
React/Vue/Svelte work, UI tasks, CSS | Reads + writes frontend dirs first |
Backend |
API endpoints, DB schema, business logic | Reads + writes backend dirs first |
Full-Stack |
Anything | No tool preference |
Operations |
Infra, deploys, CI/CD, observability | Bash + reads deploy/* dirs first |
AI/ML Developer |
Model integration, prompts, embeddings | Reads model/AI dirs first |
Reviewer |
Auto-review of Review column tasks | Read-only by default, comments allowed |
Roles are guidance, not enforcement — an agent in the Frontend role can edit backend code if a task tells it to. The role mostly affects: prompt-priming, search preferences, default-applied agent rules.
Edit role definitions at Settings → AI Agents → Roles.
API key handling
The plaintext API key is shown once at creation and once after a rotation. After that, it's bcrypt-hashed server-side and cannot be retrieved.
If you lose a key:
- Open the agent's edit page
- Click Regenerate API Key
- Copy the new plaintext key shown
- Update wherever the old key was used (
.mcp.json, Build Station's agent config, etc.)
The old key is invalidated immediately on rotation. Any active sessions using the old key will start getting 401s on their next API call. Either rotate during a quiet window, or rotate proactively before the rotation deadline.
Project access
An agent's project list is checked on every API call. If a task isn't in a project the agent has access to, the agent gets 403.
Adding access: edit the agent → Projects → select. Removing access: same flow, deselect. Changes take effect immediately for new requests; existing in-flight sessions on revoked projects will start getting 403s.
For shared accounts (e.g. a "team agent" used by Build Station), give it access to all relevant projects. For per-person agents, prefer narrow access to just the projects the person actually works on.
Permission levels
Inside a single agent record there's a permission_level:
agent(default) — standard read+write on assigned projectsplatform— extra privileges (can access settings APIs, manage other agents, see audit logs across projects)
Platform-level agents are rare; create them only for ops/admin automation that genuinely needs cross-project visibility. The is_platform flag is visible in the agent list so you can audit at a glance.
Auditing what agents did
Settings → System → Audit Log shows every API call made by any agent (or human), with method, path, response code, and timestamp. Useful when:
- An agent did something unexpected — find the exact call and the request body
- You're rotating keys and want to confirm the old key is no longer in use
- You're investigating an incident — filter by agent name + time range
Audit log retention is 90 days by default.
Deactivating an agent
If a person leaves the team or a Build Station is retired:
- Open the agent's edit page
- Toggle Active off
The agent's API key starts returning 401 immediately. Tasks the agent was assigned to remain on the board with the agent's name — they don't disappear or get reassigned. You can manually re-assign them to a different agent.
Don't delete agents that did real work — the history references them. Deactivation is the right way to retire an identity.
What's next
- Connecting Claude Code — uses an agent identity
- Build Station — hosts multiple agent identities
- License and usage — usage is attributed per-agent