This guide shows you how to isolate AI agents that execute untrusted code—such as LLM-generated scripts, plugin outputs, or user-supplied programs—using containers or virtual machines. You’ll learn the exact steps to set up a secure sandbox, restrict network access, enforce resource limits, and clean up after execution, so a malicious or buggy agent can’t damage your host system or steal data.
What You’ll Need
- A Linux host (Ubuntu 22.04+ or similar) with Docker installed, or a hypervisor like VirtualBox/KVM for VMs.
- Basic command-line familiarity.
- For containers: Docker Engine (20.10+) or Podman.
- For VMs: a virtualization platform and an OS image (e.g., Alpine Linux minimal).
- Optional: a dedicated non-root user account for running the sandbox.
Step-by-Step
- Choose your isolation level. Containers are lighter and faster; VMs provide stronger isolation because they have their own kernel. For AI agents that may need GPU access or run arbitrary system calls, a VM is safer. For typical Python or Node.js scripts, containers with strict seccomp and no privileged mode are sufficient.
- Create a dedicated user for the sandbox. On the host, run
sudo useradd -m -s /bin/bash sandbox. Never run the agent as root. - Set up a container image with minimal tools. Use a base image like
python:3.11-slimornode:20-alpine. Install only the packages your agent needs. Avoid including compilers, shells (except the one required), or package managers in the final image if possible. - Run the container with strict flags. Use
docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges --memory 512m --cpus 1 --pids-limit 100. This removes network access, makes the filesystem read-only, drops all capabilities, prevents privilege escalation, and limits memory, CPU, and process count. - Mount only a temporary working directory. Create a temp folder with
mkdir /tmp/agent-workand mount it with-v /tmp/agent-work:/work:rw. The agent can write here, but nothing else on the host is writable. - Set a timeout. Use
timeout 30s docker run ...to kill the container after 30 seconds. This prevents infinite loops from consuming resources. - For VMs, create a disposable snapshot. In VirtualBox, create a VM with a minimal OS, take a snapshot after setup, and revert to it after each run. For KVM, use
virsh snapshot-create-asandvirsh snapshot-revert. - Pass the untrusted code via stdin or a mounted file. Avoid embedding code in command-line arguments (they appear in process lists). Use
echo "$CODE" | docker run -i ...or copy the code into the mounted work directory. - Capture output and logs. Redirect stdout and stderr to files on the host:
docker run ... > /tmp/agent-out.log 2>&1. For VMs, use serial console or shared folder to retrieve output. - Clean up. After the container exits, remove the temp directory and any files created:
rm -rf /tmp/agent-work. For VMs, revert the snapshot to discard all changes. - Consider a sandboxing wrapper. Tools like
gVisor(for containers) orFirecracker(for microVMs) add an extra layer. gVisor intercepts system calls and emulates them in userspace, reducing kernel attack surface.
Common Mistakes
- Running as root. Even inside a container, root can escape if there’s a kernel vulnerability. Always drop to a non-root user inside the container (
USER nobodyin Dockerfile). - Forgetting to disable networking. If the agent can reach the internet, it can exfiltrate data or download more tools. Use
--network noneunless you specifically need outbound access. - Mounting host directories. Mounting
/homeor/varinto the container gives the agent read/write access to sensitive files. Only mount a dedicated empty temp directory. - No resource limits. Without memory and CPU limits, a runaway agent can freeze the host. Always set
--memory,--cpus, and--pids-limit. - Using privileged mode.
--privilegedgrants all capabilities and device access—this defeats the purpose of isolation. Never use it for untrusted code.
Tips
- Use
--read-onlyand mount a tmpfs for/tmpinside the container:--tmpfs /tmp:size=64mto allow temporary writes without touching the disk. - For GPU-accelerated AI, consider using a VM with GPU passthrough rather than exposing the host GPU to a container—this is more secure but requires hardware support.
- Log all execution metadata: timestamp, container ID, code hash, output. This helps with auditing and debugging.
- Use a separate Docker daemon or at least a separate user namespace (
--userns=hostis default, but consider--userns=remap) to further isolate containers from the host. - Test your sandbox with a known malicious script (e.g., one that tries to read
/etc/passwd) to verify it fails.
Troubleshooting
- Container exits immediately with error. Check the logs:
docker logs <container-id>. Often the agent needs a writable directory or a specific environment variable. Add--tmpfs /work:rwor setENVin the Dockerfile. - Agent cannot access the internet when needed. If you must allow outbound, use
--network bridgeand add a firewall rule to restrict destinations, e.g., allow only specific IPs via iptables. - Permission denied on mounted volume. The container user may not have write access. Run the container with
--user $(id -u):$(id -g)to match the host user, or chmod the temp directory. - VM snapshot revert fails. Ensure the VM is powered off before reverting. Use
virsh destroyfirst if needed. - High CPU usage on host. The agent is likely spinning. Reduce the
--cpuslimit and set a shorter timeout. Useps -p <pid> -o %cputo monitor.
Frequently Asked Questions
Can I use Docker Desktop on Windows or Mac for this?
Yes, but Docker Desktop runs inside a lightweight VM, so the isolation is similar. However, the VM is shared with your host, so a container escape could still affect your host OS. For high-security needs, use a dedicated VM.
Is a VM always safer than a container?
Generally yes, because VMs have a separate kernel and hardware virtualization. Containers share the host kernel, so a kernel exploit could break out. However, VMs have a larger attack surface (hypervisor, guest OS) and are slower.
What about using seccomp or AppArmor?
These are excellent additional layers. Docker has a default seccomp profile that blocks dangerous syscalls. You can also load a custom profile with --security-opt seccomp=profile.json. AppArmor can be enabled with --security-opt apparmor=default.
Can I let the agent access a specific API or database?
Yes, but don’t give it direct network access. Instead, run a proxy or a sidecar container that only forwards to the allowed endpoint. Or use a VM with a firewall that only allows outbound to that IP.
How do I handle agents that need to write large files?
Mount a dedicated volume with a size limit using --storage-opt size=1g (for Docker with overlay2). Or use a tmpfs with a size limit. For VMs, allocate a small virtual disk and enforce quota.
What if my agent needs to run for hours?
Increase the timeout accordingly, but still set a maximum. Use --restart=no and monitor the process. For long-running tasks, consider a VM with a snapshot that you can revert periodically to prevent state drift.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI