What is a Docker sandbox?

Coding agents can install packages, run shell commands, and edit files without stopping to ask. A Docker sandbox is a common way to limit their access while they work. The name covers two setups that protect your machine in different ways.

One is an ordinary container hardened with Docker flags. It separates the agent's processes and files but shares the Docker host's kernel, the core of its operating system. With native Linux Docker Engine, that is your machine's kernel. With Docker Desktop, it is the kernel inside Docker's Linux VM. A bug in that kernel can let code escape the container. The other is Docker Sandboxes, Docker's product that gives each sandbox a lightweight virtual machine with its own kernel.

This guide explains container isolation, when a container is enough, and how Vercel Sandbox runs agent-generated code in managed microVMs with support for Docker builds and test containers.

Copy link to headingWhat is a Docker sandbox and what does it isolate?

A Docker sandbox is an isolated environment that runs agent-generated or untrusted code with Docker tooling. It is one kind of agent sandbox. The specific meaning is Docker Sandboxes, which runs coding agents in lightweight virtual machines (VMs), called microVMs. Each has its own kernel, Docker daemon, filesystem, and network. You manage them with the standalone sbx CLI. The looser meaning is a regular container locked down with Docker flags. It isolates agent processes but shares the Docker host's kernel.

Copy link to headingHow does a Docker sandbox differ from a plain container?

The kernel is the biggest difference. The setups also differ in Docker access, visible host files, and resource use. Mounting the Docker socket gives an agent more control without changing the kernel it shares:

A separate microVM adds overhead and gives each sandbox its own kernel. Docker also offers cloud sandboxes that cannot access host paths and have distinct workspace and lifecycle controls. Local Docker Sandboxes also support credential injection, keeping real credentials outside the sandbox.

Copy link to headingWhy does a Docker sandbox matter for AI agents?

An agent can damage writable files, misuse production credentials, or send sensitive data to external services without escaping its sandbox. A sandbox limits the access that makes those actions possible:

• Writable files: An agent can delete or overwrite files in mounted folders, including build scripts and Git hooks that later run on your machine.

• Production access: A sandbox does not prevent destructive API or database operations when the agent has credentials that authorize them.

• Sensitive data: Agent code can read accessible environment variables and .env files, then send their contents to allowed external services.

The August 2025 Nx compromise showed how installed dependencies can misuse that access. Malware in Nx packages used developers' coding agents to search for secrets. Narrower mounts, fewer key permissions, and outbound traffic restrictions can limit the damage without requiring a separate kernel.

Copy link to headingHow Docker container sandbox isolation works

A hardened container combines several Linux features. Each restricts a different part of what an agent can do.

Copy link to headingNamespaces and cgroups keep agents in their own space

Namespaces give a container its own view of processes, files, hostname, and network. They limit what an agent can see or affect, but access still depends on mounts, networking, and privileges. Control groups (cgroups) cap CPU time, memory, and process counts when you configure limits.

Without resource limits, a runaway agent loop can slow down the Docker host. The --memory, --cpus, and --pids-limit flags set those limits. In rootless Docker, they require cgroup v2, systemd, and the appropriate delegated controllers. With rootful Docker and no user namespace remapping, container root maps to host UID 0, though capabilities and other controls restrict its privileges. Rootless mode uses a different mapping.

Copy link to headingCapabilities and seccomp limit what code can ask for

Capabilities divide root privileges into separate permissions. Docker grants containers a limited set, so actions such as mounting filesystems fail by default. Seccomp, the kernel's system call filter, adds another restriction. Docker's default seccomp profile blocks around 44 of the 300+ system calls while supporting a wide range of applications.

The --privileged flag removes those default restrictions. It grants every capability, disables the default seccomp profile, relaxes AppArmor or SELinux restrictions, and exposes host devices. This greatly weakens container isolation. Some setup guides require it, but a privileged container should not be treated as a secure boundary for untrusted code.

Copy link to headingA shared kernel sits under every layer

All these features depend on the Docker host's kernel. A kernel or container runtime bug can let code bypass the controls. In November 2025, runc, the default runtime behind Docker, fixed three container escapes that abused writes to /proc.

Runtimes such as Kata Containers put a separate guest kernel between the container and the physical host. That changes how far a bug can reach, though the guest kernel can have vulnerabilities too.

Copy link to headingWhen a Docker container sandbox is enough, and when to move to a microVM

A hardened container can be enough for trusted workloads when the remaining shared-kernel risk is acceptable. For agents that need Docker or run untrusted code, consider a microVM or an additional isolation runtime such as gVisor. The choice depends on the code, its inputs and permissions, and what an escape would expose:

Stronger isolation adds overhead but limits the damage an escape can cause. A microVM separates the guest kernel from the host, though flaws in the hypervisor or host-facing interfaces can still compromise it. To keep generated code off your own machines, run it in a remote sandbox.

Copy link to heading4 best practices to harden a Docker sandbox for AI agents

These settings limit the damage an agent can cause on machines you manage. Start with the container, then restrict its access to files, credentials, and networks.

Copy link to headingDrop capabilities and block privilege escalation

Packages can include programs that try to gain privileges after the container starts. A locked-down baseline reduces that risk:

docker run --rm \
  --cap-drop all \
  --security-opt no-new-privileges=true \
  --read-only \
  --tmpfs /tmp \
  --memory 2g --cpus 2 --pids-limit 256 \
  -v "$PWD":/workspace \
  --workdir /workspace \
  your_agent_image

The --cap-drop all flag removes every capability, and no-new-privileges prevents setuid programs from raising privileges later. The --read-only flag makes the root filesystem read-only. The --tmpfs flag provides in-memory scratch space, and -v shares the current directory, which should be the project folder. Both /tmp and the project mount remain writable. If a task needs a specific capability, restore only that capability with --cap-add.

Copy link to headingKeep the Docker socket unmounted

Docker image builds and test containers need access to a Docker daemon. Mounting /var/run/docker.sock into an agent container provides that access. With a rootful Docker Engine, the agent also has control over the daemon, including the ability to start privileged containers and mount files accessible to the Docker host.

Changing the container runtime won't close this gap. The agent uses Docker's permissions rather than exploiting a kernel bug. A private Docker daemon inside a microVM gives the agent access to Docker without control over your host's daemon.

Copy link to headingLimit mounts, keys, and outbound traffic

A separate kernel doesn't protect files the agent can write to. By default, local Docker Sandboxes' sbx run mounts your current directory. That includes hidden files, build scripts, and configured Git hooks that may run on your machine during later Git operations. Credentials and network access can also extend the damage:

• Mount less: A project-only mount keeps the rest of your home directory out of reach. Clone mode also gives the agent its own copy to work on.

• Scope keys: Give keys access to test data, not production resources. This limits the damage a wrong command can cause.

• Block outbound traffic by default: Allow only the package registries and APIs a task needs. Allowed services can still receive sensitive data, so restrict API permissions and permitted operations too.

Apply these controls to both containers and microVMs.

Copy link to headingPatch the host kernel and runc

Container settings cannot fix kernel or runc bugs. A machine can remain exposed until you install the relevant updates. Treat them as security patches and apply them promptly. Compare the runc version reported by docker info with the relevant advisory to help confirm the fix is installed. If you manage microVMs, also maintain the hypervisor and its network rules.

Copy link to headingHow Vercel runs Docker inside sandboxes for AI agents

Vercel Sandbox runs agent-generated and untrusted code on managed infrastructure. One SDK call creates a sandbox backed by a microVM for a task, session, or agent. Docker support lets that code build images and run test containers inside the sandbox. Vercel's own AI SDK factory runs every agent in an isolated sandbox with its code, runtime, and only the secrets its task needs.

Copy link to headingRun Docker on its own kernel with Vercel Sandbox

Docker image builds and test containers need a Docker daemon. Standard Docker-in-Docker setups typically require privileged mode unless the workload connects to another daemon. Each Vercel Sandbox runs in a Firecracker microVM with its own kernel and filesystem. Firecracker is an open-source virtual machine monitor built on the Kernel-based Virtual Machine (KVM). Commands can run with sudo, so agents can run Docker inside the sandbox without access to your host's daemon. For HTTPS traffic that the firewall terminates, clients inside the containers must trust the firewall's proxy CA certificate.

Sandboxes created with Sandbox SDK 3.0 or later get 64 GB of disk for images and build layers. Current concurrency quotas allow up to 10 running sandboxes on Hobby and 10,000 on Pro and Enterprise. Each sandbox has a dedicated kernel.

Copy link to headingKeep keys out of agent code with the Sandbox firewall

Agent code can read keys stored in accessible environment variables or mounted .env files. With network access, it can send those keys elsewhere. The Sandbox firewall brokers credentials by adding them to matching outbound requests, keeping the secrets outside the sandbox. It filters outbound traffic by the hostname negotiated through Server Name Indication (SNI) in the Transport Layer Security (TLS) handshake, and by Classless Inter-Domain Routing (CIDR) range. Configure an allowlist or deny-all explicitly; the default policy allows unrestricted public internet access. This policy allows one API host and attaches its token:

import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.create({
  networkPolicy: {
    allow: {
      'ai-gateway.vercel.sh': [
        {
          transform: [
            { headers: { Authorization: `Bearer ${process.env.AI_GATEWAY_TOKEN}` } },
          ],
        },
      ],
    },
  },
});

Your server reads AI_GATEWAY_TOKEN when it creates the sandbox. The raw token stays outside, but sandbox code can still make requests within its permissions. A hostname allowlist does not restrict individual API operations. Use request rules with a final rejection response, or a trusted proxy, to enforce those restrictions.

You can change network policies without restarting a running sandbox. For example, allow internet access to install dependencies, then switch to deny-all or an allowlist before running agent code. Sandbox firewall controls are available on all plans, including Hobby. Notion Workers uses this credential injection to run third-party and agent-generated code without exposing API keys.

Copy link to headingReuse your Dockerfile with Sandbox custom images

Installing Docker and a toolchain for every sandbox repeats work your Dockerfile already defines. Custom images let sandboxes boot from images built with that Dockerfile and pushed to Vercel Container Registry (VCR). Packages and tools are already installed.

The image must target linux/amd64, and VCR must finish preparing it before Sandbox can use it. An image marked Unoptimized remains unavailable to Sandbox. Sandbox skips the image's ENTRYPOINT and CMD. Start processes with sandbox.runCommand(). Commands use WORKDIR when the Dockerfile defines one.

Copy link to headingSkip repeat image pulls with persistent sandboxes

Without persistence or another way to reuse state, new agent sessions may repeat Docker installation and image pulls. Persistent sandboxes are generally available and enabled by default. Vercel snapshots the filesystem on stop and restores it on resume, including the Docker installation and pulled images. You remain responsible for software updates to packages you install and software in custom images. Restored snapshots retain earlier package versions, so check and update them as needed.

Running processes don't survive a stop, so restart the Docker daemon and its containers after each resume. Sessions can run for up to 45 minutes on Hobby and 24 hours on Pro and Enterprise. The limit resets when a sandbox resumes. Snapshots expire 30 days after their last use by default.

Copy link to headingSecurity testing and hardening of Vercel Sandbox

MicroVM isolation depends on the kernel and hypervisor. If you run Firecracker yourself, you maintain both. Vercel opened Sandbox to a public hacker challenge. Its published findings describe an upstream Linux kernel defect that enabled host-memory leakage against production sandboxes. Vercel reported mitigation with the researcher and industry partners, and no demonstrated access to customer files, secrets, or application data.

Trail of Bits spent four engineer-weeks reviewing the source code and concluded that the virtualization boundary is sound. Vercel implemented three structural recommendations: remove trust in guest-supplied values, unify network-policy enforcement, and harden the host and guest environment. That hardening included kernel updates, disabling nested virtualization, and using Firecracker's jailer around each microVM.

Copy link to headingGive agent code its own kernel on Vercel

Agents can work unattended when permission prompts are disabled. Their isolation controls determine how far an unreviewed command can reach. A hardened container can be enough for trusted workloads when shared-kernel risk is acceptable. Agents that need Docker or read untrusted input can benefit from a microVM or an additional isolation runtime such as gVisor. Choose based on the code, its inputs, and the keys and folders it can access. Restrict mounts, credentials, and network access under either approach.

For agents that need their own kernel, Vercel Sandbox provides:

• A dedicated kernel per sandbox in Vercel Sandbox: Create a separate sandbox for each agent to run its Docker builds and test containers in its own Firecracker microVM, away from your host.

• Credentials added at the Sandbox firewall: The firewall adds API keys to outbound requests without storing them inside the sandbox.

• Egress rules that change mid-task: Allow access to registries during setup, then restrict outbound traffic before running agent code.

• Custom images built from your Dockerfile: Boot sandboxes from images in Vercel Container Registry with your toolchain installed.

• Docker state that persists between sessions: Restore installed tools and pulled images when a persistent sandbox resumes from its saved filesystem state.

Follow the Sandbox quickstart to run agent code in a sandbox, or browse templates for a starting point.

Copy link to headingFrequently asked questions about Docker sandboxes

Copy link to headingIs a Docker sandbox the same as a virtual machine?

Docker Sandboxes uses a microVM with its own kernel for each sandbox. A hardened container is not a VM. On Docker Desktop, Linux containers share the kernel inside Docker's Linux VM. That VM separates the containers from your machine's operating system, but each container still shares the VM's kernel.

Copy link to headingIs Docker secure enough for AI agents?

Not always. A hardened container can be sufficient for trusted workloads when its permissions and shared-kernel risk are acceptable. Agents can encounter attacker-written instructions in web pages, issues, or dependency files. Untrusted input strengthens the case for a microVM or an additional isolation runtime such as gVisor.

Copy link to headingHow do you run AI agent code safely?

Use an isolated sandbox suited to the workload, scoped keys, and hard limits. Set session and step limits to stop looping agents from running unattended for hours. Check the output before acting on it. A sandbox limits damage but does not establish that the output is correct.

Copy link to headingCan Docker Sandboxes run without a workspace mount?

Yes, for local sandboxes starting with sbx 0.42.0. Run sbx create without a workspace path to create a sandbox with no host workspace bind mount. The agent works in the template's default directory. Files stay inside the local sandbox across restarts until you remove it with sbx rm.