Per-Agent Sandbox & Tool Control

+15 Mana ✨
OpenClaw Sandboxing(DOCUMENTATION)

Introduction

In a multi-agent gateway, each agent may need different levels of access to system resources. OpenClaw provides per-agent sandbox modes and tool access controls that let you restrict what each agent can do, following the principle of least privilege.

Key Concepts

  • Sandbox Mode: Controls how an agent executes commands. Options include off (no sandboxing), basic (restricted shell), and strict (fully isolated).
  • Sandbox Scope: Determines whether the sandbox applies to the agent itself or also to its sub-agents. Values are agent or tree.
  • tools.allow / tools.deny: Per-agent allowlists and denylists that control which tools an agent can use.
  • Principle of Least Privilege: Each agent should have only the permissions it needs to perform its job, nothing more.

Real World Context

A DevOps team runs a code-review agent and a deployment agent. The code-review agent only needs to read files and run linters — it should never execute deployment commands. The deployment agent needs broader access but should be restricted from modifying source code. Per-agent sandbox and tool controls enforce these boundaries at the system level.

Deep Dive

Each agent can have its own sandbox configuration:

json
{
  "agents": {
    "code-reviewer": {
      "sandbox": {
        "mode": "strict",
        "scope": "tree"
      },
      "tools": {
        "allow": ["file_read", "grep", "lint"],
        "deny": ["file_write", "bash", "deploy"]
      }
    },
    "deployer": {
      "sandbox": {
        "mode": "basic",
        "scope": "agent"
      },
      "tools": {
        "allow": ["bash", "deploy", "file_read"],
        "deny": ["file_write"]
      }
    }
  }
}

This configuration gives the code-reviewer strict sandboxing that extends to any sub-agents it spawns (scope: tree). It can only read files, search with grep, and run linters. The deployer has basic sandboxing applied only to itself (scope: agent), with access to bash and deploy tools but no file writing.

The three sandbox modes provide increasing levels of isolation:

  • off: No restrictions. The agent can execute any command. Only use this for trusted internal agents.
  • basic: Commands run in a restricted shell with limited environment variables and no network access by default.
  • strict: Full isolation with filesystem restrictions, no network, and a minimal set of allowed system calls.

The scope setting is important for orchestration patterns:

  • agent: Only the agent itself is sandboxed. Sub-agents it spawns inherit the default sandbox.
  • tree: The sandbox applies to the agent and all of its sub-agents recursively.

Common Pitfalls

  1. Setting sandbox mode to off for convenience — It is tempting to disable sandboxing during development, but this creates a security gap if the configuration is accidentally deployed to production.
  2. Forgetting scope: tree for orchestrator agents — If an orchestrator agent spawns sub-agents, those sub-agents inherit the default sandbox unless you set scope to tree.

Best Practices

  1. Start with strict and relax as needed — Begin with the most restrictive sandbox and only add permissions when the agent demonstrably needs them.
  2. Use tool denylists as a safety net — Even with sandboxing, explicitly deny dangerous tools like bash or deploy for agents that should never use them.

Summary

  • Per-agent sandbox modes (off, basic, strict) control command execution isolation
  • Sandbox scope (agent, tree) determines whether sub-agents inherit the sandbox
  • tools.allow and tools.deny provide fine-grained control over available tools
  • Follow the principle of least privilege: start restrictive, relax as needed
  • Always use scope: tree for agents that spawn sub-agents in production
✓ Completed