Aegis Orchestrator
Zaru

MCP Tools

The tools Zaru exposes to MCP clients, organized by conversation mode — what each tool does, when it is available, and how to call it.

Zaru exposes the AEGIS platform to MCP clients through a set of tools organized by conversation mode. The mode you select at the start of a conversation determines which tools are active. This page covers each mode's tool set with purpose, key parameters, and example calls.

For complete input/output schemas, see the MCP Tool Reference. For client connection instructions, see Connect Zaru to Any MCP Client.


How Modes Control Tool Access

Every Zaru conversation runs in one of five modes. Modes filter the tool surface exposed to the AI assistant — the underlying platform tools do not change, but the assistant can only call what the mode makes available.

ModeTools availablePurpose
chatzaru.* onlyConversation and planning; no platform execution
agenticzaru.* + agent/task toolsDiscover and run existing agents
executezaru.* + execute pipeline toolsOne-shot code execution from natural language
architectzaru.* + workflow/agent design toolsDesign and deploy agents and workflows
operatorAll toolsFull platform access, no filtering; only under an operator escalation

To initialize in a specific mode:

zaru init agentic

To switch modes mid-session, tell the assistant to switch — it calls zaru.mode and the tool set updates immediately.

Outside of Zaru — in agent inner loops and via direct API calls — tools are not mode-filtered. Mode filtering is a Zaru-client concern. Inside a running agent container, every built-in tool is available subject to the agent's security context and spec.tools allowlist.


Client Capabilities and Mode Gating

Some Zaru affordances are surfaced via client capabilities declared at session start. The Zaru web client declares live, vibecode, and chat-uploads. External MCP clients do not declare any of these.

The chat-uploads capability gates the chat input's file-upload UI (paperclip icon, drag-and-drop, paste). It is bound to agentic and workflow modes only — in those modes the upload affordance appears, the system prompt teaches the model how attachments flow through dispatches, and tool calls to aegis.task.execute, aegis.agent.generate, and aegis.execute.intent may carry an attachments array.

Other modes (chat, execute, live, vibecode, operator) do not surface the upload affordance, even when the capability is declared. External clients that do not declare chat-uploads see no attachment guidance and the platform rejects out-of-band attachment payloads as a defense-in-depth check.

See File Uploads in Chat for the user-facing flow.


Connections and Profiles

What a key reaches. A client connected with a person's aegis_ API key reaches only the connections named by the key's profile, chosen for the key on the API Keys page, or by the request's own x-zaru-contexts header (below). It is listed, and may call, the tools of those connections' families: the mail tools for a mailbox, the calendar tools for a calendar, and a remote server's tools for a connection to it. The remote servers a person can connect today are GitHub and Carbon Forge (formerly Nuclear Notes). Custom SEAL gateways, which will let a person put a server of their own behind the same endpoint, are planned and not available yet. The tools of no connection family (aegis.* and web.*) and the server's own tools are always listed. AEGIS gives the listing of the connected remote servers' tools five seconds: when it takes longer or fails, the tool list still answers without the tools that listing would have added, and they are listed again at the next listing that answers in time.

A key with no profile, on a request that chooses nothing, is listed no connection family's tools, whatever the person has connected. A call of such a tool on it, from a stale list or by name, is refused CREDENTIAL_BINDING_REQUIRED before anything runs: "This key reaches none of your connections. Choose a profile for it on the API keys page in Zaru Web, or name one in the request.", with error.needs {"family": "profile", "page": "/vault/profiles"}; zaru.connection.needed answers such a key the same sentence, and the companion is taught: "The API key this conversation comes through reaches none of the person's connections until a profile is chosen for it on the API keys page in Zaru Web; when a message needs one, tell the person that in one sentence and end your turn." Whether a request is a key's is read from the credential it presents; x-zaru-turn changes nothing.

A call for a family the person has not connected at all is refused CREDENTIAL_BINDING_REQUIRED before anything runs: "You have not connected <a mailbox | a calendar | GitHub | Carbon Forge | <server>> to Zaru. Connect it on the Connections page in Zaru Web (ask.myzaru.com/vault/connections), then try again."

Which connection answers. A mail or calendar call with no mailbox or account uses, of the mailboxes or calendar accounts the call reaches, the only one, else the newest. The answer names it in mailbox_name or account_name.

The person's own session. A call made with the person's own Zaru Web sign-in, not a key, that chose connections for the conversation but none of a family the person has connected is refused for that family: "Your <mailbox | calendar | GitHub | Carbon Forge | <server>> is connected but not chosen for this conversation.", with error.needs naming the Connections page. Such a call that chose nothing at all uses the person's own connection, as above.

Changes wait for the person. Every tool that asks for approval waits at the person's approval gate, as a call from the chat does, and their standing choices apply as in the chat. A pending call answers {"status": "approval_pending", "approval_id", "summary", "message"}, whose message is "This waits for your answer in Zaru Web, under Approvals."; the request appears on Zaru Web's Approvals page, and aegis.approval.status reads the answer.

Which calls wait. A call waits when the tool catalogue marks its tool or the deployment's configuration marks it; any mark gates, and none clears another. On myzaru.com these wait by default:

  • Marked in the tool catalogue: mail.send, mail.reply, mail.forward, mail.delete, mail.archive, calendar.create, calendar.update, calendar.delete and calendar.respond. The catalogue also marks the landing steps aegis.git.land, aegis.tree.land and aegis.archive.push, which are listed to no agent: only a workflow's own landing step calls them.
  • Marked by the deployment's configuration: the GitHub tools github.merge_pull_request, github.push_files, github.create_or_update_file and github.delete_file; aegis.git.push; and aegis.system.info.

No Carbon Forge tool waits: neither the catalogue nor the configuration marks one, so a Carbon Forge call the key's profile admits runs at once. The other GitHub tools (issues, comments, reviews and creating a pull request) do not wait either, nor do the reading tools, mail.draft and the web.* tools. A standing choice ("Always allow" or "Always deny") answers a marked call without asking.

The approval card for a call that came over MCP is the card a chat call gets, on Zaru Web's Approvals page: "Waiting for your approval", then "Tool: " and the tool's name; opened, the gate's summary and, for a call that writes files, the changes it would make; and the answers Approve, Always allow followed by the tool's name, and Decline. For a github.* tool, Always allow adds "(every repository your token reaches)"; for a call that carried a profile, it ends "in this profile". Under the card, Open the conversation links the conversation the call was made in when the request named one: an MCP client names it by sending the header x-zaru-conversation with one conversation id (a UUID), and a header of any other shape is answered 400 "x-zaru-conversation must be one conversation id (a UUID)". Nothing on the card says that the call came over MCP or which API key made it. A request nobody answers expires after 72 hours, and nothing runs.

What an approval binds. When a call waits, Zaru stores it as it arrived: the tool and its exact arguments. Your answer carries only Approve, Always allow or Decline; on a yes the orchestrator runs the stored call itself, with those arguments, and the client does not send it again, so nothing a client sends after you were asked changes the call that runs. A changed call is a new call and waits on a card of its own, unless an Always allow you gave answers it: a standing choice matches the tool, the connection it acts through and, for a call that carried one, the profile, not the arguments. Each file a mail attaches is checked at the run against the file the card named, and a changed file stops the send: "A file to attach changed after it was approved; nothing was sent."; mail.forward sends exactly the messages its card listed. A calendar change, deletion or answer reads the event again at the run and acts on it as it then is, and mail.delete and mail.archive move the thread's inbox messages as they are at the run, with any that arrived after the card. The card's summary carries at most 2,000 characters of each argument it lists (of the whole arguments, for a tool that lists none) and does not mark where it stops; the run uses the whole call.

A connection may send the x-zaru-contexts header to choose, for every request, which of the person's connections the tools use: for each tool server a binding id, a list of binding ids, or null for none; or, alone, {"@profile": "<profile id>"} to choose one of the person's profiles. With a profile, the tools offered are the profile's, every forwarded call carries it, and zaru.init and zaru.mode teach the model the profile's name, its Carbon Forge workspace and its instructions. A header of any other shape is answered 400. On a key, a request's @profile, or any binding the header chooses, takes the place of the key's own profile for that request.


Waiting on Long Executions

An MCP client gives up on a tool call after about a minute, so on Zaru's MCP server (https://mcp.myzaru.com/mcp/v1) one call to a wait tool (aegis.agent.wait, aegis.task.wait, aegis.execute.wait, aegis.workflow.wait) waits at most 45 seconds. A timeout_seconds that is a whole number from 0 to 45 is used as given; a larger value, a fractional value or none waits 45 seconds. Each wait tool's description says so.

When the execution finishes within the wait, the result is the execution's final status and output. When it is still running, the call returns an ordinary result rather than an error:

{
  "tool": "aegis.task.wait",
  "execution_id": "e1f2a3b4-...",
  "status": "running",
  "iteration_count": 2,
  "still_running": true,
  "timed_out": true,
  "waited_seconds": 45,
  "message": "Execution e1f2a3b4-... is still running after 45s, iteration count 2. The run keeps going on its own; read it again only when the person asks."
}

A workflow's result carries current_state in place of iteration_count. The execution goes on whether or not anything waits on it, and a later call of the same wait tool reads it again. In Zaru's modes the companion reads a run at most once in a turn and never in a loop: when the answer reads running, it says so in one sentence with the execution_id and ends its turn, and it reads the run again only when you ask.


When AEGIS Refuses a Tool Call

Zaru's MCP server forwards the aegis.* tools to AEGIS. When AEGIS refuses such a call or cannot complete it, the client gets an ordinary tool result with isError: true, not a JSON-RPC error. The result has one text item holding a JSON object:

{
  "error": {
    "code": "INVALID_ARGUMENTS",
    "message": "Invalid tool arguments: required field 'execution_id' is missing or null for tool 'aegis.task.status'"
  },
  "request_id": "3f9c2a71-5b8e-4d0a-9c1e-7a2b6d4e8f10"
}
FieldMeaning
error.codeAEGIS's code for the refusal, from Refusals and Errors, or invoke_failed (below).
error.messageFor a refusal of your call, AEGIS's own message: what was refused and why. For INTERNAL_ERROR, UPSTREAM_UNAVAILABLE and SERVICE_UNAVAILABLE, the fixed sentence of that table, never the failure's detail.
error.needsPresent when the refusal is for a connection or a profile the person lacks: {"family", "page"}, the family (mailbox, calendar, github, carbon-forge or profile) and the Zaru Web page that resolves it, /vault/connections for a connection, /vault/profiles/<profile id> for a profile that does not admit the tool, and /vault/profiles for a profile that no longer exists or for a run, a schedule or a key whose profile names no connection of the family (Zaru Web's card then says "This run has no profile that names your <family>." with Open Profiles). Any other needs is dropped.
request_idAEGIS's id for the refused call. Quote it when you report the failure: it lets an operator find what happened.
retry_after_secondsPresent when AEGIS said how long to wait, on RATE_LIMIT_EXCEEDED and on UPSTREAM_UNAVAILABLE: the seconds to wait before calling again.

The server does not repeat a refused call, apart from the session renewal below. A policy refusal is deterministic: the same call gets the same answer, so change the call instead of repeating it.

The session is renewed by the server. The server keeps a SEAL session with AEGIS for each user. When AEGIS answers 401, meaning the session or the envelope is no longer valid, the server attests again and sends the call once more. If AEGIS answers the second call 401 as well, the result carries AEGIS's code with the message "The session with AEGIS could not be renewed. Try the call again."

invoke_failed. An answer the server cannot read as one of AEGIS's refusals comes back with the code invoke_failed and the message AEGIS invoke failed: <HTTP status>. A session the server could not start comes back as invoke_failed with AEGIS attestation failed: <HTTP status>.

Not a tool result. A call AEGIS does not answer at all, because it timed out or AEGIS could not be reached, still fails as a JSON-RPC error. When the server cannot read AEGIS's tool list, tools/list fails as a JSON-RPC error with the message AEGIS tool discovery failed: <HTTP status>.

The errors of the tools the server handles itself (zaru.chat, zaru.operator.escalate, zaru.operator.release) are listed with each tool below.


Zaru Client Tools — All Modes

These tools are available in every mode, including chat. They are handled by the Zaru MCP server and never forwarded to the AEGIS orchestrator.

zaru.init

Bootstraps the session. Returns the current mode, system prompt, available tools, and server version. Call this at the start of any MCP session.

ParameterRequiredDefaultDescription
modeNochatMode to activate: chat, agentic, execute, architect, or operator while the connection holds an operator escalation
// zaru.init
{ "mode": "agentic" }

zaru.mode

Switches the active conversation mode. In the Zaru web client, this renders an inline confirmation card — the user accepts or declines. In headless MCP clients the switch applies immediately.

ParameterRequiredDefaultDescription
target_modeYes—Mode to switch to
reasonYes—One sentence explaining why the switch is needed
// zaru.mode
{
  "target_mode": "architect",
  "reason": "Designing a new multi-step workflow requires architect tools."
}

zaru.docs

Searches AEGIS and Zaru documentation at docs.100monkeys.ai. Results are cached for 5 minutes per query.

ParameterRequiredDefaultDescription
queryYes—What you want to look up
// zaru.docs
{ "query": "how to configure a persistent volume for execute mode" }

zaru.connection.needed

Says what the person must connect or choose before a family of tools can be used, when no tool of that family is listed. It reads the person's listing, the request's x-zaru-contexts choice and its profile, and changes nothing.

ParameterRequiredDefaultDescription
familyYes—mailbox, calendar, github or carbon-forge
// zaru.connection.needed
{ "family": "mailbox" }

Returns { needs, sentence }:

Stateneedssentence
Not connected{"family": "mailbox", "page": "/vault/connections"}"A mailbox is not connected to Zaru. Connect it on the Connections page in Zaru Web."
Connected, not chosen (a Zaru Web turn){"family": "mailbox", "page": "/vault/connections"}"Your mailbox is connected but not chosen for this conversation. Choose it under Context above the chat input."
Not in the chosen profile{"family": "profile", "page": "/vault/profiles/<profile id>"}"The profile chosen for this conversation does not allow this. Change it on the profile's page in Zaru Web."
Nothing missingnull"Your mailbox is connected and chosen for this conversation.", or, outside a Zaru Web turn, "Your mailbox is connected to Zaru."

A family that names no connection is refused "family must name one connection: mailbox, calendar, github, nuclear-notes, carbon-forge, or another connection's own name." carbon-forge was formerly named nuclear-notes; the former name is still accepted for at least 90 days from 21 October 2026. Every mode's instructions tell the companion to call it when a message needs a connection none of whose tools is listed, to tell the person in one sentence what to connect or choose and that the card above takes them there, and to end its turn; after a call refused for something not connected, not chosen or not in the chosen profile, to say what is missing in one sentence and end its turn; and never to say a connection is or is not made unless a tool's answer says so.

zaru.memory.get

Reads the caller's persistent memory — a per-user markdown blob shared across every MCP client connected as that user (Zaru Web, Claude Desktop, Windsurf, etc.). The current memory is auto-injected into the system prompt at session start, so calling this mid-conversation is mostly used to obtain the current version before a zaru.memory.set, or to re-read after a conflict.

No parameters — accepts an empty object {}.

// zaru.memory.get
{}
// response
{
  "content": "# User memory\n\n- Prefers concise answers...",
  "version": 7,
  "updated_at": "2026-04-28T14:32:11Z"
}

When no memory has been written yet, returns { "content": "", "version": 0, ... }.

zaru.memory.set

Persists a new memory state. Pass the full new markdown blob — not a diff or patch — together with the version returned by the most recent zaru.memory.get. The server increments the version on success.

Use this to record user preferences, work-style cues, recurring projects, frustrations, or anything worth carrying into future conversations. Always call zaru.memory.get first to obtain the current version. Keep memory concise and signal-rich — it is not a transcript log.

ParameterRequiredDescription
contentYesFull new memory markdown blob (not a diff)
versionYesVersion returned by the previous zaru.memory.get call
// zaru.memory.set
{
  "content": "# User memory\n\n- Prefers concise answers...\n- New project: zaru-edge",
  "version": 7
}

If version does not match the server's current version, the call returns a structured conflict error containing the server's current { content, version, updated_at }. Merge the intended changes into that content and retry with the new version.

zaru.schedule

Proposes a schedule to the person: one of their agents or workflows run later, once or again and again. It creates nothing. Zaru Web shows the proposal as a Schedule this? card that names what it runs and when, and the turn ends there; Schedule opens the schedule form filled in from the proposal, Not now closes it. See Schedules.

ParameterRequiredDescription
target_kindYesagent or workflow
targetYesThe name or id of one of the person's agents or workflows. It must already exist.
intentYesWhat each run is for, in the person's words
inputYesAn object of the target's input values, or one string, carried as {"prompt": <the string>}
atOne ofFor one run: an RFC 3339 time at least one minute from now and at most a year ahead
recurrenceOne ofFor a repeating run: cron (five fields, required), timezone (default UTC) and jitter_seconds (0 to 3600, default 0); at most once every 5 minutes
reasonYesOne plain sentence, shown to the person, saying what the schedule will do for them

Give exactly one of at or recurrence. After the shape is checked, the server reads the person's own agent or workflow list and accepts a target equal to an entry's name or id. Otherwise the proposal is refused, with no card:

  • an empty target: "'target' must name one of your agents or workflows. Find or make the one that does this, run it once, then propose the schedule naming it."
  • no such agent or workflow: "You have no agent named '<target>'. Find or make the one that does this, run it once, then propose the schedule naming it." (or "workflow")
  • the list could not be read: "Your agents and workflows could not be read just now, so nothing was proposed."

In chat mode the companion proposes a schedule only for an agent or workflow the conversation has already named or run; otherwise it offers agentic mode with zaru.mode, where the one that does it is found or made and run once, and the proposal follows that run. In agentic and workflow modes it names as the target the agent or workflow it ran. In no mode does it make a schedule itself.

// zaru.schedule
{
  "target_kind": "agent",
  "target": "mail-reply-watcher-agent",
  "intent": "Watch for a reply from Cloudflare about the startup program and tell me when it comes",
  "input": "Look for a reply from Cloudflare about the startup program",
  "recurrence": { "cron": "0 */6 * * *", "timezone": "America/Los_Angeles", "jitter_seconds": 300 },
  "reason": "Checks your inbox every 6 hours and tells you the moment a reply arrives."
}

zaru.conversations.list, zaru.conversations.read, zaru.conversations.search

Read the person's own Zaru conversations: the ones held on the Zaru Web chat page and the ones held through zaru.chat. They read nothing of anyone else's, whatever tenant was active, and wait for no approval.

ToolParametersReturns
zaru.conversations.listlimit (1 to 50, default 20){ conversations: [{ id, title, mode, updated_at, message_count, archived, current }], more }, newest first by the last message
zaru.conversations.readconversation_id (required), cursor, page_size (1 to 100, default 50){ conversation: { id, title, mode, updated_at }, messages, next_cursor }, oldest first
zaru.conversations.searchquery (3 to 200 characters, required), limit (1 to 50, default 20){ hits: [{ conversation_id, title, message_id, role, created_at, snippet, current }], more }, newest first

A message read returns is { id, role, text, created_at } for something the person or Zaru said, with channel: "api" on a message the person sent through another app and truncated: true on a text cut at 4,000 characters; or { id, role: "tool_call", tool, outcome, created_at } for a tool call, outcome being ok, error or aborted. Tool arguments and results are not returned. Pass next_cursor as cursor to read the next page; it is null at the end. search matches the whole query literally, without regard to case, in titles and in what the person and Zaru said; message_id is null for a match in a title, and snippet is up to 200 characters around the match.

current marks the conversation the call is made in. Reading it is refused with current_conversation: "That is the conversation we are in; it is already in front of you." A refusal is a tool error whose text is { "error": <code>, "message": <sentence> }, the code one of unauthorized, conversation_not_found, current_conversation, invalid_request or unavailable; another person's conversation is conversation_not_found, exactly as one that does not exist.

// zaru.conversations.search
{ "query": "Google credits", "limit": 5 }

Talking to Zaru from Another Client

zaru.chat

Runs one turn of the Zaru companion on Zaru's own model, in one of your stored Zaru Web conversations, and returns its answer. The turn is the one the chat page at ask.myzaru.com runs, with the companion's prompt, your memory and the tools of the mode, and the conversation is stored with your others: it is listed on the page and can be continued there or through the tool.

Zaru's MCP server lists zaru.chat to every client that connects to it, and handles it itself, never forwarding it to the AEGIS orchestrator. It is not one of the companion's own tools: no mode offers it inside a Zaru turn, and a call made from inside a turn is refused with mode_not_available, so a turn never starts another turn.

The turn runs as the user the MCP connection is authenticated as, by an aegis_ API key or a Zaru sign-in.

ParameterRequiredDefaultDescription
messageYes—Your message for this turn, 1 to 32,768 characters
conversation_idNoa new conversationUUID of a conversation of yours to continue, begun on the page or here
modeNothe conversation's stored mode, or chat for a new onechat, agentic, workflow or execute, or operator while the connection's key holds an operator escalation; a different mode changes the conversation's mode
// zaru.chat
{
  "message": "Summarise what we decided about the release yesterday.",
  "conversation_id": "<conversation-uuid>"
}

The result is a JSON object, returned as text and as structured content:

FieldDescription
conversation_idThe conversation the turn ran in; for a new conversation, its new id
statuscomplete, or incomplete when the turn reached its time limit
answerThe companion's answer
tool_callsEach tool call of the turn as { name, arguments, outcome, result, result_truncated }; outcome is ok or error, and result is cut to 8,192 characters, with result_truncated saying whether it was
model, modeThe model and the mode the turn ran on
mode_switch_requestedPresent when the companion asked to switch modes, as { mode, reason }; the switch is not applied
usagePresent when the model reported it: { prompt_tokens, completion_tokens, total_tokens }
goalPresent when the turn holds a goal: { goal_id, statement, state, rounds, verdicts }, each verdict { round, score, confidence, outcome, reasoning } with round the round it judged, counted from 0. A goal handed on to be judged after the call reads state open

Limits. One call runs one turn of at most five model calls. No model call starts later than 40 seconds after the request arrives, and the turn ends at 50 seconds, so a call answers within the minute an MCP client waits. A turn that reaches the limit ends incomplete with what it did so far stored. In agentic mode a turn that starts creating or running an agent sets a goal (Goals in Agentic Mode): Zaru judges it after the call has answered and continues by itself, without your next message, until it is met, cannot be met or its bounds end it. Otherwise, to continue, send your next message in the same conversation. A connection authenticated by a Zaru sign-in instead of an aegis_ API key gets no goal. The companion sees the most recent 100 of the conversation's messages.

Knowing the work is done. status says only whether the turn reached its time limit: a turn that started work can be complete while that work goes on. Whether the request is done is the goal's state: open while it is judged or continued, then met, cannot_be_met, exhausted (no round left), expired (open past its lifetime) or superseded (a later message started new work). Read it with aegis.goal.status and the answer's goal_id where the connection lists that tool; the conversation on the page shows the same verdicts as cards.

Errors. A refusal is a tool error whose text is a JSON object { "error", "message" }. The error is one of:

errorWhen
unauthorizedThe connection's API key or session is not valid
invalid_requestThe arguments are not valid: message empty or too long, conversation_id not a UUID, or mode not a Zaru mode
conversation_not_foundNo conversation of yours has that id
conversation_archivedThe conversation is archived
active_execution_existsA turn, or a goal's continuation round, is already running in that conversation
mode_not_availablemode is live or vibecode, or operator without an operator escalation, or the call was made from inside a Zaru turn
inference_unavailableZaru cannot reach its model; try again in a moment
turn_failedThe turn could not be run, or failed after it started; a turn that failed after it started keeps what it did stored

Operator Escalation

Through Zaru's MCP server, operator mode and the operator tools are reached only by an operator escalation: an operator generates a one-time code on Zaru Web, gives it to the AI agent, and the agent presents it. Until then a connection carries the ordinary tools of its user, whatever that user's platform role, and an aegis-system token presented to the server is refused 401.

Who can escalate. A person with the aegis:admin or aegis:operator role; aegis:readonly generates no code. The code is redeemed by an aegis_ API key the same person created from their ordinary Zaru sign-in (API Keys). A key created in an operator session, which carries the role itself, cannot hold an escalation, and a connection authenticated by a Zaru sign-in instead of an API key cannot escalate.

Steps.

  1. In Zaru Web's admin area, open MCP escalation and click Generate code. The page shows six digits once, with the time left to use them; they are not shown again.
  2. Give the six digits to the agent. It calls zaru.operator.escalate with them.
  3. The agent lists its tools again: the connection now carries the operator tools and operator mode.

The page also lists your active escalations by key, role, start and expiry, each with End now.

zaru.operator.escalate

Listed to every client connected with an aegis_ API key and handled by Zaru's MCP server, which presents the code to AEGIS with the connection's own key.

ParameterRequiredDescription
codeYesThe six digits shown on the MCP escalation page, exactly as given
// zaru.operator.escalate — 123456 is an example, not a code
{ "code": "123456" }

Returns { aegis_role, expires_at }: the role, aegis:admin or aegis:operator, and when the escalation ends. A refusal is a tool error whose text is { "error", "message" }:

errorWhen
invalid_codeThe code is not six digits, matches no live code of the key's user (already used, invalidated or wrong), or the key cannot hold an escalation
code_expiredThe code matched after its validity ended
escalation_requires_api_keyThe connection is not authenticated by an aegis_ API key
orchestrator_unavailableZaru's MCP server could not reach AEGIS or got no usable answer

A code that is not six digits is refused by the server and never sent. Any other wrong code counts against every live code of that person, and the fifth failure invalidates them: an agent asks the person for the code and never guesses one.

zaru.operator.release

Listed only while the connection's key holds an escalation. No parameters. Ends the escalation now and returns { ended_at }; refused escalation_not_found when the key holds none, and orchestrator_unavailable as above.

What an Escalation Lasts and Carries

  • A code is valid once, for 5 minutes after it is generated by default; an escalation lasts 30 minutes from its redemption by default. A deployment sets both, and the failure count, in spec.iam.operator_escalation (Node Configuration).
  • The escalation is held by the one API key that redeemed it. It ends at its expiry, at End now on the page, at zaru.operator.release, when the key is revoked, when an administrator ends every escalation of that operator, or when the operator's role is withdrawn.
  • While it lasts, the connection's tool list is the operator surface together with the tools of what the person has connected, a call the operator context does not admit is checked against the person's own plan, and zaru.init and zaru.mode offer operator mode. aegis.task.list without agent_id lists the most recent executions of every tenant, each with its tenant_id, and aegis.task.status, aegis.task.logs and aegis.workflow.logs read an execution of any tenant by its id. Naming another tenant in a tool's tenant_id argument is admitted for aegis:admin only.
  • A tool call that arrives after the end is refused, and the ordinary tools return at the next tool listing.
  • AEGIS reads the operator's role again from the identity provider at every escalated tool call and at every redemption. Once the role is withdrawn or changed, or the account is disabled or removed, the next escalated call is refused and every escalation of that operator ends; an escalation that makes no call ends within a minute. A code redeemed after that is refused invalid_code. While the identity provider cannot be read, escalated calls and redemptions are refused and the escalation stays active until the role can be read again or the escalation expires.
  • Every tool call made under an escalation is recorded in the platform's admin audit log under the operator's identity, with the tenant it acted on. On the Podman deployment, make operator-escalation-audit prints these rows (Makefile Targets).
  • Neither tool is offered to the companion inside a Zaru Web turn: only the person holding the code begins or ends an escalation.

Agentic Mode Tools

Agentic mode gives the assistant access to agent discovery, generation, task execution, and monitoring. Use it when you want to run existing agents or generate new ones from a description.

In agentic mode the companion's prompt sends every request for a result to an agent, however simple, starting with aegis.agent.list; it does not answer such a request itself, even with an answer it already knows. It answers directly only talk about the work in hand (what is running, what a result means, what it will do next), and offers Chat through zaru.mode for conversation alone.

In agentic mode the companion's prompt has it treat a system message headed Goal check as coming from Zaru, not from you: the message names the executions already started for your goal and what the judge found missing, and the companion continues from them, reading a completed execution's result with aegis.task.wait or aegis.execution.file instead of starting it again. Zaru Web sends this message at the start of a continuation round and of a turn that begins while the conversation's goal is open (Goals in Agentic Mode).

Agent Discovery and Generation

aegis.agent.list — Lists all deployed agents with name, version, status, and description. No parameters required. Use this to find agents before running them.

// aegis.agent.list
{}

aegis.agent.generate — Starts an async authoring loop that generates a complete agent manifest from a plain-English description and deploys it. Returns an execution_id immediately.

ParameterRequiredDescription
inputYesNatural-language description of what the agent should do
// aegis.agent.generate
{
  "input": "An agent that reads a CSV file from /workspace, computes summary statistics for each numeric column, and writes a markdown report to /workspace/report.md"
}
// response
{ "execution_id": "e1f2a3b4-...", "status": "started" }

Follow with aegis.agent.wait to block until generation completes.

aegis.agent.wait — Blocks until an agent generation (or any agent execution) reaches a terminal state.

ParameterRequiredDefaultDescription
execution_idYes—ID returned by aegis.agent.generate or aegis.task.execute
poll_interval_secondsNo10Seconds between internal polls
timeout_secondsNo45Seconds this call waits, at most 45 (Waiting on Long Executions)
// aegis.agent.wait
{ "execution_id": "e1f2a3b4-...", "timeout_seconds": 45 }

aegis.agent.logs — Retrieves deployment events and execution summaries for a specific agent by UUID.

ParameterRequiredDefaultDescription
agent_idYes—UUID of the agent
limitNo50Maximum events to return
offsetNo0Pagination offset
// aegis.agent.logs
{ "agent_id": "a1b2c3d4-...", "limit": 20 }

Task Execution and Monitoring

aegis.task.execute — Starts a new execution of a deployed agent by UUID or name. Returns an execution_id.

ParameterRequiredDefaultDescription
agent_idYes—UUID or name of the agent
intentNo—Natural-language goal; steers the LLM prompt
inputNo—Structured data; input.prompt holds full task instructions
versionNolatestSemantic version to execute
// aegis.task.execute
{
  "agent_id": "csv-summary-agent",
  "intent": "Summarize the sales data uploaded this morning",
  "input": {
    "prompt": "The file is at /workspace/sales-2026-04.csv. Focus on Q1 vs Q2 variance."
  }
}

aegis.task.wait — Blocks until an execution reaches a terminal state. Returns the final status, output and error, and produced_files: the files the execution's declared outputs found, each with path, size_bytes and content_type.

ParameterRequiredDefaultDescription
execution_idYes—ID from aegis.task.execute
poll_interval_secondsNo10Seconds between polls
timeout_secondsNo45Seconds this call waits, at most 45 (Waiting on Long Executions)
// aegis.task.wait
{
  "execution_id": "e1f2a3b4-...",
  "poll_interval_seconds": 5,
  "timeout_seconds": 30
}

aegis.task.list — Lists recent executions, optionally filtered by agent.

ParameterRequiredDefaultDescription
agent_idNo—Filter to a specific agent UUID
limitNo20Maximum results

aegis.task.logs — Returns paginated execution events for a specific task.

ParameterRequiredDefaultDescription
execution_idYes—UUID of the task execution
limitNo50Maximum events (cap: 200)
offsetNo0Pagination offset

aegis.task.cancel — Cancels one running agent execution by its id. The person's goal stays open and the execution stays bound to it, so the corrected execution can start next; aegis.goal.cancel ends the whole request.

// aegis.task.cancel
{ "execution_id": "e1f2a3b4-..." }

Execution Output Files

aegis.execution.file — Reads a file from a completed execution's workspace. Available in agentic, execute, and architect modes.

ParameterRequiredDescription
execution_idYes, unless volume_id is givenUUID of the completed execution
volume_idNoA volume of yours to read the file from instead of the execution's workspace, such as the one an aegis.image.generate answer names
pathYesFile path relative to /workspace (e.g. report.md or /workspace/report.md); with volume_id, the path inside that volume (e.g. generated/<batch>/1.jpg)
// aegis.execution.file
{ "execution_id": "e1f2a3b4-...", "path": "report.md" }

Text files return their content inline. Binary files (images, PDFs, archives) return a download_url instead of inline content.

The workspace is available after execution completes and is cleaned up according to the volume's TTL. Retrieve output files before the volume expires.

Tool Discovery

aegis.tools.list — Lists all tools available in the current security context. No parameters.

aegis.tools.search — Searches tools by name and description.

ParameterRequiredDescription
queryNoSearch term (omitting it behaves like aegis.tools.list)
// aegis.tools.search
{ "query": "workflow" }

Workflows

Agentic mode runs a deployed workflow with aegis.workflow.run, after finding it with aegis.workflow.search; once the run has started the companion ends its turn, and it reads the run with aegis.workflow.wait only when you ask, as described under Workflow Generation and Management.

A recording attached to the turn becomes text through the built-in workflow transcribe-audio: aegis.workflow.run with name transcribe-audio; input.audio_path may be left out when one file is attached, and is otherwise the file's name exactly as the chat's attachment marker gives it. With input.speakers set to true the transcript starts a new paragraph at each change of speaker, labelled Speaker 1 and Speaker 2 in turn, for English recordings only. Zaru Web carries the turn's attachments into the run, and its file picker accepts audio. The transcript is the run's answer, shown on the run's card; the companion says the run has started and ends its turn, promising nothing for after it.

Images

Agentic and execute modes offer aegis.image.generate: a request for an image is that one call, with the person's words as prompt and a size they name as size. Each image is saved in the person's chat attachments under generated/, and the chat shows each of the answer's files as an image card. The answer's fetch names how to read a file back, such as "Fetch it with aegis.execution.file, volume_id <id>, path generated/<batch>/1.jpg.".

Schedules

Agentic mode, like architect mode, lists the person's schedules and reads, pauses, resumes and deletes them: aegis.schedule.list, aegis.schedule.get, aegis.schedule.runs, aegis.schedule.pause, aegis.schedule.resume and aegis.schedule.delete, each but list taking schedule_id. Neither mode lists aegis.schedule.create or aegis.schedule.update: after running an agent or workflow for a request that should run again later, the companion proposes a schedule with zaru.schedule, naming what it ran, and the person makes it from the card.

// aegis.schedule.pause
{ "schedule_id": "951ead16-b7ac-4a40-a88c-cf0b6ad1b22d" }

Execute Mode Tools

Execute mode provides a single-shot pipeline: describe a computation in plain English, optionally supply typed inputs, and Zaru generates and runs the code in a sandboxed container. No pre-existing agent is required.

For the full user guide including tier limits, supported languages, and workspace options, see Running Code with Execute Mode.

aegis.execute.intent

Starts the intent-to-execution pipeline. Discovers or generates a code-writing agent, produces the code, runs it in an isolated container, and returns the result.

ParameterRequiredDefaultDescription
intentYes—Natural-language description of what to compute
inputsNo—Typed scalar or structured inputs embedded in the generated code
languageNopythonpython, javascript, or bash
volume_idNoephemeralPersistent volume ID for result storage (Pro and higher)
timeout_secondsNo—Execution timeout override
// aegis.execute.intent
{
  "intent": "compute the mean, median, and standard deviation of this list of numbers",
  "inputs": { "numbers": [14, 22, 8, 31, 19, 7, 45] },
  "language": "python"
}

Returns a pipeline_execution_id. Use aegis.execute.wait to block until the pipeline finishes.

aegis.execute.status

Returns the current status of a pipeline run.

ParameterRequiredDescription
pipeline_execution_idYesID returned by aegis.execute.intent
// aegis.execute.status
{ "pipeline_execution_id": "p1b2c3d4-..." }

Returns { "status": "running" } while in progress, or a completed result with final_result and duration_ms.

aegis.execute.wait

Blocks until the pipeline execution completes. Pass the pipeline_execution_id as execution_id.

ParameterRequiredDefaultDescription
execution_idYes—The pipeline_execution_id from aegis.execute.intent
poll_interval_secondsNo5Seconds between polls
timeout_secondsNo45Seconds this call waits, at most 45 (Waiting on Long Executions)
// aegis.execute.wait
{ "execution_id": "p1b2c3d4-...", "timeout_seconds": 45 }

aegis.goal.cancel

Stops the person's goal: no further round, every execution still running for it cancelled, and the goal closed cancelled with the reason given. The companion calls it when the person asks to stop; to stop one execution and go on, it cancels that execution instead. Also available in agentic and architect modes.

ParameterRequiredDescription
goal_idYesThe goal to stop
reasonNoWhy the person stopped it, in their words; kept with the goal, to 1,000 characters

In Zaru Web the call's schema has no goal_id: the conversation sends its own goal.

// aegis.goal.cancel
{ "goal_id": "g1b2c3d4-...", "reason": "Not needed any more" }

Architect Mode Tools

Architect mode adds workflow and agent design tooling on top of the agentic mode tools. Use it when you need to author new workflows or agents from natural language, validate manifests, or query schemas.

All agentic mode tools (aegis.agent.*, aegis.task.*, aegis.execution.file) are also available in architect mode. The tools below are the additions.

Workflow Generation and Management

aegis.workflow.generate — Starts an async authoring loop that generates a complete workflow manifest from a natural-language objective and registers it.

ParameterRequiredDescription
inputYesNatural-language workflow objective
// aegis.workflow.generate
{
  "input": "A three-stage pipeline: extract keywords from a document, look each keyword up in a knowledge base, then produce a structured summary with citations"
}

Returns { "execution_id": "...", "status": "started" }. Follow with aegis.workflow.wait.

The workflow mode also offers two tools a person uses through the companion:

  • aegis.workflow.create deploys a workflow manifest the person gives, manifest_yaml, registered in the person's tenant; the answer's deployed is true when it was deployed.
  • aegis.workflow.update replaces a deployed workflow of the same name with a manifest the person gives, manifest_yaml and, optionally, force to overwrite the same version; the answer's updated is true when it was replaced.

Each refusal is answered in the tool's own words, and the companion never says a workflow was deployed or updated without the tool's answer.

aegis.workflow.run is listed in architect mode too, as described under Operator Mode Tools: a client in architect mode can start a workflow, such as the built-in Forge. No mode offers the companion aegis.workflow.signal: a run's Human gate is the person's to answer, in Zaru Web on the gate card under the run, on the Approvals page or on the run's execution page (Human Gates of a Workflow Run). In the workflow and agentic modes the companion reads a workflow's inputs before a run and asks for each required one the request does not give, and sends task as the person's request in their own words, as they wrote it, never a paraphrase or a task it composed. When aegis.workflow.run answers started, the companion says the run has started, with its execution_id, that the card below shows its state, and that each Human gate appears on that card and in Approvals for the person to answer there, never in the chat; then it ends its turn without waiting. Nothing of the companion watches the run after its turn, and it promises nothing for after it: not to bring a gate or its prompt into the chat later, nor to watch the run. When the person asks about the run later, it reads the run once with aegis.workflow.wait and answers from that read; when the run waits at a gate, it shows the gate's prompt as a tool answered it, says where the person answers it, and never asks for the answer in the chat. The Zaru MCP server still lists aegis.workflow.signal to an external MCP client such as Claude Code, whose tools/list is the orchestrator's tool list for the person, not a mode's list; there the person's own client calls it. Zaru Web's workflow mode offers aegis.workflow.run as its agentic mode does, and a run started from it carries the conversation's chosen connections, or its profile, as in agentic mode.

aegis.workflow.wait — Blocks until a workflow execution or generation completes.

ParameterRequiredDefaultDescription
execution_idYes—Workflow execution UUID
poll_interval_secondsNo5Seconds between polls
timeout_secondsNo45Seconds this call waits, at most 45 (Waiting on Long Executions)
// aegis.workflow.wait
{ "execution_id": "e1f2a3b4-...", "timeout_seconds": 45 }

aegis.workflow.list — Lists all registered workflows with name, version, and initial state. No required parameters.

aegis.workflow.logs — Returns paginated state-transition and lifecycle events for a workflow execution.

ParameterRequiredDefaultDescription
execution_idYes—UUID of the workflow execution
limitNo50Maximum events (cap: 200)
offsetNo0Pagination offset
// aegis.workflow.logs
{ "execution_id": "e1f2a3b4-...", "limit": 100 }

Schema and Validation Tools

aegis.schema.get — Retrieves the canonical JSON Schema for a manifest kind. Use before writing a manifest to understand required and optional fields.

ParameterRequiredDescription
keyYes"agent/manifest/v1" or "workflow/manifest/v1"
// aegis.schema.get
{ "key": "agent/manifest/v1" }

aegis.schema.validate — Validates a manifest YAML against its canonical schema without deploying it.

ParameterRequiredDescription
kindYes"agent" or "workflow"
manifest_yamlYesThe full manifest YAML text
// aegis.schema.validate
{
  "kind": "agent",
  "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Agent\nmetadata:\n  name: my-agent\n..."
}

Returns { "valid": true, "errors": null } on success or { "valid": false, "errors": ["..."] } on failure.


Operator Mode Tools

Operator mode exposes all tools with no filtering. It includes everything from the modes above plus the tool groups below.

Through Zaru's MCP server, operator mode is reached only by an operator escalation; a platform admin realm token is refused. System tools (aegis.agent.create, aegis.agent.update, aegis.workflow.promote, aegis.workflow.demote) require operator credentials; aegis.workflow.create and aegis.workflow.update are also offered in workflow mode. Destructive tools (aegis.agent.delete, aegis.workflow.delete, aegis.task.remove, aegis.workflow.remove, aegis.system.*) are similarly restricted to operator sessions.

Agent and Workflow Lifecycle

These tools manage the registry directly. They take a manifest YAML and register it synchronously — no async generation loop.

aegis.agent.create / aegis.agent.update — Deploy or update an agent manifest. Pass force: true to overwrite an existing name/version pair.

// aegis.agent.create
{ "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Agent\n..." }

aegis.agent.export — Retrieves the raw manifest YAML of a deployed agent by name.

// aegis.agent.export
{ "name": "csv-summary-agent" }

aegis.agent.delete — Permanently removes an agent from the registry by UUID.

aegis.agent.delete is irreversible. In-progress executions continue to completion but new tasks cannot be dispatched against the deleted agent.

// aegis.agent.delete
{ "agent_id": "a1b2c3d4-..." }

aegis.agent.search — Semantic search over deployed agents by natural-language query.

// aegis.agent.search
{
  "query": "summarize CSV files and produce markdown reports",
  "limit": 5,
  "min_score": 0.7
}

aegis.workflow.create / aegis.workflow.update — Register or update a workflow manifest.

// aegis.workflow.create
{
  "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Workflow\n...",
  "task_context": "Adding a new CSV-parsing stage to the data pipeline."
}

aegis.workflow.validate — Validates a workflow manifest without registering it.

// aegis.workflow.validate
{ "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Workflow\n..." }

aegis.workflow.export — Retrieves the raw manifest YAML of a registered workflow by name.

aegis.workflow.delete — Permanently removes a workflow from the registry.

aegis.workflow.delete removes the definition. In-progress executions are not terminated, but new executions of this workflow will no longer be possible.

aegis.workflow.run — Executes a registered workflow by name.

ParameterRequiredDefaultDescription
nameYes—Workflow name
intentNo—Natural-language goal for this run
inputNo—Structured input parameters
versionNolatestSpecific version to execute
// aegis.workflow.run
{
  "name": "data-pipeline",
  "intent": "Process the April sales extract",
  "input": { "source_path": "/workspace/sales-2026-04.csv" }
}

aegis.workflow.search — Semantic search over registered workflows.

// aegis.workflow.search
{ "query": "data transformation and reporting pipeline", "min_score": 0.65 }

Workflow Execution Control

aegis.workflow.cancel — Cancels one running workflow execution by its id. The person's goal stays open, so the corrected run can start next; aegis.goal.cancel ends the whole request.

// aegis.workflow.cancel
{ "execution_id": "e1f2a3b4-..." }

aegis.workflow.signal — Sends human input to a workflow paused at a Human state: execution_id, response and, optionally, feedback, which the workflow reads as {{human.feedback}}. No mode of Zaru's companion offers it, operator mode included; the Zaru MCP server lists it to external MCP clients such as Claude Code, where the person's own client calls it.

// aegis.workflow.signal
{ "execution_id": "e1f2a3b4-...", "response": "yes", "feedback": "Ship it." }

aegis.workflow.status — Lightweight status snapshot for a workflow execution.

aegis.workflow.executions.list — Lists workflow executions with optional filtering by workflow and pagination.

aegis.workflow.executions.get — Full execution detail including blackboard state and state outputs.

aegis.workflow.remove — Removes a terminal execution record from the registry.

aegis.workflow.remove requires the execution to be in a terminal state (completed, failed, or cancelled). Cancel a running execution first if needed.

aegis.workflow.promote / aegis.workflow.demote — Change a workflow's visibility scope (user → tenant → global and back).

// aegis.workflow.promote
{ "name": "data-pipeline", "target_scope": "tenant" }

Task Status and Cleanup

aegis.task.status — Returns current status and progress of an execution by UUID.

aegis.task.remove — Removes a terminal execution record.

// aegis.task.remove
{ "execution_id": "e1f2a3b4-..." }

Volume and File Tools

aegis.volume.create — Provision a new persistent volume.

// aegis.volume.create
{ "label": "project-data", "size_limit_bytes": 5368709120 }

aegis.volume.list — List all volumes owned by the current user. No parameters.

aegis.volume.quota — Get storage quota usage. No parameters.

aegis.volume.delete — Delete a volume and all its contents.

aegis.volume.delete is irreversible. All files stored in the volume are permanently removed.

aegis.file.list / aegis.file.read / aegis.file.write / aegis.file.delete / aegis.file.mkdir — Operate on files within a specific volume. All require volume_id and path.

// aegis.file.read
{ "volume_id": "vol-abc123", "path": "reports/april-summary.md" }

Git Repository Tools

aegis.git.clone — Create a git repo binding and trigger an async clone into a workspace volume.

ParameterRequiredDefaultDescription
repo_urlYes—Repository URL (https://... or git@...)
labelYes—Binding name; clone is mounted at /workspace/{label}
git_refNo{ kind: "branch", value: "main" }Branch, tag, or commit to check out
shallowNotrueShallow clone
// aegis.git.clone
{
  "repo_url": "https://github.com/my-org/my-repo",
  "label": "my-repo",
  "git_ref": { "kind": "branch", "value": "main" }
}

aegis.git.status — Check clone/refresh status for a binding by binding_id.

aegis.git.refresh — Pull latest remote HEAD into the bound volume.

aegis.git.diff — Return the unified diff of the bound volume's working tree.

aegis.git.commit — Stage all changes and commit with a message. Returns the new commit SHA.

aegis.git.push — Push committed changes to the remote.

aegis.git.list — List all git repo bindings.

aegis.git.delete — Delete a binding and cascade-delete the associated volume.

aegis.git.delete deletes the binding and all associated volume contents. Any uncommitted or unpushed work is lost.

Script Library Tools

Scripts are TypeScript programs stored in the caller's script library. Names must be unique per tenant.

aegis.script.save — Persist a new TypeScript script.

ParameterRequiredDescription
nameYesUnique script name
codeYesTypeScript source
descriptionNoFree-form description
tagsNoArray of lowercase tags

aegis.script.list — List saved scripts, optionally filtered by tag or name substring.

aegis.script.get — Retrieve a script by id, including full version history.

aegis.script.update — Update a script. Bumps the version number monotonically.

aegis.script.delete — Soft-delete a script. Version history is retained; the name becomes available for reuse.

Runtime Discovery

aegis.runtime.list — List all supported runtime environments (language/version pairs). Filter by language to narrow results. Call this before writing spec.runtime in an agent manifest.

// aegis.runtime.list
{ "language": "python" }

See the Standard Runtime Registry for the full runtime matrix.

System Tools

aegis.system.info — Returns node version, health status, and enabled capabilities. No parameters.

aegis.system.config — Returns the full active node configuration as a string. No parameters. See the Node Configuration Reference for the schema.

Dispatch and Filesystem Tools

cmd.run, fs.* (9 tools), and web.* (2 tools) are available in operator mode. cmd.run executes a shell command inside the agent container. fs.* tools operate on the mounted workspace volume directly. web.search and web.fetch make outbound network calls.

// cmd.run
{ "command": "python /workspace/process.py --input data.csv" }

Mode-to-Tools Quick Reference

Abbreviations: C = chat, Ag = agentic, Ex = execute, Ar = architect, Op = operator.

ToolCAgExArOp
zaru.init✓✓✓✓✓
zaru.mode✓✓✓✓✓
zaru.docs✓✓✓✓✓
zaru.connection.needed✓✓✓✓✓
zaru.memory.get✓✓✓✓✓
zaru.memory.set✓✓✓✓✓
zaru.schedule✓✓✓✓✓
zaru.conversations.* (3 tools)✓✓✓✓✓
aegis.agent.generate✓✓✓
aegis.agent.wait✓✓✓
aegis.agent.list✓✓✓
aegis.agent.logs✓✓✓
aegis.task.execute✓✓✓
aegis.task.wait✓✓✓
aegis.task.list✓✓
aegis.task.logs✓✓
aegis.task.cancel✓✓
aegis.execution.file✓✓✓✓
aegis.tools.list✓✓
aegis.tools.search✓✓
aegis.schedule.list✓✓✓
aegis.schedule.get✓✓✓
aegis.schedule.runs✓✓✓
aegis.schedule.pause✓✓✓
aegis.schedule.resume✓✓✓
aegis.schedule.delete✓✓✓
aegis.schedule.create✓
aegis.schedule.update✓
aegis.execute.intent✓✓
aegis.execute.status✓✓
aegis.execute.wait✓✓
aegis.goal.cancel✓✓✓✓
aegis.workflow.wait✓✓✓
aegis.workflow.generate✓✓
aegis.workflow.list✓✓
aegis.workflow.logs✓✓
aegis.schema.get✓✓
aegis.schema.validate✓✓
aegis.agent.create✓
aegis.agent.update✓
aegis.agent.export✓
aegis.agent.delete✓
aegis.agent.search✓✓
aegis.workflow.create✓✓
aegis.workflow.update✓✓
aegis.workflow.validate✓
aegis.workflow.export✓
aegis.workflow.delete✓
aegis.workflow.run✓✓✓
aegis.workflow.cancel✓
aegis.workflow.signal
aegis.image.generate✓✓
aegis.workflow.status✓
aegis.workflow.executions.list✓
aegis.workflow.executions.get✓
aegis.workflow.remove✓
aegis.workflow.promote✓
aegis.workflow.demote✓
aegis.workflow.search✓✓
aegis.task.status✓
aegis.task.remove✓
aegis.runtime.list✓
aegis.volume.create✓
aegis.volume.list✓
aegis.volume.delete✓
aegis.volume.quota✓
aegis.file.* (5 tools)✓
aegis.git.list✓✓✓
aegis.git.* (7 other tools)✓
aegis.script.* (5 tools)✓
aegis.system.info✓
aegis.system.config✓
cmd.run✓
fs.* (9 tools)✓
web.* (2 tools)✓

aegis.workflow.signal is in no mode's list: the companion never answers a workflow run's Human gate. An external MCP client still lists it on Zaru's MCP server.



Edge Fleet Tools (System Tier)

Three system-tier MCP tools cover edge fleet operations. They are gated by an operator/tenant-admin SecurityContext and surfaced to operator-mode conversations and the Fleet Launcher UI.

aegis.edge.fleet.invoke

Invoke any registered tool against an EdgeTarget with a FleetDispatchPolicy. Per-node CommandProgress chunks stream back tagged with node_id; the terminal payload is FleetExecutionResult { fleet_command_id, targets_resolved, targets_skipped, per_node, summary }.

Inputs (selected fields):

FieldDescription
targetTagged-union over Node, Group, Selector, All.
toolTool name to invoke per node. Must declare fleet_capable: true to accept multi-target dispatch.
argsTool-specific argument map.
policy.modeSequential / Parallel / Rolling { batch }.
policy.failure_policyFailFast / ContinueOnError / StopAfter(N).
policy.max_concurrencyOptional cap.
policy.require_min_targetsRefuse upfront if fewer matches resolve.
policy.per_target_deadline_secsPer-call deadline propagated as EdgeCommand.deadline.

aegis.edge.fleet.list

Resolve an EdgeTarget to a node list without dispatching. The operationally critical answer to "show me which hosts this selector hits before I run anything." Zaru's selector preview panel is built on this tool.

aegis.edge.fleet.cancel

Broadcast Cancel to every in-flight per-node command in a fleet operation, addressed by fleet_command_id. Already-completed nodes are unaffected.

fleet_capable flag

Tool descriptors carry a fleet_capable: bool flag. Tools that are inherently single-target (interactive shells, file uploads where the target host matters semantically) declare fleet_capable: false and refuse multi-target dispatch even when the caller tries to fan them out.

For the underlying model, see fleet operations; for the REST shape, see edge REST API.

On this page