keepcalculator

06 Numbers and Powers

Isolate AI Agents Running Untrusted Code in Containers or VMs

Card No. 06·72318 · Updated · Standard formula, shown below

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

  1. 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.
  2. Create a dedicated user for the sandbox. On the host, run sudo useradd -m -s /bin/bash sandbox. Never run the agent as root.
  3. Set up a container image with minimal tools. Use a base image like python:3.11-slim or node: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.
  4. 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.
  5. Mount only a temporary working directory. Create a temp folder with mkdir /tmp/agent-work and mount it with -v /tmp/agent-work:/work:rw. The agent can write here, but nothing else on the host is writable.
  6. Set a timeout. Use timeout 30s docker run ... to kill the container after 30 seconds. This prevents infinite loops from consuming resources.
  7. 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-as and virsh snapshot-revert.
  8. 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.
  9. 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.
  10. 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.
  11. Consider a sandboxing wrapper. Tools like gVisor (for containers) or Firecracker (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 nobody in Dockerfile).
  • Forgetting to disable networking. If the agent can reach the internet, it can exfiltrate data or download more tools. Use --network none unless you specifically need outbound access.
  • Mounting host directories. Mounting /home or /var into 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. --privileged grants all capabilities and device access—this defeats the purpose of isolation. Never use it for untrusted code.

Tips

  • Use --read-only and mount a tmpfs for /tmp inside the container: --tmpfs /tmp:size=64m to 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=host is 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:rw or set ENV in the Dockerfile.
  • Agent cannot access the internet when needed. If you must allow outbound, use --network bridge and 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 destroy first if needed.
  • High CPU usage on host. The agent is likely spinning. Reduce the --cpus limit and set a shorter timeout. Use ps -p <pid> -o %cpu to 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

The whole Numbers and Powers drawer →