APort Agent Guardrails is a deterministic pre-action authorization tool for AI agents, published by aporthq, with the repository address at https://github.com/aporthq/aport-agent-guardrails。其核心理念是：护栏在受支持的工具执行之前运行，因此提示注入无法绕过宿主发出的策略检查。
In terms of purpose, this tool is used to perform policy verification before an AI agent invokes sensitive tools (such as files, commands, and external calls), reducing the risks brought by prompt injection and erroneous agent decisions, and shifting risk from runtime behavior to the policy configuration layer. It offers two usage modes: first, Guardrails (CLI/installer), where running the installer creates a passport and configuration; second, Core (library), where OAPGuardrailProvider is used in the application (see docs/PROVIDER.md), so that every tool call is verified. There is one provider per language (Python and TypeScript), and it can work with any framework.
Main capabilities include: deterministic enforcement (runtime hooks, not prompt instructions); fail-closed by default (verification failure blocks high-risk actions); explicit publication modes (--enforcement=warn records completed policy denials but allows framework actions, for policy tuning; --enforcement=observe allows non-mandatory APort runtime/mapping/API failures and issues warnings, for adoption); auditable decisions (every allow/deny is recorded with context); open standard artifacts (Open Agent Passport (OAP) v1.0 passport and decision formats); low latency at production scale (cloud API verification p50 about 53ms, N=1,000). According to the materials, in a live adversarial testbed, the success rate of permissive policies is 74.6%, while under restrictive OAP policies it is 0% (879 top-level attempts).
In terms of usage, it can be run via npm: npx @aporthq/aport-agent-guardrails <framework> (or select a framework when prompted). GitHub repository protection: npx @aporthq/aport-agent-guardrails github generates a GitHub Actions workflow using aporthq/policy-verify-action@v1 from GitHub Marketplace, and is the fastest zero-key path to collect OAP evidence for AI-assisted repository changes. For a blocking setup protecting branches, use --mode hosted --branches main,staging, and add --block-protected-paths to make workflows, policies, packages, or release surfaces fail closed. curl installation of runtime hooks: curl -fsSL https://aport.io/install.sh | bash -s -- claude-code. Hosted passport available: npx @aporthq/aport-agent-guardrails <framework> <agent_id>. Change enforcement mode without rebuilding the passport: npx @aporthq/aport-agent-guardrails mode claude-code --enforcement=warn. Reset framework: npx @aporthq/aport-agent-guardrails reset claude-code --yes.
Passport setup options include: 1) Create a hosted APort passport now (recommended); 2) Use an existing hosted passport ID (paste agent_id); 3) Create a local passport file (offline/local JSON passport). For non-interactive installation, use --non-interactive together with --mode=local --output <path> to create a local passport; using hosted flags (such as --hosted, etc.) creates a hosted passport.
Supported frameworks and targets: The CLI currently supports github, cursor, claude / claude-code, openclaw, langchain, crewai, deerflow, n8n setup only, as well as beta command hook targets codex, gemini, goose. opencode is intentionally restricted until the current plugin API is verified through smoke testing with the installed version plugin. Python users (LangChain/CrewAI/DeerFlow) can run the same CLI for the wizard and configuration, then install the Python package according to the framework documentation. SDKs and middleware: for Node, @aporthq/sdk-node, @aporthq/middleware-express; for Python, aporthq-sdk-python, aporthq-middleware-fastapi.
Prerequisites: The setup wizard requires Node 18+ (or use the Python CLI). Claude Code, Cursor, Codex, Gemini CLI, and Goose hooks as well as the local evaluator require jq; if jq is missing, hooks in enforce, warn, and observe modes will reject every tool call (APort: jq is required). Audit entries also require python3 in the host PATH; otherwise APort will reject with oap.missing_dependency instead of allowing without an audit record. No need to clone the repository.
Guardrail modes (local vs API): The Node installer (npx @aporthq/aport-agent-guardrails … / bin/agent-guardrails) accepts the same flags for every framework: --mode=api (optional --api-url, default https://api.aport.io）或 --mode=local, and an optional managed ap_<hex> parameter (API mode, no local passport). This flow writes to …/aport/guardrail-mode.env. Python's aport setup CLI does not yet parse these flags.
Enforcement modes: default is enforce, APort fails closed, and policy denials block tool calls. --enforcement=warn is for conservative report-only rollouts: completed policy denials are logged but framework actions continue, while malformed hook input, missing dependencies, invalid mode files, unmapped side-effecting tools, and evaluator integrity failures still block. --enforcement=observe is for adoption-first rollouts: APort returns allow-with-warning for policy denials and non-mandatory APort runtime/mapping/API failures, so developers are not blocked while tuning passports and mappings. Mandatory preconditions (such as missing jq) still block; if APort must create synthetic audit entries for observe-mode adapter/API failures, the hook also needs python3, and unsafe or unavailable audit paths are denied with oap.audit_unavailable or oap.missing_dependency. Observe is not a secure enforcement mode. Host visibility differs: Claude Code shows a systemMessage warning; Cursor returns a best-effort warning field but may not display allow warnings in the UI, so rely on audit logs/status output.
Changing enforcement mode: no need to create a new passport or reinstall hooks; use the mode command. Upgrading an installed runtime: rerunning the unpinned npx @aporthq/aport-agent-guardrails <framework> installer resolves the current npm package, reuses the existing passport, and replaces the stable runtime copy used by the framework hooks. Runtime hooks do not check npm updates during tool calls, so version prompts cannot slow or block agent actions; enterprise deployments can pin an audited version with APORT_PACKAGE_VERSION.
Custom directory installation: each framework's config directory can be moved via an environment variable, and the installer, mode and reset commands, and the Python aport setup CLI all read it (get_config_dir in bin/lib/config.sh). The passport, guardrail-mode.env, runtime copy, and audit logs all land in <dir>/aport/. For example APORT_CLAUDE_CODE_CONFIG_DIR=/srv/agent/claude npx @aporthq/aport-agent-guardrails claude-code. For Codex, Gemini CLI, and Goose, the installer writes the variable into the hook command or wrapper script. For Claude Code and Cursor, the settings file stores only the hook path, and the hook runtime reads the variable, so it must be exported in the host's startup environment; otherwise the hook falls back to ~/.claude or ~/.cursor and denies every call when there is no passport or mode file there. The Python runtime package does not read these variables; instead pass config_path to the provider or callback. To point the hook at a passport outside the config directory, set APORT_PASSPORT_FILE and also set APORT_ALLOW_EXTERNAL_PASSPORT_FILE=1 (the material is interrupted here).
