Profiles
A named set of your connections and the tools they may use, chosen for a conversation, a run or a schedule in one step.
Profiles
A profile is your own named set of connections (a mailbox, a calendar account, a Carbon Forge (formerly Nuclear Notes) token, a GitHub token and so on, any number of any kind) with a list of the tools they may use, and optional defaults. You choose a profile for a conversation, and every run started from it, or for a schedule, instead of choosing connections one by one.
A run carries one profile or chosen connections, never both. Choosing both is refused: "Choose one profile, or choose connections without a profile; not both."
A run, a schedule or an API key reaches only the connections its profile names, or, for a run or a schedule, the connections chosen for it one by one. With neither, it reaches none of your connections, whatever you have connected. The Profiles page says so above the list: "A run, a schedule or an API key reaches only the connections a profile names. Without one it reaches none."
What a Profile Holds
| Field | Description |
|---|---|
name | 1 to 64 characters, unique among your profiles. |
bindings | Your own active connections, by id, in order. A connection revoked or deleted later stays listed as removed. |
tools | The tools the profile allows, each an exact name (mail.reply) or a family written <family>.* (carbon-forge.*). Empty: every tool these connections allow. carbon-forge was formerly named nuclear-notes; the former name is still accepted for at least 90 days from 21 October 2026. |
repository | A default repository, one of your git repository bindings. |
notes_workspace | A default Carbon Forge workspace, by id or slug (1 to 128 characters). |
instructions | Your instructions for conversations on this profile, at most 4,000 characters. |
A profile can only narrow what your plan allows. Each entry of tools must match a tool your security context admits for the profile's connections, or it is refused: "A profile can only narrow the tools your plan allows; <pattern> is not one of them."
What a Profile Governs
A profile governs the tools of its connections' families: mail.* for a mailbox, calendar.* for a calendar account, and the provider's own family for any other connection (for example carbon-forge.* or github.*). For those tools:
- Listing. A run or conversation on the profile is offered only the tools the profile allows.
- Calling. Every call of a governed tool is checked against the profile as it stands at that moment, after the security context's own check and before the approval gate. A tool the profile does not allow is refused
TOOL_NOT_IN_PROFILE: "This tool is not in the profile chosen for this conversation." in a conversation, "This tool is not in the profile chosen for this run." in a run; the refusal names the profile's page, and Zaru Web shows a card with a link to it. - Starting. When a run starts, the profile's active connections become the run's chosen connections. A profile that is not yours, or was deleted, refuses the start, and any later governed call: "The profile chosen for this run no longer exists."
A tool the profile allows still meets the approval gate. mail.send, mail.reply, mail.forward, mail.delete, mail.archive, calendar.create, calendar.update, calendar.delete and calendar.respond are marked in the tool catalogue as waiting for your approval, and neither a profile, an agent nor the deployment's configuration clears that mark: each call waits for your answer unless a standing choice answers it. So a profile that allows mail.reply and not mail.send lets a run reply in a thread, each reply waiting for your approval, and refuses a new message at once, before any approval is asked.
Tools of other families, such as fs.*, cmd.run or web.*, are not governed by a profile: the security context alone decides them.
A run's profile is passed on to the agent states of a workflow and to child runs, as its connections are. A run started by another run never reaches past it: a choice of its own naming a connection the other run did not choose is refused "A run started by another run can only use connections that run chose; the connection chosen for '<server>' is not one of them."
Standing Choices
An "Always allow" or "Always deny" choice made on a profile's run applies to that profile only. Zaru Web shows it as "Always allow <tool> · <connection> · <profile name>", and the approval card's "Always allow" says "in this profile" when the call carried one. Deleting a profile revokes the standing choices made in it.
In Zaru Web
- Vault, Profiles.
/vault/profileslists your profiles with their connections and tool count. New profile and each profile's page share one form: a name; your connections grouped by type; the tools those connections allow, by family, with "Needs your approval" beside a tool that waits for your approval and "All tools these connections allow" for an empty list; a repository, a Carbon Forge workspace and instructions. A profile with a removed connection says "A connection in this profile was removed." - In a conversation. The conversation panel above the chat input opens upward over the conversation, at most half the window's height, scrolling when the list is longer. Its Context section lists None, then Profiles (one at a time), then your connections by type; choosing a profile clears chosen connections and the other way round, and the line above the input reads "Profile: <name>" in place of the context. The profile is stored with the conversation, so its later turns, and the runs they start, use it. Zaru is told the profile's name, its Carbon Forge workspace (used when a Carbon Forge call names none) and your instructions for it.
- API keys. Each key's row on Settings → API Keys chooses its profile, None first. See API Keys.
- Schedules. The schedule form saves a profile or chosen connections, never both; a profile's repository and Carbon Forge workspace fill the form, and a Schedule this? card or a run's Schedule this opens it on the conversation's profile. See Schedules.
Over MCP
An MCP client chooses a profile for every request of its connection with the x-zaru-contexts header, holding the reserved key @profile alone:
x-zaru-contexts: {"@profile":"0000daeb-ae45-4d06-9712-9d498a653b24"}Zaru Web prints no profile's id as text. The id is the last part of the address of the profile's own page: open Vault → Profiles, choose the profile by its name, and copy the id from ask.myzaru.com/vault/profiles/<profile id>. Where Zaru Web shows a connection's binding id, for the form that names connections, is not documented.
Without @profile, the same header names connections instead: for each tool server, a binding id, a list of binding ids, or null for none. @profile beside any other key, a list under it, or any other key beginning with @ is answered 400 with "Choose one profile, or choose connections without a profile; not both."; any other shape with "x-zaru-contexts must be a JSON object naming one profile as @profile, or, for each server, a binding id, a list of binding ids, or null".
With a profile chosen, every call the server forwards carries it, the tools offered are the profile's, and a tool that starts a run starts it on the profile. zaru.init and zaru.mode teach the model the profile's name, its Carbon Forge workspace and its instructions.
A call of a tool that starts a run (aegis.task.execute, aegis.agent.generate, aegis.execute.intent, aegis.workflow.generate, aegis.workflow.run) may also carry profile, one profile id, which the client writes from the person's choice; a call that carries none takes the request's profile, and a call made inside a run takes the run's.
REST Routes
| Route | Who | Scope |
|---|---|---|
POST /v1/profiles | a person | profile:write |
GET /v1/profiles | a person (their own, by name) | profile:read |
GET /v1/profiles/{id} | the owner | profile:read |
PATCH /v1/profiles/{id} | the owner | profile:write |
DELETE /v1/profiles/{id} | the owner | profile:write |
POST /v1/profiles/available-tools | a person | profile:read |
Another person's profile is answered 404, exactly as one that does not exist. An operator reads none, and a service account is refused every route: "Profiles belong to the person who made them; only that person can read or change them."
A profile answers as:
{
"profile": {
"id": "0000daeb-ae45-4d06-9712-9d498a653b24",
"name": "Fundraising",
"bindings": [
{ "binding_id": "44217ea5-…", "state": "active", "label": "ann@example.com" }
],
"tools": ["carbon-forge.*", "mail.draft", "mail.reply", "mail.list", "mail.read"],
"repository": null,
"notes_workspace": "fundraising",
"instructions": null,
"created_at": "2026-10-09T16:21:42Z",
"updated_at": "2026-10-09T16:21:42Z"
}
}The list answers {count, profiles}. POST /v1/profiles/available-tools with {"bindings": [<ids>]} answers {count, tools}, each tool with its name, description, family and gated (whether a call waits for approval); a remote tool server's family answers one <family>.* entry. DELETE answers 204.
"Profile" here is this object. The deployment's named policies are security contexts, and the command line's login profiles are another thing again; neither is a profile.
See Also
The Vault
Store and manage credentials that your agents use at runtime. Agents never see credential values directly — the platform injects them securely at execution time.
Calendar
Connect a calendar account, by Google sign-in or a CalDAV server's address, and let Zaru read your events and, with your approval, change them.