AgentNode Sandbox

AgentNode runs untrusted, community-tier code (verified and unverified publishers, plus any unknown tier) inside a hardened container — or not at all. Trusted and curated packages run on the host by default — with subprocess isolation and policy checks, not OS-level sandboxing — and a user-controlled host-trust policy can sandbox them too. Docker or Podman plus a digest-pinned image are required; there is no silent host fallback.

Who runs where

What gets enforced depends on the package trust level and the kind of code. The matrix below is the single source of truth — there is no blanket rule that every package is sandboxed.

The trust-tier rows describe how a package's code executes under the default host-trust policy; the MCP servers and agents rows note where those runtimes differ. Community-tier code is never downgraded to host execution — and sandbox.host_trust_policy lets you sandbox the vetted tiers too (see below).

Container hardening

When community code runs in the sandbox, the container is locked down: read-only root filesystem, non-root user, all Linux capabilities dropped, no privilege escalation, and CPU / memory / PID limits. No host paths are mounted, no host environment is passed, and the image is referenced by an immutable digest that is never pulled automatically.

docker run -i \
  --rm --read-only --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --user 1000:1000 \
  --pids-limit 256 --memory 512m --cpus 1 \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  -e HOME=/sandbox-home --tmpfs /sandbox-home:rw,size=16m \
  --network none \
  -v agentnode-pack-<slug>-<version>-<hash>:/pack:ro \
  -e PYTHONPATH=/pack \
  ghcr.io/agentnode-ai/sandbox@sha256:6c77...  python -c <wrapper>

The only thing mounted is the pre-built, per-pack-version volume (read-only) whose name is tied to the exact verified artifact, so a stale or mismatched build can never be silently reused.

Network rules

Toolpack and agent-sandbox containers start with --network none. A network is granted only when the package declares a recognized network level; unknown, missing, or none values mean no socket at all — an unknown value is never a silent grant (unknown = deny).

MCP servers are held to the same standard. A community MCP runs only when it is pinned and preinstalled into a sealed volume; it then runs with no network by default, or behind a sealed egress allowlist when it declares mcp_allowed_domains. Non-preinstalled servers that fetch at runtime (floating npx/uvx) are refused — there is no open default-network path. Filesystem, host, and secret isolation apply throughout.

Fail-closed: isolated or not at all

Community execution is fail-closed end to end. If a container runtime or the pinned image is missing, or a toolpack build volume is missing or stale, execution is blocked before any code runs. There is never a silent downgrade to host execution.

Setup & diagnosis

Three commands manage and diagnose the sandbox. The image is only ever fetched by an explicit pull — there is no auto-pull anywhere in the SDK.

$ agentnode sandbox status          # one-line readiness check (no changes)
$ agentnode sandbox doctor          # full diagnosis + guidance
$ agentnode sandbox doctor <slug>   # check one installed package
$ agentnode sandbox pull            # explicitly fetch the digest-pinned image

Host-trust policy — you decide what runs on your host

AgentNode trusting a package's code is not the same as you trusting it with your machine. The sandbox.host_trust_policy setting lets you decide which trust tiers may run directly on your host — enforced uniformly across toolpacks, MCP servers, and agents.

$ agentnode config set sandbox.host_trust_policy curated_only

A tier the policy sandboxes is fail-closed — never a host fallback. Because the sandbox has no host filesystem, no host environment, and a restricted network, a stricter policy can break trusted or curated packages that expect host access. After tightening the policy, reinstall affected packages so their sealed volume is built, and run agentnode sandbox doctor <slug> — now policy-aware — to see exactly what each package needs.

Agent sandbox & LLM keys

Running an agent means running the agent's own code, so it is gated harder. Trusted and curated agents run on the host under the default policy — or in the sandbox when sandbox.host_trust_policy sandboxes their tier. Community agents are refused unless you opt in: the agent sandbox is default OFF.

$ agentnode config set agent_sandbox.enabled true
# or, per shell:  export AGENTNODE_AGENT_SANDBOX=1

When enabled, verified and unverified community agents run sandbox-or-fail-closed in the same hardened container. LLM calls go through a host-side broker: the provider API key stays on the host and never enters the container, audit records, manifests, or lockfiles. Access is default-deny — an agent reaches the host LLM only if its manifest declares llm_access.enabled: true, and the host-config ceiling always wins. Tool calls are routed back to the host and limited to the agent's declared allowlist.

Honest limits

• By default, trusted and curated packages run on the host and are not OS-sandboxed — their network and filesystem declarations are policy-checked, not enforced by the OS. Tighten this with sandbox.host_trust_policy to sandbox them too.
• MCP server containers run with no network by default; egress is only granted through a declared allowlist (mcp_allowed_domains), and non-preinstalled servers are refused.
• The agent sandbox is opt-in and default OFF; with it off, community agents are refused, not run on the host.
• A container runtime (Docker or Podman) and the digest-pinned image are required; without them, community code is blocked, not downgraded.
• The sandbox complements publisher signatures, lockfile integrity, and Guard — it does not replace them.

Related

• Security Model — what is enforced per trust tier, end to end.
• Credentials & Connectors — OS-keychain storage and host-side secret handling.
• Agents — agent tiers, manifests, and llm_access.
• LLM Runtime — how agents and the runtime call models.
• AgentNode Guard — pre-execution action policy and rate limits.
• Package Verification — how trust tiers are earned.