Infrastructure for agent-native applications, with pluggable runtimes.
Canopy is a framework for building multi-user AI agent products where .md files define the agent's behavior, memory, and capabilities. Each user gets an isolated Workspace — a directory that an agent runtime runs against. Canopy infra provisions Workspaces from templates, handles triggers, spawns runtime instances, and routes output. The runtime is pluggable — Claude Code is the default, but any coding agent (Aider, Open Interpreter, or a custom binary) can be configured via CANOPY_RUNTIME.
These docs are an implementation spec: copy this folder into your project, point Claude at it, and it can build the entire Canopy platform for your agent.
# 1. Install
pip install canopy-cli
# 2. Create a workspace from the Codebase Navigator example
canopy create myteam myuser
# → provisions workspaces/myteam_myuser/ from examples/codebase-navigator/
# 3. Connect and start a session
canopy connect myteam_myuser
# → opens an interactive agent session in that workspace
# 4. Or run a one-shot prompt
canopy run myteam_myuser -p "Explain the top-level architecture of this project"1. Developer authors a template (CLAUDE.md, skills, agents, tool configs, settings.json)
2. Canopy infra provisions a Workspace directory for each user from the template
3. Trigger arrives (chat message, scheduled task, webhook)
4. Canopy infra spawns the agent runtime against the Workspace directory → captures stdout
That's it. No custom runtime code, no prompt assembly, no tool dispatch logic. The agent runtime handles context loading, skills, sub-agents, MCP tools, memory, and sandboxing natively. When using Claude Code (the default), this means CLAUDE.md loading, slash commands, agents, and auto-memory — all built in.
Requires Python 3.12+ and uv.
Run without installing (recommended for development):
uv run --directory canopy/cli canopy --helpInstall as editable package:
uv pip install -e canopy/cli
canopy --helpFull reference: cli/README.md
| Command | What it does |
|---|---|
canopy ls |
List all workspaces |
canopy create <account_id> <user_id> |
Provision workspace from a template |
canopy info <name> |
Show workspace details: path, template/version, layers, MCP servers |
canopy connect <name> |
Open interactive agent session in workspace |
canopy run <name> -p "<prompt>" |
Execute one-shot prompt, stream response |
canopy delete <name> |
Delete workspace after confirmation |
Global: --env-file PATH. Auto-loads canopy/.env if present.
Env var: CANOPY_WORKSPACE_BASE_PATH (default: /tmp/canopy/workspaces).
All name arguments support fuzzy (substring) matching.
See cli/README.md for full details.
Canopy is infrastructure for building multi-user AI agent products. Think of it like Docker for agents:
| Docker | Canopy |
|---|---|
| Dockerfile | Template (CLAUDE.md + skills + agents + tool configs + settings.json) |
| Image | Template snapshot at a version |
| Running container | Agent runtime process against a Workspace directory (Claude Code by default, any runtime via CANOPY_RUNTIME) |
| Volumes | Agent-generated files (memory, knowledge) |
| Installed packages | MCP tool integrations |
| Environment variables | User customizations + injected credentials |
| Concept | What it is |
|---|---|
| Workspace | An isolated directory for one user/org. Contains the agent's personality, skills, memory, and tool configs. The agent runtime runs against it. |
| Template | The developer-controlled base layer. Defines the agent's identity, skills, agents, and capabilities. Deployed identically to all users. |
| Canopy Infra | The thin code layer that provisions Workspaces, handles triggers, spawns runtime processes, and routes output. |
| Skill | A .md file that becomes an invocable command — trigger conditions, steps, output format. (When using Claude Code: .claude/commands/ → slash commands.) |
| Sub-Agent | A .md file that defines a specialized agent the runtime can delegate to. (When using Claude Code: .claude/agents/.) |
| Memory | Agent-generated .md files — learned facts, entity profiles, observations. Persists across sessions. (When using Claude Code: auto-memory in .claude/projects/.) |
| Tool | An MCP server configured in settings.json. Exposes operations the agent can call. |
To adopt Canopy in your project, answer five questions:
Example: "Personal executive assistant that manages Slack, Calendar, and Email" Example: "SRE agent that queries logs, metrics, and traces from an observability platform"
List the external APIs and actions the agent can perform (these become MCP servers). Example:
messaging_read,messaging_send_draft,calendar_read,calendar_create,monitoring_query_logs
What data is the same for all users (template) vs unique per user (preferences, memory)? Example: Agent personality = global. User's communication style = learned per user.
What auth, database, and frontend do you already have? Example: "Clerk auth, PostgreSQL, Next.js frontend, OAuth tokens for Slack and Google"
Is this replacing your entire agent system, or enhancing an existing one? Example: "Replace — our current OpenAI Agents SDK setup is being retired" Example: "Enhance — add per-org learned context to our existing multi-agent system"
With these answers, Claude can read this framework and build the Canopy layer for your specific product.
Three ready-to-use templates in examples/, each showcasing a different Canopy capability:
| Template | What it does | What it demonstrates |
|---|---|---|
| codebase-navigator | Helps developers understand any codebase — explains architecture, finds examples, traces data flow | Layer 1 (docs-as-database) + Skills |
| release-pilot | Orchestrates release prep — changelogs, CI checks, pre-release audits, version validation | Multi-step skills + MCP tool patterns |
| daily-standup | Tracks your work and prepares standup summaries | Layer 3 per-user memory (agent learns your projects over time) |
Use one as-is or as a starting point for your own template:
canopy create myteam myuser --template codebase-navigator
canopy create myteam myuser --template release-pilot
canopy create myteam myuser --template daily-standup| Doc | What it covers |
|---|---|
| 01 — Architecture | The Workspace's 3-layer filesystem model, memory format, mapping to runtime primitives |
| 02 — Security | 7 security controls: template immutability, write scoping, tool allowlists, isolation |
| 03 — Versioning | Shipping template updates without destroying user data |
| 04 — Sessions | Session lifecycle, invocation modes (resumable vs one-shot), triggers |
| 05 — Multi-Tenancy | Provisioning, isolation, org Workspaces, Canopy infra responsibilities |
| 06 — The Runtime | Runtime interface, Claude Code reference impl, configuring other runtimes |
| 07 — Adoption Guide | Step-by-step guide with worked examples |
| Claude Code Stream Format | NDJSON event format from claude --output-format stream-json |
These files show the expected structure and conventions for each file type. Claude uses them as reference when generating your template folder.
| File | What it shows |
|---|---|
| CLAUDE.md.template | Agent personality structure (identity, rules, capabilities, learning rules) |
| skill.md.template | Skill file structure (trigger, steps, output format, rules) |
| tool-config.md.template | Tool config structure (agent-facing MCP tool documentation) |
| settings.json.template | Runtime settings structure (MCP servers, permissions, hooks) |
| version.json | Version metadata format |
| workspace-structure.md | Complete directory tree reference |
-
Documents are the database. The agent's personality, memory, skills, and knowledge are
.mdfiles. No ORM. No migrations. The LLM reads and writes them natively. -
Skills are functions. A skill is a prompt template with a trigger, steps, and output format. Creating a new capability means writing a
.mdfile, not writing code. -
The LLM is the CPU. The runtime reads documents, reasons, calls MCP tools, writes memory. It provides the intelligence. Canopy provides the infrastructure.
-
Code is only for I/O. Auth, credentials, webhooks, process management, output routing — these need code. Everything else — personality, behavior, memory, skills — is documents.
-
Don't build what the runtime gives you. Context loading, skills, sub-agents, MCP tools, memory, hooks, sandboxing — leverage what's native. Claude Code provides all of these out of the box; other runtimes may provide a subset.
Canopy is in active development. The CLI (cli/) is functional — create, inspect, connect, run, and delete workspaces. The runtime is configurable via CANOPY_RUNTIME (default: claude-code; supports any binary via custom). The framework specification docs define the full architecture. 90+ tests with CI via GitHub Actions.
Canopy is in its early stages. Contributions welcome:
- Architecture feedback — open an issue with suggestions for the pattern
- Worked examples — submit a PR adding your product type to the Adoption Guide
- MCP server examples — reference MCP server implementations for common integrations
- Bug reports — found an inconsistency or gap in the docs? Let us know
Apache 2.0