Security Model

AgentNode is local-first by design. All tools run on your machine. The registry never sees what you do with them.

AgentNode runs third-party tool code on your machine. This page explains exactly what is enforced, what is declared but not enforced, and what you can do to stay safe.

What is enforced

EnforcedPolicy gate

Every run_tool() call passes through check_run() which evaluates trust level, permissions, and environment context. Returns allow, deny, or prompt. Fail-closed when config is missing.

EnforcedEnv filtering

Subprocess mode strips API keys (AWS_*, OPENAI_*, STRIPE_*, etc.) from the child process environment. Only PATH, HOME, PYTHON*, and TEMP are passed through.

EnforcedSubprocess timeout

Tools running in subprocess mode are killed after a configurable timeout (default 30 seconds).

EnforcedTrust minimum

Your local config sets a minimum trust level (default: verified). Packages below this threshold are denied before execution.

EnforcedCI/non-interactive deny

In CI environments or when AGENTNODE_NON_INTERACTIVE is set, any 'prompt' decision escalates to 'deny'. No silent approvals in automation.

EnforcedAudit trail

All policy decisions are logged to ~/.agentnode/audit.jsonl. Append-only, rotated, local-only. Never contains secrets or tool inputs/outputs.

EnforcedCredential domain lock

CredentialHandle validates the target domain against allowed_domains before attaching credentials. Secrets are never exposed via properties.

EnforcedAgent tool allowlist

Agent packages can only invoke tools explicitly listed in their manifest. Attempts to call unlisted tools are blocked.

What is NOT enforced

Not enforcedNetwork access

Permissions like 'network: none' are declared by the publisher and checked by the policy gate, but not sandboxed at runtime. A tool can still make HTTP requests regardless of its declaration.

Not enforcedFilesystem access

Same as network — declared, policy-checked, but not restricted. A tool with 'filesystem: temp' can still read/write anywhere the process has OS-level access.

Not enforcedDirect mode isolation

mode='direct' runs tool code in your process with full environment access. This is opt-in only — mode='auto' (the default) always uses subprocess isolation.

PartialInput validation

The input guard checks for path traversal and suspicious URLs, but only logs warnings — it never blocks execution.

Privacy

All execution is local. Tool inputs, outputs, and logs never leave your machine.

What the registry sees: Install events, search queries, and periodic trust-level refresh requests.

Audit logs: Stored at ~/.agentnode/audit.jsonl. Never transmitted. Contains only policy decisions (action, source, reason, trust level).

Recommendations

Use agentnode inspect <slug> to review permissions, enforcement status, and policy preview before running a package.
Keep the default mode="auto" which always uses subprocess isolation with env filtering.
For sensitive workloads, run tools inside a VM or container for additional isolation.
Review agentnode audit periodically to see policy decisions for installed packages.
Set a higher minimum trust level in your config if you want stricter package requirements.

Questions or concerns? See our FAQ or reach out on GitHub.