Agent Sandbox & Security

You found a useful agent online, imported it into Meggy, and hit Run. Three seconds later, it starts scanning your home directory, opening network connections to unknown servers, and burning through CPU. By the time you notice, it's already read files you'd rather keep private.

That's the nightmare scenario when AI agents run without guardrails. Meggy solves this with a declarative sandbox system — you set the rules once, and Meggy enforces them for every execution. No code changes, no manual lockdown. Just a policy that says what the agent can and can't do.

Seven Isolation Modes

Every agent in Meggy has a sandbox policy that controls how its code runs. You pick the isolation level that matches the trust you have in the agent:

Mode Isolation Best For Zero Install?
Auto Decided at runtime based on risk score Most agents — Meggy picks the right level for you ✓
None No isolation — runs in the main process Your own trusted agents that need full access ✓
Process Separate Node.js process Untrusted agents that need basic containment ✓
Restricted Process + filesystem/network enforcement Default for imported agents — blocks unauthorized paths and domains ✓
Docker Full container isolation Maximum lockdown for experimental or risky agents ✗
Deno Deno subprocess with explicit permission flags Agents that need fine-grained OS-level controls ✗
WASM WebAssembly sandbox (QuickJS) Complete isolation with no host access ✗

The first four modes work out of the box — no Docker, Deno, or WASM runtime needed. For most use cases, Auto is the right choice: Meggy evaluates the agent's tools, network needs, and trust tier, then escalates to the minimum isolation level required.

Declarative Policies

Beyond choosing a mode, you can set fine-grained policies that control exactly what an agent can access:

Filesystem Policy

Control which paths agents can read and write:

Network Policy

Control which domains agents can reach:

Resource Limits

Prevent agents from hogging your system:

Auto-Escalation

When you leave the sandbox mode set to Auto, Meggy's danger assessment engine analyzes the agent before every run:

  1. Score the risk — based on which tools the agent requests (filesystem write, terminal access, browser control), its network requirements, budget limits, and the trust level of whoever created it
  2. Pick the minimum isolation — a low-risk agent with no dangerous tools runs with basic process isolation; a high-risk agent with filesystem and network access gets escalated to Restricted or higher
  3. Notify you — when Meggy escalates an agent's sandbox, you see a notification explaining why

This means you never have to think about sandbox configuration for most agents. Just set Auto and Meggy handles the rest — upgrading isolation when needed, keeping things fast when it's safe to do so.

Backward Compatibility

If you've been using Meggy before the sandbox update, your existing agents keep working. The old sandbox values (in-process, child-process, docker) are automatically mapped to the new system:

Old Value New Mode
in-process none
child-process process
docker docker

No migration steps needed — Meggy normalizes legacy values transparently on load.

What's Next?