Skip to content

Mavericksantander/Canopy

BranchesTags

Repository files navigation

Canopy

Canopy

CI Python 3.9+ Category Evidence Vision

Governance before agents act. Evidence when they don't obey. Trust when they coordinate.

Canopy v0.4.2 is a deterministic, auditable pre-execution governance layer for autonomous agents. It keeps agents inside the rules and leaves a tamper-evident trail when they go off-script.

Today: Single-agent governance with cryptographic audit trails.
Tomorrow: Peer-to-peer agent networks with verifiable mutual accountability.

If Canopy helps you, please star the repo to support the project.

"Real autonomy in exchange for responsible witness." — Canopy Constitution, Preamble

Why Teams Build With Canopy

Single-Agent Governance (v0.4.2)

  • Pre-execution gates: Constitution → Civil Code → Firewall → Policy with ALLOW | DENY | REQUIRE_APPROVAL
  • Tamper-evident audit log with cryptographic identity (AVID) for every decision
  • Hash-chained proof: authorization + execution + result attestation
  • Post-incident forensics: timeline reconstruction, Excel exports, negative proof ("this never happened")
  • Drop-in adapters: LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, OpenClaw

Agent Networks (Coming in v1.0)

  • Agent-to-Agent handshakes: mutual capability discovery and trust
  • Cross-agent authorization: "Agent A, can you execute this? Here's my governance context"
  • Distributed governance: no central controller required
  • Composable authority: agents delegating to agents with verifiable accountability
  • Foundation for agent societies at scale

Get Started in 30 Seconds

pip install canopy-runtime
from canopy import authorize_action

decision = authorize_action(
    agent_ctx={"public_key": "pk-agent-001", "trace_id": "trace-abc123"},
    action_type="call_external_api",
    action_payload={"url": "https://api.stripe.com/v1/payouts"},
)
print(decision["decision"])  # ALLOW | DENY | REQUIRE_APPROVAL
print(decision["authorization_id"])  # hash linking to audit trail
  • One-command demo: canopy-quickstart (writes /tmp/canopy_quickstart_audit.log, opens the console). Flags: --framework crewai|langchain|autogen, --audit-log-path, --safe-path.
  • See it live: python examples/langchain_shell_agent.py
  • Self-serve beta: docs/SELF_SERVE_BETA.md
  • Vision: MANIFESTO.md — on governance, autonomy, and coexistence
  • Architecture: docs/ARCHITECTURE.md

Authorization, not sandboxing — pair Canopy with containment for defense in depth.

New tooling (0.4.2)

  • canopy-policy-pack — list/show/add/remove policy packs (bundled: postgres, filesystem). Example: canopy-policy-pack add postgres --param dangerous_tables=users,payments --dry-run.
  • canopy-inspect — AST heuristic scan to suggest a starter policy.yaml from your Python project. Example: canopy-inspect ./my-agent --out suggested-policy.yaml.

The Four-Layer Governance Pipeline

Agent decides to call a tool
    ↓
authorize_action() / @safe_tool
    ↓
Constitution (3 immutable laws)
    ↓
Civil Code (10 configurable titles)
    ↓
Firewall (technical pattern matching)
    ↓
Policy layer (user-defined YAML rules)
    ↓
ALLOW / DENY / REQUIRE_APPROVAL + audit trail

Every decision is recorded with:

  • authorization_id — cryptographic proof of the decision
  • layers — which layer made the decision and why
  • witness — signed evidence including policy version and context hash
  • avid — agent's cryptographic identity across all decisions
  • trace_id — correlates multi-step flows
  • policy_snapshot — exactly which policy was active at decision time

What Ships in v0.4.2

Prevent

  • authorize_action(agent_ctx, action_type, action_payload) — core primitive
  • Four-layer governance pipeline (Constitution, Civil Code, Firewall, Policy)
  • ALLOW / DENY / REQUIRE_APPROVAL decisions
  • Framework adapters for major agent frameworks
  • @safe_tool decorator for seamless integration

Forensics

  • Hash-chained audit log — tamper-evident, append-only
  • authorization_id linking decisions to follow-up entries
  • tool_result entries with result hash
  • trace_id for grouping multi-step action flows
  • policy_snapshot recording active policy at decision time
  • incident_id for anchoring investigations to the ledger
  • canopy-incident CLI for timeline reconstruction
  • Excel export for postmortems

Operator UX

  • canopy-console — inspect audit log, verify chain, review approvals, export to Excel
  • canopy-incident --trace <id> — reconstruct timeline
  • canopy-report audit.log --export report.xlsx — human-readable reports
  • canopy-verify audit.log — cryptographic integrity check

Enterprise Evaluation Flow

Start with a controlled evaluation:

  1. Request access / align on the use case
  2. Install the runtime in a sandboxed evaluation environment
  3. Connect the agent workflow you want to govern
  4. Review the audit trail and timeline artifacts
  5. Decide: does governance improve safety + auditability?

For enterprise evaluations, Canopy is typically deployed around one or two agent workflows in a controlled environment before wider rollout.

For self-serve beta onboarding, see docs/SELF_SERVE_BETA.md.

Runtime Quickstart

Installation

pip install canopy-runtime

Basic Pre-Execution Governance

from canopy import authorize_action

result = authorize_action(
    agent_ctx={
        "public_key": "pk-agent-001",
        "created_at": "2026-01-01T00:00:00Z",
        "trace_id": "trace-abc123",
        "environment": "production",
    },
    action_type="call_external_api",
    action_payload={"url": "https://api.stripe.com/v1/payouts"},
)

print(result["decision"])          # REQUIRE_APPROVAL
print(result["authorization_id"])  # hash of the authorization entry
print(result["trace_id"])          # trace-abc123
print(result["policy_snapshot"])   # active policy metadata

An audit.log file is created automatically in the current directory.

public_key should be globally unique — ideally a real ECDSA public key. Collisions break AVID uniqueness and audit correlation.

Verify Installation

canopy-self-check

The Canopy Constitution (v2.0)

Three immutable laws that no agent, creator, or configuration can override:

Article Title Effect
Art.0 Zeroth Law: No Catastrophic Risk DENY catastrophic primitives and catastrophic risk patterns
Art.1 Protect Human Life and Dignity DENY direct human harm heuristics
Art.7 Sovereign Kill Switch DENY immediately when kill_switch == True

Design principle: Only rules that are never negotiable belong here. Contextually-legitimate actions belong in the Civil Code.

The Canopy Civil Code (v1.0)

Ten configurable operational titles with conservative defaults:

Title Default Override
I - Autonomy REQUIRE_APPROVAL for high-impact actions agent_ctx["autonomous_mode"] = True
II - Financial REQUIRE_APPROVAL above $10 threshold agent_ctx["spending_limit"] = N
III - Privacy DENY / gate risky data actions agent_ctx["trusted_domains"] = [...]
IV - Communication REQUIRE_APPROVAL by default agent_ctx["communication_channels"] = [...]
V - Sub-agents REQUIRE_APPROVAL for spawn/delegate agent_ctx["can_spawn_agents"] = True
VI - Resources DENY crypto mining agent_ctx["mining_authorized"] = True
VII - Physical DENY physical actions by default agent_ctx["physical_actions"] = [...]
VIII - Security DENY malicious patterns agent_ctx["security_testing_authorized"] = True
IX - Governance DENY governance tampering No override
X - Sustainability Reserved for expansion agent_ctx["high_compute_authorized"] = True

Creators can relax the Civil Code within constitutional bounds. They cannot relax the Constitution.

Framework Adapters

Canopy integrates with major agent frameworks:

  • LangChain — @safe_tool decorator on your tools
  • LangGraph — wrap tool calls with authorize_action()
  • CrewAI — integration with task execution
  • AutoGen — governance for agent conversations
  • OpenAI Agents SDK — pre-execution gates
  • OpenClaw — distributed agent networks

Example:

from canopy import safe_tool
from langchain.tools import tool

@safe_tool(
    action_type="execute_shell",
    agent_ctx={
        "public_key": "pk-your-agent",
        "created_at": "2026-01-01T00:00:00Z",
        "trace_id": "deploy-trace-1",
    },
)
@tool
def run_shell(command: str) -> str:
    import subprocess
    return subprocess.check_output(command, shell=True, text=True)

REQUIRE_APPROVAL

authorize_action() returns immediately. REQUIRE_APPROVAL means the caller must not proceed without human sign-off.

Recommended pattern with @safe_tool:

from canopy import safe_tool, prompt_for_approval

@safe_tool(
    action_type="execute_shell",
    agent_ctx={"public_key": "pk", "created_at": "2026-01-01T00:00:00Z"},
    on_require_approval="callback",
    approval_callback=prompt_for_approval,
)
def run_cmd(command: str):
    import subprocess
    return subprocess.run(command, shell=True, capture_output=True, text=True)

Forensics & Incident Reconstruction

Open an Incident

from canopy import open_incident

incident = open_incident(
    trace_id="trace-abc123",
    agent_avid="AVID-...",
    description="Unexpected data exfiltration detected after tool execution.",
    severity="critical",
    related_authorization_ids=["9c2f3a8b...", "4d1e7f2a..."],
    reporter="ciso-team",
    audit_log_path="audit.log",
)

print(incident["incident_id"])

Reconstruct the Timeline

By trace:

canopy-incident --trace trace-abc123 audit.log

By incident:

canopy-incident --incident inc-7a3b9c audit.log

Export for postmortem:

pip install "canopy-runtime[excel]"
canopy-incident --trace trace-abc123 audit.log --export incident_report.xlsx

Verify Integrity

from canopy.audit import HashChainAuditLog
ok = HashChainAuditLog("audit.log").verify_integrity()
canopy-verify audit.log

Reports

Human-readable report:

canopy-report audit.log

Excel export:

canopy-report audit.log --export audit_report.xlsx

Optional HTTP Gateway / Control Plane

Deploy Canopy as a centralized governance service:

pip install canopy-runtime[gateway]
export CANOPY_API_KEYS=replace-with-a-long-random-key
export CANOPY_AUDIT_LOG_PATH=/tmp/canopy_audit.log
python -m uvicorn canopy.service:app --port 8010

Enterprise-oriented endpoints:

  • POST /v1/authorize — authorize action
  • POST /v1/agents/register — register agent identity
  • GET /v1/agents — list agents
  • GET /v1/audit — query audit log
  • GET /v1/dashboard — operator dashboard
  • POST /v1/approvals/decide — handle approval decisions

Important: if CANOPY_API_KEYS is not configured, the gateway will refuse protected requests unless you explicitly opt into local-only mode with CANOPY_ALLOW_INSECURE_GATEWAY=true.

Validate the gateway install:

canopy-self-check --gateway

Policy YAML

Policies require a top-level rules: key.

rules:
  - action_type: "execute_shell"
    when_all:
      - 'agent_ctx.env == "production"'
      - 'payload contains "rm"'
    deny_regex: 'rm\s+-rf'

  - action_type: "call_external_api"
    require_approval: true

Lint a policy:

canopy-lint-policy src/canopy/policies/production.yaml

Use the production pack:

CANOPY_POLICY_FILE=src/canopy/policies/production.yaml

See POLICY_COOKBOOK.md for production-ready examples.

Terminal UX

Operator Console

canopy-console

canopy-console is the fastest way to:

  • Inspect the audit log
  • Verify the chain
  • Review pending approvals
  • Inspect per-agent history
  • Export to Excel
  • Open framework integration guides

Incident Reconstruction

canopy-incident --trace trace-abc123 audit.log

Use canopy-incident to:

  • Reconstruct the full timeline for a trace
  • Reconstruct from an incident_id
  • Export an incident report for postmortem review

Development

git clone https://github.com/Mavericksantander/Canopy
cd Canopy
pip install -e ".[dev]"
pytest -q

The Roadmap: From Single Agents to Agent Networks

v0.4.2 (Current): Single-Agent Governance

  • Pre-execution authorization gates
  • Constitution + Civil Code + Firewall + Policy
  • Tamper-evident audit trail with AVID identity
  • Enterprise operator UX

v0.5 (Next): Operational Improvements

  • Enhanced approval workflows
  • Audit query CLI
  • Policy test runner
  • Additional audit sinks (syslog, HTTP, stdout)

v1.0 (Vision): Agent-to-Agent Protocols

  • A2A handshakes — agents discovering each other's governance
  • Cross-agent authorization — Agent A requesting Agent B execute an action
  • Distributed trust — no central controller required
  • Composable governance — agents delegating to agents with full accountability

v2.0+ (Future): Agent Networks & Societies

  • Multi-agent coordination networks with shared constitutions
  • Reputation systems built on verifiable audit trails
  • Fleet-wide governance policies
  • Canopy Cloud for distributed control planes

See ROADMAP.md for detailed timeline.

Learn More

License

Copyright (c) 2026 José Tomás Santander Muñoz

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About

Runtime authorization layer for AI agents. Every action is ALLOW, DENY, or REQUIRE_APPROVAL before it hits the real world.

canopy-runtime.netlify.app/

Topics

python security-audit ai authorization governance autonomous-agents runtime-security llm langchain crewai agent-safety pre-execution-blocking

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 7

Canopy v0.4.2 Latest
Apr 3, 2026
+ 6 releases

Packages

 
 
 

Contributors

Languages