Coding agents, agent definitions and agent profiles
Three names, three different things. Sorting them out once saves a lot of confusion later.
| Name | What it is | What you do with it |
|---|---|---|
| Coding agent | The program that writes code — Claude Code or Codex — running inside your container | You talk to it |
| Agent definition | A reusable configuration: which agent, its prompt, its files, its tools, which secrets it may use | You edit it, and you launch it |
| Agent profile | A stored preset that pre-fills choices | You pick it |
The short version: you edit a definition, you launch a definition, and what you end up talking to is a coding agent.
The coding agent
Claude Code or Codex, running as a process inside your container with your repository checked out and a shell available. It reads and writes files, runs commands, and runs on your model account via a coding-agent credential.
It is not a hosted service we run on your behalf. It is a program in your container, which is why it can run your test suite and why its network access is your container's network access.
Agent definitions
A definition answers: which agent, told what, with what tools, allowed which secrets. It is the unit you author and reuse.
A definition exists at one of three scopes — organization, workspace or project — and a project definition overrides a workspace one, which overrides an organization one. That is how a team keeps one house style and one project departs from it without forking anything. See Configuration precedence.
Your organization starts with two definitions — Default (Claude Code) and Default (Codex) —
and neither is set as the organization's default. That is deliberate: at
registration nobody has configured a credential, so choosing a coding agent would be a guess.
Connecting a credential in the setup wizard flags the matching definition automatically. Until a default exists, a launch that does not name a definition is refused rather than falling back to a guess — which is the right failure, because the alternative is an organization silently running the wrong coding agent. → No default coding agent yet
Authoring agent definitions covers composing the prompt, files and MCP configuration, wiring secrets, and testing a definition before you depend on it.
Why a definition can be unlaunchable for you
A definition may show as not launchable even though it is perfectly valid, because launchability is computed per caller. It asks: does this specific person, in this specific workspace, have a credential for the agent this definition names?
So two people legitimately see two different answers on the same definition. If a teammate can launch it and you cannot, you are missing a credential for that agent — not permission. The fix is usually adding a personal credential for the right agent, or asking an admin for a shared one.
Agent profiles
A profile is a stored preset — a saved set of choices to pre-fill a launch. It configures nothing on its own and overrides nothing; it saves you from re-picking. If you are trying to change what an agent does, you want a definition, not a profile.