AgentNode Guard

Applies to SDK 0.16+ · Last updated: 2026-06-12

AgentNode Guard is the pre-execution policy gateway built into the SDK. Every install and run call passes through Guard before anything executes. Guard checks trust levels, permission boundaries, and environment context — then allows, denies, or prompts. Every decision is logged to an append-only audit trail.

How it works

Guard sits at the center of every execution path: the Python SDK, the CLI, the MCP adapter, and the agent runtime. There is no way to run or install a pack without Guard evaluating the request first.

1. Check

Guard reads your config (~/.agentnode/config.json), the package's trust level and permissions, and the runtime environment (secrets present? CI? container?).

2. Decide

Based on your policy, Guard returns one of three actions: allow, deny, or prompt. Broken or missing config defaults to deny (fail-closed).

3. Audit

Every decision is logged to ~/.agentnode/audit.jsonl with timestamp, event type, package, action, source, and environment context. The audit trail is append-only and auto-rotated.

Enforcement points

Guard is enforced at every execution path. There is no bypass.

Path	Check	Enforcement
client.install()	check_install	Hard — policy crash = deny
runner.run_tool()	check_run	Hard — deny or prompt stops execution
runtime.handle()	check_run	Hard — returns policy_denied error
MCP call_tool()	check_run	Hard — fail-closed (non-interactive = deny)
agent_runner	trust check	Hard — own trust verification
remote_runner	dispatcher	Hard — audited as remote_run event

Policy configuration

Guard reads your policy from ~/.agentnode/config.json. These are the key settings:

~/.agentnode/config.json

{
  "trust": {
    "minimum_trust_level": "verified"
  },
  "permissions": {
    "network": "prompt",
    "filesystem": "prompt",
    "code_execution": "sandboxed"
  },
  "audit": {
    "max_size_mb": 10,
    "max_files": 5
  }
}

Setting	Values	Description
trust.minimum_trust_level	unverified, verified, trusted, curated	Packages below this level are denied
permissions.network	allow, prompt, deny	How to handle packages requesting network access
permissions.filesystem	allow, prompt, deny	How to handle packages requesting filesystem access
permissions.code_execution	sandboxed, prompt, deny	How to handle packages requesting code execution
audit.max_size_mb	number (default: 10)	Rotate audit log when it exceeds this size
audit.max_files	number (default: 5)	Maximum number of rotated audit files to keep

Environment-aware decisions

Guard detects your runtime environment and escalates decisions when risk is higher:

Secrets detected — if environment variables like AWS_*, OPENAI_*, or DATABASE_URL are present, Guard escalates to prompt for unverified packages with network access
CI mode — detected via CI, GITHUB_ACTIONS, etc. Non-interactive environments use deny instead of prompt
Strict mode — set AGENTNODE_GUARD_STRICT=true to force all uncertain decisions to deny instead of prompt

Viewing the audit trail

Every Guard decision is logged. Use the CLI to inspect:

terminal

# Show recent decisions
$ agentnode audit show

# Show statistics
$ agentnode audit stats

# Export as JSON for analysis
$ agentnode audit show --limit 100 --json > decisions.json