Warden

A deny-by-default sandbox for AI agents, MCP servers, and local AI tools.

Stop AI tools from accessing files, secrets, or network hosts you did not approve. Warden turns broad user permissions into a small, reviewable policy.

Website · Documentation · npm · License

Warden is pre-1.0 security software. Read the security model and limitations before protecting sensitive workloads. Verify native enforcement on the operating system where you will run it.

See the boundary

AI tool → ./project              ✅ allowed
AI tool → .env                   ❌ denied
AI tool → ~/.ssh/id_rsa          ❌ denied
AI tool → api.github.com         ✅ allowed when declared
AI tool → evil.example.com       ❌ denied

The exact result depends on the policy and backend. Warden refuses to run when it cannot establish the requested sandbox instead of silently running without protection.

Install

npm install -g warden-sandbox-cli
warden doctor

Use warden doctor before the first protected run. It checks whether the selected platform backend and its required primitives are ready. For release downloads, source builds, and platform prerequisites, see the installation guide.

Quickstart

Observe a trusted local command, turn the observed accesses into a starter policy, review it, then run the command inside Warden:

warden trace -- npx your-server
warden init
warden run --policy policy.yaml -- npx your-server

Tracing is intentionally unsandboxed. Use disposable data and fake credentials, then narrow the generated policy before running it.

A small policy

filesystem:
  read:
    - ./project

network:
  allow:
    - api.github.com

env:
  allow:
    - GITHUB_TOKEN

With this policy, the process receives only the declared filesystem, network, and environment access. Anything else is not an implicit permission. The full policy reference explains write grants, limits, MCP rules, redaction, and platform differences.

Protect an AI coding agent

When an agent needs to edit code near credentials, use a sanitized workspace:

warden agent --policy agent-policy.yaml -- claude

Warden creates a temporary project projection. Selected environment values and fields in dotenv, JSON, YAML, or TOML files become placeholders. The agent can edit the surrounding code, but Warden shows a sanitized diff and requires your approval before applying changes to the real project.

Read the AI agent workspace guide for the policy format, supported clients, fixed credential requests, limits, and failure behavior.

What Warden controls

• Files: grant selected paths read or write access.
• Secrets: pass only named environment variables, or hide selected values from an agent workspace.
• Network: allow only declared hosts through Warden's policy-aware path.
• Processes: run the whole child process tree inside the selected sandbox, with supported timeout and memory supervision.

How it works

AI agent / MCP server / local tool
                 ↓
              Warden
                 ↓
        policy + OS sandbox backend
                 ↓
          approved resources only

MCP is a first-class workflow, not the product boundary. Warden can wrap local commands directly, and it also provides MCP proxy, gateway, and client setup workflows.

Evidence and platforms

The repository maintains an 18-entry MCP compatibility matrix: 14 pass, 2 are conditional, and 2 are documented failures. These are fixture classifications, not a promise that every upstream service works without configuration.

Native platform status and reproducible proof are documented separately:

• Linux: bubblewrap namespaces and the native proof harness.
• macOS: Seatbelt with platform-specific limitations and fallback paths.
• Windows: AppContainer/WFP/Job Objects with native verification requirements.
• Docker: explicit fallback backend with a larger trust surface.

See test evidence, the compatibility matrix, and the security review. A CI or compile result is not automatically proof of native enforcement on your machine.

Documentation

• Quickstart
• Installation
• AI agent workspace
• Policy reference
• CLI reference
• Compatibility
• Security model and limitations
• Architecture
• Verification and testing
• Contributing

Contributing

Contributions are welcome, especially platform evidence, escape tests, policy fixtures, documentation, and reproducible bug reports. Start with CONTRIBUTING.md. Security issues should follow SECURITY.md.

Warden is released under the MIT License.