Agent definitions
An agent definition is the reusable configuration a coding agent runs with: which agent, what it is told, what files it starts with, what tools it can reach, and which secrets it may use. It is the densest concept in the product and the one most worth learning properly, because it is where you make the agent yours.
If you have not met the three adjacent names yet — coding agent, agent definition, agent profile — start here.
What a definition holds
| Part | What it does |
|---|---|
| The agent | Claude Code or Codex |
| The prompt | The standing instructions the agent starts every session with |
| Files | Content placed into the container — instruction files, configuration, templates |
| MCP configuration | Which MCP servers the agent may use, and how they are configured |
| Secret references | Which secrets this definition is allowed to have injected |
The three scopes
A definition lives at organization, workspace or project scope.
project > workspace > organization
A project definition overrides the workspace and organization definitions it would otherwise inherit. That is how one team keeps a house style while a single project departs from it, with nothing forked and nothing copied. The full rule is on Configuration precedence.
Your organization starts with two organization-scope definitions, Default (Claude Code) and
Default (Codex), which is why your very first launch has something to launch. Neither starts as the
organization's default — the setup wizard flags the one matching the credential you connect.
→ No default coding agent yet
You can change which is the default at any time from a definition's detail page.
Composing one
Work in this order, because each step is easier once the one before it is settled:
- Pick the agent — this constrains everything else, and it constrains who can launch the result (see below).
- Write the prompt. Standing instructions, not a task. "You are working on a Go service; run
make testbefore proposing a change" is a prompt; "fix the login bug" is a message you send in a session. - Add files. Anything the agent should find already in place.
- Wire MCP servers if the agent needs tools beyond its shell.
- Reference the secrets it needs — and no more than it needs.
Consuming a secret
Secret references are keyed on the definition. You attach a reference to a definition; at launch the platform resolves that reference against the launching scope and injects the value.
Two consequences:
- Adding a secret to a project does not expose it to every agent. Some definition has to reference it by name.
- The same definition resolves to different values in different scopes — a reference to
DEPLOY_KEYpicks up the project'sDEPLOY_KEYwhen launched in that project, and the organization's when launched elsewhere. That is the intended use, not a quirk.
Why a definition may show as not launchable for you
Launchability is derived per caller: does this person have a credential for the agent this definition names? Two people legitimately see two different answers on the same definition.
If a definition is greyed out for you and not for a teammate, you are missing a credential for that agent. Either add a personal one or ask an admin for a shared one — it is not a permission problem.
Testing before you depend on it
Launch a sandbox with the definition in a throwaway project before you make it your organization's default. The things that go wrong are mundane and all visible in the first thirty seconds of a session: the prompt says something you did not mean, a file is not where the agent expects it, an MCP server is not reachable from your environment, or a secret reference resolves to nothing.
A definition that fails only at launch time — for example because it names a coding agent nobody has a credential for — stops while the container is starting. → A launch that will not finish