Securely Running AI Agents in Docker Sandbox: A Practical Guide

AI agents are powerful but can pose significant security risks if they have unrestricted access to your system. This article distills the key concepts and step‑by‑step instructions from a recent video by Vladimir Karpukhin, showing how to run agents safely inside a Docker Sandbox. It covers why bypass permissions can be dangerous, how the sandbox isolates files, network, and environment variables, and how to configure allowlists to give agents only the access they need.

Context and practical value

The video demonstrates installing and configuring Docker Sandbox on macOS and Windows, explains security risks of bypass permissions, and shows how to set up allowlists to protect sensitive data while running Claude and Codex agents.

This article expands on the video by providing a structured, step‑by‑step guide, clarifying security concepts, and offering troubleshooting tips that were only briefly touched in the source.

Tutorial profile

• Format: dev_setup
• Topic: ai-agent-security
• Audience: intermediate
• Tools: Docker, Homebrew, Hypervisor Platform, sbx CLI, Claude, Codex

Key takeaways

• Docker Sandbox isolates agents from the host, limiting file, network, and process access.
• Bypass permissions can expose agents to prompt injection and file deletion attacks.
• Allowlists let you whitelist specific URLs, files, and network endpoints for controlled agent interaction.
• The sandbox can be set up on both macOS and Windows with minimal prerequisites.
• Agents can still use API keys securely without direct access to .env files.

Why Isolation Matters

AI agents can interpret prompts in unexpected ways, potentially deleting files or terminating processes. Isolation prevents these actions from affecting the host system.

Docker Sandbox Overview

The sandbox runs a lightweight VM inside Docker, restricting file system mounts, network access, and environment variables. It supports agents like Claude and Codex via a CLI.

Setting Up on macOS

Install Homebrew, enable Hypervisor Platform, and run the provided Docker image. Configure the sandbox with sbx run and set up the project directory.

Setting Up on Windows

Ensure Hypervisor Platform is enabled, install Docker Desktop, and follow the same sbx run workflow. Windows users must adjust file permissions for the sandbox.

Configuring Allowlists

Whitelist GitHub, model URLs, and remove risky skills like WebReader. Test that the agent cannot read .env files but can still use API keys via the sandbox.

Testing Security Boundaries

Run checks to confirm the agent cannot delete files, terminate processes, or access unauthorized network endpoints.

Practical next steps

1. Install Docker Desktop and enable Hypervisor Platform on macOS or Windows.
2. Clone the sandbox repository and run sbx run to start the agent inside the sandbox.
3. Create an allowlist JSON file specifying permitted URLs and file paths.
4. Verify that the agent cannot read your .env file but can still call OpenAI APIs.

Limits and verification

• The guide assumes familiarity with Docker and basic command‑line usage.
• Sandbox behavior may differ on older OS versions or non‑standard Docker configurations.

FAQ

Can I run multiple agents in the same sandbox?

Yes, but each agent should have its own sandbox instance to avoid cross‑talk and maintain isolation.

What if the agent needs internet access?

Add the required domains to the allowlist; the sandbox will block all other outbound traffic.