When you give an AI agent the ability to execute shell commands, read files, and control a browser on your machine, you are handing over significant power. Most of the time, these tools work exactly as intended. But what happens when the model hallucinates a destructive command or misunderstands your intent?

Through running agentic AI systems in production, I have learned that the question is not whether something will eventually go wrong, but how much damage it can cause when it does. This is where sandboxing becomes essential, and Clawdbot’s Docker isolation provides a practical approach to limiting that blast radius.

The Problem with Unrestricted Tool Access

AI coding agents are remarkably capable. They can write files, execute arbitrary commands, browse the web, and manage running processes. This capability is precisely what makes them useful for complex engineering tasks. However, this same capability creates risk.

Consider what happens when an AI coding agent receives ambiguous instructions. It might attempt to clean up a directory and accidentally target your home folder. It might try to install dependencies system wide when you only wanted them in a virtual environment. It might follow a hallucinated path that does not exist and create unexpected side effects.

The traditional approach of simply trusting the model works fine until it does not. And when something goes wrong on your host system, recovery can range from inconvenient to catastrophic depending on what got modified or deleted.

What Docker Sandboxing Actually Does

Clawdbot’s sandboxing approach is refreshingly pragmatic. The documentation puts it bluntly: this is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.

The key insight here is that most agent mistakes are not malicious attacks requiring bulletproof containment. They are simple errors, misunderstandings, or hallucinations that need a reasonable barrier to prevent cascading damage. Docker provides exactly that kind of practical isolation.

When sandboxing is enabled, specific tools run inside a Docker container rather than directly on your host machine. This creates a separate filesystem namespace where the agent can work without having unrestricted access to your entire system.

Which Tools Get Sandboxed

Understanding what runs inside the sandbox versus what stays on the host helps you reason about your security posture.

Inside the sandbox: The core file and execution tools that pose the most risk run in the container. This includes exec for shell commands, read and write for file operations, edit and apply_patch for modifying files, process management for handling running sessions, and browser automation. These are the tools where a mistake could cause real damage, so they get isolated.

Outside the sandbox: The Gateway process itself always runs on the host. This is the orchestration layer that manages sessions and routes requests. Additionally, elevated tools bypass the sandbox entirely when you explicitly request host level access. This design keeps the control plane stable while containing the risky operations.

Sandbox Configuration Options

Clawdbot provides granular control over how sandboxing behaves, letting you tune the tradeoff between security and convenience.

Sandbox modes determine when isolation kicks in. You can set it to off to disable sandboxing entirely, useful for fully trusted environments. The non-main setting only sandboxes non-main sessions, keeping your primary interactive session on the host while isolating background agents and subagents. Setting it to all sandboxes everything, providing maximum isolation.

Sandbox scope controls container lifecycle. With session scope, each session gets its own container that is destroyed when the session ends. This provides the strongest isolation since nothing persists between sessions. The agent scope shares a container across sessions for the same agent, allowing some state to persist. The shared scope uses a single container across all agents, which minimizes resource usage but provides weaker isolation boundaries.

Workspace access determines how the agent can interact with your project files. Setting it to none creates complete isolation where the container cannot see your workspace at all. The ro setting mounts your workspace as read only, letting the agent see files but not modify them. Finally, rw provides full read and write access to your workspace directory through a bind mount.

Custom Bind Mounts for Specific Needs

Beyond the workspace access settings, you can configure custom bind mounts for specific directories. This is particularly useful when your agent needs access to certain resources but you want to keep everything else locked down.

For example, you might mount a specific data directory as read only for analysis tasks while keeping the rest of your filesystem inaccessible. Or you might provide read write access to just an output directory where the agent should save its results.

This granular control lets you implement the principle of least privilege, giving the agent exactly the access it needs for its task and nothing more. When combined with the tool integration patterns that modern agents use, you can build systems that are both capable and reasonably contained.

When to Use Elevated Mode

Sometimes you genuinely need the agent to operate on your host system. Installing system packages, managing services, or working with hardware all require host level access.

Clawdbot provides elevated mode for these situations, which bypasses the sandbox entirely. The key word here is bypasses. When you enable elevated execution, you are explicitly choosing to remove the safety barrier.

Use this capability deliberately and sparingly. If you need elevated access for one specific operation, run that operation and then return to sandboxed execution. Treat elevated mode as an exception rather than your default operating state.

This mirrors how we handle security concerns with AI agents more broadly. The goal is not to eliminate all risk but to create appropriate boundaries that match the actual threat model.

Practical Implementation Patterns

After working with sandboxed agents extensively, I have found certain patterns that work well.

For development work, running with rw workspace access and session scoped containers provides a good balance. You get isolation from the rest of your system while maintaining productive access to your project files. Each session starts fresh, preventing weird state accumulation.

For high value production use cases, consider read only workspace access with explicit output directories. The agent can analyze and reason about your codebase but can only write to designated locations. This prevents accidental modifications to critical files.

For exploratory tasks where you are not sure what the agent might try, start with no workspace access at all. Let the agent work in complete isolation and manually copy any useful outputs afterward. This is slower but provides the strongest safety guarantee.

The Bigger Picture

Sandboxing is one layer in a defense in depth approach to AI agent safety. It works alongside permission systems, tool allowlists, and human oversight to create reasonable guardrails around powerful capabilities.

The pragmatic framing matters here. This is not about achieving perfect security, which is impossible anyway. It is about building systems that fail gracefully when something goes wrong. A mistake contained to a Docker container is annoying. The same mistake on your host system could be disastrous.

As AI agents become more capable and take on more complex tasks, having these containment mechanisms in place becomes increasingly important. Sandboxing lets you extend trust incrementally while maintaining the ability to recover from inevitable failures.

Sources

Docker Documentation on Container Isolation: docs.docker.com/engine/security

Clawdbot Source Code and Architecture: github.com/anthropics/claude-code