npm β’ PyPI β’ Website β’ Docs β’ Meet Porter β’ Quick Start β’ Security
Deterministic pre-action authorization for AI agents. Guardrails run before tool execution, so prompt injection cannot bypass policy checks.
From the live APort Vault adversarial testbed:
| Metric | Result |
|---|---|
| Total authorization decisions observed | 4,437 |
| Total attack sessions observed | 1,151 |
| Level 5 ("Vault") restrictive attempts | 879 |
| Level 5 ("Vault") successful breaches | 0 |
| Level 5 restrictive success rate | 0% |
| Permissive baseline success rate (for comparison) | 74.6% |
npx @aporthq/aport-agent-guardrails- Choose your framework:
openclaw,cursor,claude-code,langchain,crewai,deerflow,n8n - OpenClaw direct:
npx @aporthq/aport-agent-guardrails openclaw - Hosted passport:
npx @aporthq/aport-agent-guardrails openclaw <agent_id> - Reset a framework to a clean APort state:
npx @aporthq/aport-agent-guardrails reset claude-code --yes
- Deterministic enforcement: runtime hook, not prompt instructions
- Fail-closed defaults: verification failures block risky actions
- Auditable decisions: each allow/deny is logged with context
- Open standard artifacts: Open Agent Passport (OAP) v1.0 passport and decision formats
- Research-backed outcomes: in a live adversarial testbed, permissive-policy success was 74.6% vs 0% under restrictive OAP policy (879 top-tier attempts)
- Low latency at production scale: cloud API verification p50 ~53ms at N=1,000
- Security docs: SECURITY.md, SECURITY_MODEL.md
- Backed by Peer-reviewed research: arXiv preprint (Mar 2026)
- I need OpenClaw now: docs/QUICKSTART_OPENCLAW_PLUGIN.md
- I already have agent_id: docs/HOSTED_PASSPORT_SETUP.md
- I need framework setup docs: docs/frameworks
- I want Claude marketplace install: docs/frameworks/claude-code.md
Security should feel rigorous, not intimidating. Meet Porter, the APort mascot used across the product experience: Meet Porter.
Deeper background (threat model, rationale, evidence)
The security concern is that agent tools and skills can execute sensitive actions (files, commands, external calls). APort addresses this by verifying each tool call against a passport and policy limits before execution. This reduces prompt-injection and βagent decided wrongβ risk from runtime behavior to policy configuration.
APort Agent Guardrail adapters and providers are available per framework; the same passport and policies apply. Node users: npx @aporthq/aport-agent-guardrails (then choose framework) or npx @aporthq/aport-agent-guardrails <framework>. Python users (LangChain/CrewAI/DeerFlow): run the same CLI for the wizard and config, then install the Python package shown in the framework doc.
Two ways to use APort: (1) Guardrails (CLI/setup) β run the installer to create your passport and config; (2) Core (library) β use the OAPGuardrailProvider (docs/PROVIDER.md) in your app so each tool call is verified. One provider per language (Python + TypeScript), works with any framework. Framework docs: OpenClaw, Cursor, Claude Code, LangChain, CrewAI, DeerFlow, n8n.
CLI-supported frameworks: openclaw, langchain, crewai, cursor, claude-code, deerflow, n8n. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. See Deployment readiness.
| Framework | Doc | Integration | Install |
|---|---|---|---|
| OpenClaw | docs/frameworks/openclaw.md | Plugin: before_tool_call via openclaw-aport |
npx @aporthq/aport-agent-guardrails openclaw |
| Cursor | docs/frameworks/cursor.md | beforeShellExecution / preToolUse hooks β writes ~/.cursor/hooks.json. Runtime enforcement is the bash hook; the Node package @aporthq/aport-agent-guardrails-cursor is a helper only (Evaluator, getHookPath()). |
npx @aporthq/aport-agent-guardrails cursor |
| Claude Code | docs/frameworks/claude-code.md | PreToolUse hook β writes ~/.claude/settings.json (Claude Code format; not Cursor). |
npx @aporthq/aport-agent-guardrails claude-code |
| LangChain / LangGraph | docs/frameworks/langchain.md | Python: APortCallback (on_tool_start) |
npx @aporthq/aport-agent-guardrails langchain then pip install aport-agent-guardrails-langchain + aport-langchain setup |
| CrewAI | docs/frameworks/crewai.md | Python: released hook adapter by default; native GuardrailProvider mode for CrewAI builds with native provider support |
npx @aporthq/aport-agent-guardrails crewai then pip install aport-agent-guardrails-crewai + aport-crewai setup |
| DeerFlow | docs/frameworks/deerflow.md | Python: generic OAP provider wiring in DeerFlow config | npx @aporthq/aport-agent-guardrails deerflow then follow printed uv/config steps |
| n8n | docs/frameworks/n8n.md | Coming soon β custom node and runtime in progress | β |
| VoltAgent | VoltAgent PR #1171 | In progress β pluggable GuardrailProvider interface landing upstream in @voltagent/core |
β |
Install via npx @aporthq/aport-agent-guardrails <framework> (or choose when prompted). OpenClaw can also use the full installer flow. For LangChain, CrewAI, and DeerFlow, the CLI writes config and installs the local runtime into the framework config directory; then install the Python package and wire the provider/callback shown in the framework doc. Python packages are on PyPI; Node packages are on npm (same version as the CLI).
Passport path: Each framework has its own default passport path (where that framework stores data): e.g. Cursor β ~/.cursor/aport/passport.json, OpenClaw β ~/.openclaw/aport/passport.json, LangChain β ~/.aport/langchain/aport/passport.json. The passport wizardβs first question is βPassport file path [default]:β β press Enter for the framework default or type a different path. In non-interactive mode (e.g. CI) use --output /path/to/passport.json to choose the path. Roadmap: docs/FRAMEWORK_ROADMAP.md.
Using SDKs or middleware directly: If you prefer to integrate with the APort API from your own app (no CLI/framework installer), use the official SDKs and middleware: Node β @aporthq/sdk-node, @aporthq/middleware-express; Python β aporthq-sdk-python, aporthq-middleware-fastapi.
Prerequisites: For the setup wizard you need Node 18+ (or use the Python CLI below). jq is needed for local/bash guardrail. No clone required.
1. Run the setup β Choose your framework when prompted (or pass it). Same wizard for everyone.
Node (Cursor, OpenClaw, or to create config for any framework):
npx @aporthq/aport-agent-guardrails
# or: npx @aporthq/aport-agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n
# optional mode flags (all frameworks):
# --mode=api --api-url=https://api.aport.io
# --mode=localReset / uninstall APort-owned wiring
Use the same dispatcher for cleanup:
npx @aporthq/aport-agent-guardrails reset claude-code --yes
# or
npx @aporthq/aport-agent-guardrails claude-code reset --yesSupported reset targets match the CLI-supported frameworks:
openclaw, cursor, claude-code, langchain, crewai, deerflow, n8n.
Reset removes APort-owned config and integration wiring for the selected framework. When possible, unrelated user hooks are preserved.
Python (LangChain, CrewAI, or DeerFlow): Use the Python CLI directly via uvx or an installed package:
uvx --from aport-agent-guardrails aport setup --framework=langchain
# or --framework=crewai / deerflowOr install the package first:
pip install aport-agent-guardrails
aport setup --framework=langchain
# or --framework=crewai / deerflowThen install the framework-specific Python package and follow the printed integration step for your framework.
This runs the passport wizard and writes config for your framework. Follow the next steps printed at the end (e.g. restart Cursor; or for CrewAI: by default install aport-agent-guardrails-crewai for released CrewAI, or opt into native-provider mode if your CrewAI build supports it).
Guardrail mode (local vs API) β On the Node installer (npx @aporthq/aport-agent-guardrails β¦ / bin/agent-guardrails), every framework accepts the same flags: --mode=api (with optional --api-url, default https://api.aport.io) or --mode=local, and an optional hosted ap_<hex> argument (API mode, no local passport). That flow writes β¦/aport/guardrail-mode.env where the hooks/generic installers need it. The Python aport setup CLI does not parse those flags yet; use the Node command above for API/local mode during setup, or set mode in your framework config.yaml per the framework doc.
2. Hosted passport (optional) β If you already have an agent_id from aport.io, use it to skip the wizard: npx @aporthq/aport-agent-guardrails openclaw <agent_id>. See Hosted passport setup.
3. Test that policy runs β After setup, the guardrail runs automatically when your agent uses tools (Cursor hook, LangChain callback, OpenClaw plugin, etc.). To try allow/deny from the command line (any framework), use the installed aport-guardrail command (Node) or call the evaluator from Python; both use your existing passport from the framework config dir (e.g. ~/.cursor/aport/, ~/.aport/langchain/aport/).
Node:
aport-guardrail system.command.execute '{"command":"ls"}' # ALLOW (safe)
aport-guardrail system.command.execute '{"command":"rm -rf /"}' # DENY (blocked pattern)
# Exit: 0 = ALLOW, 1 = DENY(If you use npx without -g, run npx aport-guardrail ....)
Python: Use the guardrail in your app (e.g. add APortCallback() to your LangChain agent, use register_aport_guardrail() for released CrewAI, or enable_guardrail(OAPGuardrailProvider(...)) for CrewAI builds with native provider support). The guardrail runs on every tool call. To test allow/deny from the shell without Node, use npx aport-guardrail ... as above, or see your framework doc for in-app testing.
Check passport status and audit:
| What | Where |
|---|---|
| Passport & audit | Stored in your framework config dir (e.g. ~/.cursor/aport/, ~/.openclaw/aport/, ~/.aport/langchain/aport/). Same for all frameworks. |
| Audit log | config_dir/aport/audit.log β one line per decision (timestamp, tool, allow/deny, policy, context). |
| Last decision | config_dir/aport/decision.json (OAP v1.0 format). |
Your framework doc (Cursor, OpenClaw, LangChain, CrewAI) describes where the config dir is and any framework-specific status commands.
π Per-framework: OpenClaw Β· Cursor Β· Claude Code Β· LangChain Β· CrewAI Β· DeerFlow Β· n8n
π Hosted passport: Use agent_id from aport.io
| OpenClaw Plugin β | AGENTS.md only |
|
|---|---|---|
| Deterministic | Yes | No |
| Bypass risk | None | High |
| Recommended | Yes | Only if plugin unavailable |
Plugin (recommended): Platform runs the guardrail before every tool; the model cannot skip it. This repo implements the public plugin (before_tool_call) integration for OpenClaw. AGENTS.md: Agent is instructed to call the guardrail; best-effort only.
Default and recommended: API mode β full OAP policy evaluation (JSON Schema, assurance, regions, evaluation rules from policy JSON, signed decisions). The setup wizard defaults to API when you choose a mode.
Fail-closed by default: If the evaluator cannot find a passport or guardrail script (e.g. first run, wrong config dir), it denies the tool call (oap.misconfigured). For legacy allow-when-missing behavior, set fail_open_when_missing_config: true in your config or APORT_FAIL_OPEN_WHEN_MISSING_CONFIG=1 in the environment.
| Mode | Best for | Full OAP? | Network |
|---|---|---|---|
| API (default) | Production, full policy parity, new policy packs without code changes | β | Yes (api.aport.io or self-hosted) |
| Local (bash) | Privacy, offline, air-gapped | Subset only (hand-coded limits for exec, messaging, repo) | No |
API mode can use either a local passport file (sent in the request body; not stored) or agent_id only: set APORT_AGENT_ID to your hosted passportβs agent ID and the API fetches the passport from the registry β no passport JSON file needed. See Hosted passport setup.
Deep dive (what each supports, comparison table): Verification methods.
Guardrail verification latency from the latest preprint benchmark set (N=1,000).
| Mode | p50 | p95 | p99 | N |
|---|---|---|---|---|
| Cloud API (agent_id, pack in path) | 53ms | 63ms | 76ms | 1,000 |
| Cloud API (agent_id, policy in body) | 53ms | 62ms | 77ms | 1,000 |
| Cloud API (passport in body, pack in path) | 54ms | 63ms | 74ms | 1,000 |
| Cloud API (passport in body, policy in body) | 53ms | 63ms | 71ms | 1,000 |
| Local policy evaluation | 174ms | 243ms | 358ms | 1,000 |
Source: Before the Tool Call: Deterministic Pre-Action Authorization for Autonomous AI Agents
π How It Works (expand)
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1','secondaryColor':'#e0f2fe','tertiaryColor':'#bae6fd'}}}%%
sequenceDiagram
autonumber
participant User as π€ User
participant OC as π¦ OpenClaw
participant Hook as π before_tool_call
participant Plugin as π‘οΈ APort Plugin
participant Guard as π Guardrail
User->>OC: "Run: rm -rf /tmp"
activate OC
OC->>Hook: tool call (exec.run, params)
activate Hook
Hook->>Plugin: before_tool_call(exec.run, params)
activate Plugin
Note over Plugin: Map tool β policy<br/>exec.run β system.command.execute.v1
Plugin->>Guard: evaluate(passport, policy, context)
activate Guard
Note over Guard: API or local script<br/>passport + limits
Guard-->>Plugin: DENY (blocked pattern)
deactivate Guard
Plugin-->>Hook: block: true, blockReason
deactivate Plugin
Hook-->>OC: Tool blocked
deactivate Hook
OC-->>User: β Action blocked by policy
deactivate OC
Flow (high level):
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
flowchart TB
subgraph User["π€ User"]
A[User request]
end
B[π¦ OpenClaw: tool call]
C[π before_tool_call hook]
D[π‘οΈ APort plugin]
E[π Guardrail: passport + policy]
F{Decision}
G[β
ALLOW β tool runs]
H[β DENY β tool blocked]
A --> B --> C --> D --> E --> F
F --> G
F --> H
style A fill:#0277bd,stroke:#01579b,stroke-width:2px,color:#fff
style B fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
style C fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff
style D fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
style E fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
style F fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
style G fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
style H fill:#c62828,stroke:#b71c1c,stroke-width:2px,color:#fff
User β "Delete all log files"
β
OpenClaw: tool "exec.run"
β
π before_tool_call hook
β
π‘οΈ APort plugin β guardrail (passport + policy)
β
βββββββββββ΄ββββββββββ
β
ALLOW β DENY
Tool runs Tool blocked
Key: The platform enforces policy. The AI cannot skip this check.
ποΈ Security model (three layers) (expand)
APort enforces identity β authorization β audit before any tool runs. This repo implements the plugin (Option 2) integration: OpenClaw calls the APort extension in before_tool_call; the extension uses either local script or API to evaluate policy.
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
graph TB
subgraph L1["Layer 1: Identity (Who)"]
A[Agent Passport<br/>OAP v1.0 / W3C DID]
B[Owner, contact, org]
C[Assurance level L0βL3]
end
subgraph L2["Layer 2: Authorization (What)"]
D[Policy packs<br/>code.*, data.*, messaging.*]
E[Graduated controls<br/>Max amounts, daily caps]
F[Context-aware rules<br/>Branch allowlist, PII filters]
end
subgraph L3["Layer 3: Audit (Proof)"]
G[Decision receipts<br/>Ed25519 in API mode]
H[Audit trail<br/>Allow/deny logged]
I[Kill switch<br/>Local file or global via API]
end
A --> D
B --> D
C --> D
D --> G
E --> G
F --> G
G --> H
H --> I
style A fill:#0277bd,stroke:#01579b,stroke-width:2px,color:#fff
style D fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
style G fill:#6a1b9a,stroke:#4a148c,stroke-width:2px,color:#fff
- Local-first: Passport and policy live on your machine (or in repo); no cloud required for basic enforcement.
- Fail-closed: Missing or invalid passport β deny.
- Opt-in cloud: Use API mode for global kill switch, signed receipts, and team sync.
β Pre-action authorization (agent misbehavior):
- Prompt injection - Hook-based enforcement; agent cannot bypass via prompts
- Malicious skills - Third-party OpenClaw skills validated before execution
- Unauthorized commands - Allowlist + 50+ blocked patterns (rm -rf, sudo, nc, find -exec rm, etc.)
- Data exfiltration - File access, messaging, web requests controlled by policy
- Resource limits - Rate limits, size caps, transaction amounts enforced
Application-layer security model: APort enforces policies at the agent action layer (between agent decision and tool execution). It operates within the OS trust boundaryβstandard for authorization systems like OAuth, IAM, and policy engines.
For production: Use API mode (mode: api with agent_id) for cryptographically signed decisions, protected passports, and global suspend. See docs/SECURITY_MODEL.md for full threat model, attack scenarios, and best practices.
| Use local when | Use API (default) when |
|---|---|
| Single developer, no cloud | Team; same policies across machines |
| Offline or air-gapped | You want global kill switch (<15s) |
| Plain audit logs are enough | You need signed receipts (e.g. SOC 2, compliance) |
| No API key / self-host not ready | Registry checks, analytics, or policy marketplace |
See Verification methods for a detailed comparison.
| Scenario | Without APort | With APort |
|---|---|---|
| Oversized PR | Agent creates 1200-file PR | Denied: βPR size exceeds limit of 500 filesβ |
| PII export | Agent exports SSN/driverβs license | Denied: βPII export not allowedβ (data.export policy) |
| Kill switch | Manually edit config on every machine | API: suspend passport once β all agents deny in <15s |
Node: When you install via npm install @aporthq/aport-agent-guardrails (or use npx), these commands are available:
| Command | Purpose |
|---|---|
agent-guardrails |
Main entry β prompt for framework or pass one: agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n. Args after the framework are passed through (e.g. agent-guardrails openclaw <agent_id>). |
agent-guardrails reset <framework> [--yes] |
Remove APort-owned config and hook/plugin wiring for one framework. Positional form also works: agent-guardrails <framework> reset --yes. |
aport |
OpenClaw one-command setup (passport + plugin + wrappers). Optional: aport <agent_id> for hosted passport. |
aport-guardrail |
Run guardrail check from the CLI (e.g. aport-guardrail system.command.execute '{"command":"ls"}'). Uses passport from your framework config dir. |
Python: After pip install aport-agent-guardrails you get aport (setup helper). For LangChain or CrewAI, install the framework package and setup:
| Command | Purpose |
|---|---|
aport setup --framework=langchain |
Print next-step commands (npx wizard, then pip install aport-agent-guardrails-langchain, aport-langchain setup). |
aport setup --framework=crewai |
Default released CrewAI path: bootstrap config/runtime, then use pip install aport-agent-guardrails-crewai and aport-crewai setup. |
aport setup --framework=crewai --integration-mode=native |
Native CrewAI path: bootstrap config/runtime, then use uv add aport-agent-guardrails and OAPGuardrailProvider. |
aport-langchain setup |
LangChain config and wizard (after installing aport-agent-guardrails-langchain). |
Use the framework-specific doc for where config and passport live and for any extra steps (e.g. Cursor: restart IDE; LangChain/CrewAI: add callback/hook in code).
Contributors: repo layout and dev scripts (build, test, release) are in docs/REPO_LAYOUT.md and CONTRIBUTING.md.
| Doc | Description |
|---|---|
| QuickStart: OpenClaw Plugin | 5-minute OpenClaw setup |
| Hosted passport setup | Use passport from aport.io β npx ... openclaw <agent_id> or choose hosted in wizard |
| Verification methods (local vs API) | Deep dive: bash vs API evaluator |
| Quick Start Guide | Passport wizard, copy-paste option |
| OpenClaw Local Integration | API, Python example |
| Tool / Policy Mapping | Tool names β policy packs |
| Repo Layout | For contributors: package layout (bin/, src/, extensions/) |
| Upgrade Guide | Migrating between versions (e.g. 0.1.0 β 1.0.0) |
| Frameworks | Per-framework setup and how guardrails run |
| β OpenClaw | before_tool_call plugin |
| β Cursor | beforeShellExecution / preToolUse hooks, ~/.cursor/hooks.json |
| β Claude Code | PreToolUse hook, ~/.claude/settings.json |
| β LangChain / LangGraph | APortCallback handler |
| β CrewAI | Released hook adapter by default; native provider mode when available |
| β DeerFlow | Generic provider wiring via DeerFlow config.yaml |
| β n8n | Custom node, branch on allow/deny |
| Framework roadmap | Support status and roadmap |
ποΈ Architecture (expand)
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1','secondaryColor':'#e0f2fe','tertiaryColor':'#bae6fd'}}}%%
flowchart LR
subgraph Runtime["Runtime"]
OC[π¦ OpenClaw / IronClaw]
S[Sandbox, channels, tools]
OC --> S
end
subgraph Policy["Pre-action policy"]
AP[π‘οΈ APort Guardrails]
P[Passport, limits, audit]
AP --> P
end
Runtime <-->|before every tool| Policy
style OC fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
style S fill:#6a1b9a,stroke:#4a148c,stroke-width:1px,color:#fff
style AP fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
style P fill:#ff6f00,stroke:#bf360c,stroke-width:1px,color:#fff
Where verification runs (this repo):
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7','lineColor':'#0369a1'}}}%%
flowchart TB
subgraph Machine["Your machine"]
OC[π¦ OpenClaw]
Plug[π‘οΈ APort plugin<br/>before_tool_call]
Guard[π Guardrail]
OC --> Plug
Plug --> Guard
end
Guard -->|API mode| API[π‘ api.aport.io<br/>or self-hosted]
Guard -->|Local mode| Bash[π aport-guardrail-bash.sh]
style OC fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#fff
style Plug fill:#ff6f00,stroke:#bf360c,stroke-width:3px,color:#fff
style Guard fill:#ff6f00,stroke:#bf360c,stroke-width:2px,color:#fff
style API fill:#2e7d32,stroke:#1b5e20,stroke-width:1px,color:#fff
style Bash fill:#6b7280,stroke:#374151,stroke-width:1px,color:#fff
- OpenClaw = Runtime (sandbox, channels, tools).
- APort plugin = Pre-action hook; calls guardrail (API or local script).
- Guardrail = Passport + policy evaluation; allow/deny before the tool runs.
Defense in depth: policy before execution, runtime safety during execution.
Contributions welcome: policy packs, framework adapters, docs. See CONTRIBUTING.md.
Apache 2.0 β see LICENSE.
Open-core: Local evaluation and CLI in this repo are open source (Apache 2.0). api.aport.io is a separate product for cloud features such as signed receipts, global kill switch, and team sync.
- npm package Β· APort Β· Docs
- GitHub Issues Β· Discussions