Install to your first
multi-agent task

00 / PREPARE

Prepare

You need:

• macOS or Linux terminal
• Homebrew
• A coding agent: Claude Code, Codex CLI, or AGY
• A Markdown / Obsidian vault (optional, for memory consent)

Windows is not supported. Do not put real production credentials in the sample workspace; use a local temporary project for this tutorial.

01 / INSTALL

Install Aegis OS

# Add the Heurion tap and install
brew tap heurion-org/aegis-os https://github.com/heurion-org/aegis-os.git
brew trust heurion-org/aegis-os
brew install aegis-os

# Wire AGY / Claude Code / Codex (run once)
aegis-os install

# Verify
aegis-os --version
aegis-os doctor

After Homebrew installs the binary, run aegis-os install once to wire Aegis OS into agy, claude, and codex; doctor should then pass.

Without Homebrew: download the platform binary from GitHub Releases or build with cargo install --path crates/aos-cli. Then run aegis-os install.

02 / FIRST RUN

Connect an agent

Enter a project directory and launch your agent directly:

# Pick one
claude
codex
agy

Aegis OS hooks attach the runtime automatically. It starts silently in Free Local CoW mode by default, and you can switch to Cloud mode anytime:

You can switch later by telling the agent “switch to Local mode” or “switch to Cloud mode”.

Verify isolation & boundary approval

Ask the agent to modify a file, then run:

aegis-os workspace status
aegis-os workspace diff

The change lands in the CoW shadow workspace first and is not written to the host until workspace_commit. When workspace_commit runs, Aegis OS auto-opens the web approval console (/approve) and auto-resumes once approved, or you can run aegis-os approve (alias: aos approve) in terminal.

03 / MEMORY CONSENT

Memory consent: only the approved scope

UOMP is the memory consent protocol enforced by Aegis OS. First write the client bridge profile and import notes:

aegis-os memory setup claude --vault ~/Notes

This command:

• imports Markdown notes (base tag notes by default; use --tag)
• starts the local memory server in the background (default 127.0.0.1:9374)
• writes the Claude Desktop / Cursor / OpenCode MCP config
• issues no token and grants no access

Restart the client, then ask the agent to read notes:

# In Claude / Cursor / OpenCode
List the notes under notes/projects

The first tool call creates a consent request. Aegis OS opens a local consent page automatically (127.0.0.1:9375); select the tags / keys to grant, then click Allow selected. No second terminal is required.

# If the browser did not open automatically, start the consent UI manually
aegis-os memory ui

# CLI fallback
aegis-os memory pending
aegis-os memory approve <request-id>

The page shows the request id, agent, task id (if any), session id, and expiry. After approval the current call continues; a denial returns an error.

High-sensitivity data is not opened by a tag scope. The consent page lists specific keys separately, and you must select each key; an agent cannot approve its own request.

Verify

aegis-os memory sessions
aegis-os memory audit --limit 20

You should see the session scope, expiry, and allow / deny audit events.

04 / MULTI-AGENT

Multi-agent / A2A

Aegis OS uses Google A2A as the agent-to-agent collaboration bus. Create a stateful task:

aegis-os ipc request \
  --to worker \
  --subject "Review auth module" \
  --message "Read the auth module and report risks"

Inspect tasks:

aegis-os a2a board
aegis-os a2a show <task-id>

board shows task, state, from → to, age, flags, and subject. input-required is pinned with BLOCKED; a task whose assignee disappeared is marked STALE.

Task-scoped lease

If a task needs temporary auto-commit permission, bind a lease to it:

aegis-os policy lease \
  --action-pattern workspace_commit \
  --ttl-secs 3600 \
  --task-id <task-id>

The output contains "kind": "task_scoped" and task_id. When the task reaches a terminal state the lease is revoked; the same agent cannot reuse task A's lease for task B.

If you use a custom --runtime-dir, pass the same runtime directory to all a2a / policy / memory revoke commands.

05 / REVOKE & AUDIT

Revoke and audit

Inspect and revoke a memory session:

aegis-os memory sessions
aegis-os memory revoke <session-id>

After revocation:

• the next memory request returns 401 SESSION_NOT_ACTIVE
• if the session is bound to an A2A task, the task moves to input-required (marked BLOCKED)
• the audit records the revoke event and task id

aegis-os memory audit --limit 20
aegis-os a2a board

If a task reaches a terminal state through the gateway (for example tasks/cancel), Aegis OS calls the memory server's revoke-by-task endpoint and revokes that task's memory sessions automatically.

06 / TROUBLESHOOT

Troubleshooting