Create and manage an agent profile

An agent profile is the saved who of a run: which agent and model it uses, which MCP tool tiers it may reach, which execution mode it runs in, which memories it may draw on, and which pre- and post-flight checks it must pass. Pinning a profile to a task, an automation or a workflow node says “work like this” once instead of at every launch.

Two neighbouring tabs complete the picture. MCPs is what an agent may reach — the tool servers this workspace makes available. Skills is what it knows how to do — reusable Markdown instruction sets injected into a run. All three tabs live under Settings → Agents.

This page is where you set it, not what it means

For the tier model itself — what the baseline, read, ops, scaffold and deploy tiers actually grant, and the rate limits attached to each — read Entitlements and the MCP tool tiers. This page only shows where you set it and who may.

Create a profile

Open Settings → Agents → Agent Profiles. The tab is a searchable, sortable list of every profile in the workspace — name, default agent, execution mode, version and status, with a Default badge on the workspace-default profile — sitting above a detail form bound to whichever row is selected.

1. Click Create profile in the list toolbar. The detail form below clears and stops pointing at an existing profile.

2. Give the profile its identity: Name, Slug and Color — the colour the profile is drawn in across the product. Leave the slug empty and one is derived from the name; it is the handle you pin the profile by from chat and the web terminal (run <project> <agent> --profile <slug>).

3. Choose who runs the work:

   • Default agent — Claude Code, Codex, Gemini, Qwen Code or OpenRouter.
   • Model policy — Auto (SupaCloud may choose the model from selection signals when the task sets none), Manual (the task decides; the profile only sets agent, persona and capabilities) or Fixed (this profile always runs the one model you name).
   • Fixed model — enabled only under the Fixed policy. The options come from the maintained model catalog, narrowed to the chosen agent’s provider.
   • Execution mode — Normal (standard single-agent execution) or Workflow (Claude Code’s multi-agent workflow orchestration). Workflow is a Claude Code capability, so the picker is disabled for the other agents.

4. Write the Description and the Persona prompt — the standing instruction every run under this profile is given. The counter beside the field caps the persona at 200 tokens, and saving is blocked above that.

5. Fill the Capability allowlist — a comma-separated list of MCP tool names or tiers (for example supacloud.read.*, supacloud.ops.*, an individual tool name, or supacloud.full). An empty allowlist grants nothing of its own: the session falls through to the workspace default, and then to the built-in read-only floor.

6. Set the Memory policy — the scopes and kinds injected as auto context, the scopes and kinds the agent may read over MCP, whether personal memories are allowed, and the auto limit.

7. Add Tags if you sort profiles by them, leave Enabled on, and click Create profile. The Effective system prompt preview below the form renders the persona prompt as the agent will receive it.

A disabled profile fails a pinned task closed

Enabled is not cosmetic. A task pinned to a profile that has been disabled (or deleted, or belongs to another workspace) does not quietly fall back to a weaker tier — its MCP session is refused outright with “Pinned agent profile is unavailable or disabled”. That is deliberate: revoking a profile must not widen an agent’s surface through a fallback.

Tune the profile in the advanced editor

Select a profile and click Advanced editor to open it at its own page. The editor has four views.

Form

Everything the list form has, plus the fields that live only here:

• Avatar style and Avatar value — colour, initial, icon or image.
• Default reasoning effort — Inherit (the runner default) or one of the five effort levels, applied to every task run under this profile.
• Autonomy — the profile-scope slider. The profile is the most specific scope, so its level wins over the project and the workspace; see Set the autonomy level.
• PR template — the Markdown template applied to pull requests this profile opens.
• Visual verify — the screenshot-and-judge post-flight gate; see Configure visual-verify gates.
• Require review — tasks from this profile must be reviewed before they count as done.
• Allow memory.create (MCP) — lets the agent write memories directly, bypassing review. Off by default.
• Interactive tool approvals — pauses the agent mid-run for a human verdict on gated tools. Off by default, and combined with the run’s autonomy level rather than overriding it; the pauses land in the inbox.

Raw

A JSON editor over exactly three of the profile’s fields — pre_flight_checks, post_flight_checks and retry_policy. These are forward-compatible arrays and bags, so Raw is how you author a check kind (or a retry setting) that has no dedicated control in the Form yet. Save stays disabled while the JSON is invalid or is not an object, so a typo cannot overwrite a working runbook.

Raw is not where you promote a profile

is_workspace_default is deliberately absent from the Raw surface. Only one profile per workspace may hold it, so promotion is its own action — see Set the workspace default below.

Versions

The profile’s history: an immutable snapshot is written server-side on every runbook change. The list is newest-first, and View snapshot expands a row to the full JSON of the profile as it stood at that version. Nothing on this view mutates the profile.

Governor

The self-learning governor’s surface for this profile: the Drift status banner (shown when a drift signal has frozen the profile’s learned model selection), the open Version proposals the governor raised in response, and the Governor audit card with the latest golden-set pass rate, judge agreement and mean cost. Approving a proposal materializes it as a new version and lifts the freeze. The proposals and drift status are workspace owner reads; the audit card is a workspace admin read. For the mechanism, see The self-learning Governor.

You can decide profile proposals without opening the editor

The same proposals appear in Inbox → Decisions with a Profile proposal badge, alongside every other decision waiting on you — see Work the inbox.

Set the workspace default

This is the load-bearing, non-obvious part of the profile surface.

A task that carries no agent profile — a run launched without one, or a workflow agent step whose node pins none — does not get a generous surface. Its MCP session resolves in this order:

1. the task’s own profile allowlist, when it has a profile and that allowlist is non-empty;
2. otherwise the workspace-default profile’s allowlist, when one is set and non-empty;
3. otherwise the built-in floor: supacloud.* plus supacloud.read.* — the unconditional baseline plus read-only tools. Ops, scaffold and deploy stay fail-closed.

So step 3 is what a profile-less task gets by default, and promoting a workspace-default profile is the only thing that changes it.

1. Open Settings → Agents → Agent Profiles and select the profile in the list.

2. Scroll to the bottom of the detail form and click Set as workspace default. The button appears only for a saved profile, never while you are composing a new one.

3. The line beside it becomes This is the workspace-default profile. and the Default badge moves to that row in the list. A workspace holds at most one default, so promoting a profile clears the previous one in the same operation.

The default is not filtered down to read-only

The workspace default’s allowlist is used verbatim. If you promote a profile whose allowlist names supacloud.ops.*, supacloud.deploy.* or supacloud.full, every profile-less task in the workspace inherits that surface — the “read-only fallback” guarantee covers only the built-in floor in step 3, not the profile you promote. Deploy-tier tools still need their own server-side confirmation secret, and every tier keeps its rate limits.

Curate the MCPs a profile may reach

Settings → Agents → MCPs lists the workspace’s capabilities of kind mcp — the tool servers an agent run can be given. Standard presets ship active; the tab lets you disable or extend them per workspace. They are grouped as Code & Repositories, Observability, Browser & UI, Documentation and Custom MCPs, each group showing an n/m active count.

1. Use Enable / Disable on a single capability, or Enable group / Disable group on the group header to move all of them at once.

2. A capability whose configuration needs a secret is marked Setup required and opens a Configure dialog instead of toggling straight on. Pick an existing workspace secret or paste a new value, then Save & enable — the value is stored as a workspace secret and the capability’s config keeps only a reference to it, never the value.

3. To add your own server, fill the Custom preset form at the bottom — internal name, label, an optional description and a JSON Configuration (JSON) body — then Save preset. Reference secrets in it rather than inlining them, for example {"env":{"TOKEN":"${{ secrets.TOKEN }}"}}.

Enabling a capability makes it available to the workspace; which of its tools a given run may actually call is still decided by that run’s profile allowlist and the tier model.

Author the skills a profile draws on

A skill is an agent_capabilities row of kind skill — the same table as an MCP, a different kind — and its body is a Markdown instruction set you edit in place. There is no file tree and no repository behind it: one skill is one document, plus the list of agents it targets.

1. Open Settings → Agents → Skills. The tab is a card gallery with a search box and a Source facet (Built-in / Custom); a built-in skill carries a Seed badge.

2. Click New skill, give it an internal name, a label and an optional description, and save. It starts with empty instructions.

3. Open the card (Edit skill) to write it. In the editor you set:

   • Label and Description — read-only for a built-in skill, which the catalog manages.
   • Agent targets — the agents the skill applies to, as toggles. Select none and it applies to every agent.
   • Instructions (Markdown) — the skill body, in a Markdown editor.
   • Available to agents — the on/off switch for the skill.

4. Save skill. A custom skill can also be deleted from here; a built-in one can only be disabled.

Induced skills arrive as a proposal, not as a skill

SupaCloud can mine a successful run’s own reflection for a generalizable skill. It never publishes one silently: it raises a draft proposal, and only an approval materializes it as a skill row that runs can read. Decide those proposals in Inbox → Decisions, on the rows badged Skill proposal — see Work the inbox. Deciding requires workspace admin; a member sees the row without buttons.

Pre- and post-flight checks

The two check arrays on a profile bracket a run, and both default to empty — an existing profile is unaffected until you opt in. An unrecognised check kind is kept and ignored rather than failing the run, which is what makes the Raw tab safe to author into.

• Pre-flight runs before the task’s container is prepared. The typed kind today is the readiness guard (readiness_guard): it blocks launch when the linked backlog item was classified needs info. A task with no backlog item counts as ready, so the guard only bites on dispatched backlog work.
• Post-flight runs at the task’s terminal event. The gate summary (gate_summary) records that the deterministic gates were expected, so the post-flight surface is auditable. The visual-verify gate also rides this array, as one forward-compatible visual_verify entry, and is enforced by the backlog capture-and-judge pipeline rather than by the post-flight hook — configure it from the Form tab, documented in Configure visual-verify gates.

Every evaluated check writes an audit event, pass or block.

Who may do what

All three tabs are visible to every workspace member — the server, not the navigation, is the authority — and the MCPs and Skills tabs say so with a Workspace admin badge in their header.

Action	Role required
Read profiles, MCPs and skills	Any workspace member
Create or update a profile	Workspace owner or admin
Promote the workspace-default profile	Workspace owner or admin
Enable, configure, create or delete an MCP capability	Workspace owner or admin
Create, edit or delete a skill	Workspace owner or admin
Approve or reject an induced skill proposal	Workspace owner or admin
Read the Governor drift status and version proposals, and decide one	Workspace owner
Read the Governor audit card	Workspace owner or admin

A member who edits a form and saves gets a permission error from the server rather than a silent no-op, so nothing you see on these tabs is a promise that you may write it.

See also

• Entitlements and the MCP tool tiers
• Configure visual-verify gates
• Set the autonomy level
• Work the inbox
• The self-learning Governor