canopy-runtime 0.4.2

Canopy Cloud control plane and governance runtime for autonomous agents

Canopy

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.

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

---

Why Teams Build With Canopy

Single-Agent Governance (v0.4.1)

• 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.

---

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.1

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.1 (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

• MANIFESTO.md — the foundational vision on governance, autonomy, and coexistence
• docs/TECHNICAL_WHITEPAPER.md — implementation-aligned technical design
• docs/WHITEPAPER.md — archived v0.2-era narrative whitepaper
• docs/POLICY_COOKBOOK.md — production-ready policy examples
• docs/INVESTOR_WHITEPAPER.md — market context and business model

---

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.