How to Build an AI Agent Execution Boundary

Updated 4 November 2026 · Standard formula, shown below

This guide explains how to set up a secure execution boundary for AI agents that run code. You’ll learn to contain the agent’s actions using operating system permissions, network controls, and resource limits, so a bug or malicious prompt can’t damage your system or data. We’ll cover the essential steps for creating a sandboxed environment, from user accounts to network isolation, and include common pitfalls and troubleshooting tips.

What You’ll Need

A Linux server or workstation (Ubuntu 22.04+ recommended; commands are for systemd-based distros)
sudo/root access
Basic familiarity with the command line
Docker installed (for container isolation)
Optionally, a separate network interface or VLAN for network isolation

Step-by-Step

Create a dedicated user account for the agent. Run sudo useradd -m -s /bin/bash agent and set a strong password with sudo passwd agent. This user will own all agent processes and files, so any compromise is limited to this account’s permissions.
Restrict the user’s filesystem access. Create a home directory with only necessary files: sudo mkdir -p /home/agent/workspace /home/agent/cache. Set permissions so the agent can read/write only in these directories: sudo chown -R agent:agent /home/agent/workspace /home/agent/cache and sudo chmod 700 /home/agent. Avoid giving the agent access to system directories.
Set resource limits using systemd. Create a systemd service file for the agent: sudo nano /etc/systemd/system/agent.service. Add the following:
```
[Service]
User=agent
Group=agent
ExecStart=/usr/bin/python3 /home/agent/workspace/agent.py
MemoryMax=1G
CPUQuota=50%
TasksMax=100
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/agent/workspace /home/agent/cache
```
This limits memory, CPU, process count, and blocks privilege escalation. Adjust paths and ExecStart to your agent’s entry point.
Enable the service. Run sudo systemctl daemon-reload then sudo systemctl enable agent and sudo systemctl start agent. Verify it’s running with sudo systemctl status agent.
Isolate network access. By default, the agent can access the network. To block all network access, add PrivateNetwork=true to the service file. If the agent needs internet, create a separate network namespace or use a firewall. For example, use iptables to allow only specific IPs: sudo iptables -A OUTPUT -m owner --uid-owner agent -d 8.8.8.8 -j ACCEPT and then sudo iptables -A OUTPUT -m owner --uid-owner agent -j DROP. This allows DNS only; adjust as needed.
Use Docker for stronger isolation. For untrusted code, run the agent inside a Docker container with read-only root filesystem and no capabilities. Create a Dockerfile:
```
FROM python:3.11-slim
RUN useradd -m agent
USER agent
WORKDIR /home/agent
COPY --chown=agent:agent . /home/agent/workspace
CMD ["python", "/home/agent/workspace/agent.py"]
```
Run with: docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges --network none -v /home/agent/workspace:/home/agent/workspace:rw agent-image. This limits filesystem writes, drops all capabilities, and blocks network.
Set up a separate user namespace. If using Docker, enable user namespace remapping in /etc/docker/daemon.json: { "userns-remap": "default" }. This maps the container’s root user to a non-root user on the host, preventing container root from having host root privileges.
Monitor and log all activity. Use auditd to track file access: sudo apt install auditd, then add rules: sudo auditctl -w /home/agent/workspace -p rwxa -k agent_activity. Also, enable systemd journal logging for the service: sudo journalctl -u agent -f to see real-time logs.
Test the boundary. Try to break out: as the agent user, attempt to read /etc/shadow, write to /tmp, or access the network. Verify that all attempts fail. Use a test script that tries these actions and report results.
Document and automate. Write a script that sets up the user, service, and firewall rules so you can recreate the environment easily. Store this script in version control.

Common Mistakes

Running the agent as root. This defeats the purpose; always use a non-privileged user.
Forgetting to set NoNewPrivileges=true. Without this, a compromised agent might escalate privileges via setuid binaries.
Using a shared home directory. If the agent user has access to the main user’s files, a breach leaks data. Keep the agent’s home isolated.
Allowing full network access. The agent could exfiltrate data or attack other systems. Restrict network to only necessary endpoints.
Not setting memory limits. A runaway agent can consume all RAM and crash the host. Always set MemoryMax.
Ignoring Docker’s default root user. Even in a container, root inside the container can escape if userns-remap is not enabled. Always enable it.

Tips

Use a read-only root filesystem in Docker to prevent the agent from modifying system binaries.
Set CPUQuota to a low value (e.g., 50%) to prevent CPU exhaustion.
For network access, use a proxy or a dedicated egress firewall with allowlisted domains.
Regularly update the base image and system packages to patch known vulnerabilities.
Use a separate disk partition for the agent’s workspace to avoid filling up the system disk.
Consider using a tool like gVisor or Firecracker for even stronger isolation, but start with basic user/container isolation.

Troubleshooting

Agent cannot write to workspace. Check permissions: ls -ld /home/agent/workspace. Ensure the user owns it and has write permission. In systemd, verify ReadWritePaths includes the directory.
Agent cannot access the network even though you allowed it. Check iptables rules: sudo iptables -L OUTPUT -v. Ensure the owner match is correct (UID of agent). Also, if using Docker with –network none, you must remove that flag.
Service fails to start. Check logs: sudo journalctl -u agent -e. Common issues: wrong ExecStart path, missing Python interpreter, or permission denied on the script. Make the script executable: chmod +x /home/agent/workspace/agent.py.
Docker container cannot write to mounted volume. Ensure the volume is mounted with :rw and the container user has write permission on the host directory. Also, if using userns-remap, the host directory must be owned by the mapped user (e.g., 1000:1000).
Audit logs are too verbose. Filter by key: sudo ausearch -k agent_activity or use auditctl to reduce rules.
Agent still has network access despite PrivateNetwork=true. Restart the service after changing the file: sudo systemctl daemon-reload && sudo systemctl restart agent. Verify with sudo systemctl show agent -p PrivateNetwork.

Frequently Asked Questions

What is an execution boundary?

An execution boundary is a set of restrictions that limit what an AI agent can do when running code. It includes user permissions, filesystem access, network controls, and resource limits, so the agent can only perform allowed actions and cannot harm the host system.

Is a Docker container enough?

Not by itself. Docker provides isolation, but you must also drop capabilities, enable user namespace remapping, and use read-only filesystems. Without these, a container can escape. Always combine Docker with the other steps.

Can I use a virtual machine instead?

Yes, a VM provides stronger isolation because it has a separate kernel. However, it uses more resources. For many use cases, a well-configured container or systemd sandbox is sufficient.

How do I allow the agent to access specific APIs?

Use network restrictions. In systemd, you can’t easily allow specific domains, but you can use iptables to allow specific IPs. For Docker, use a proxy or a firewall on the host. Alternatively, provide a local proxy that the agent must go through.

What if the agent needs to install packages?

Install packages at build time in Docker, or use a separate package cache directory that the agent can write to. In systemd, you can allow write access to a specific cache directory and set PIP_CACHE_DIR. Avoid giving the agent root access.

How do I know if my boundary is secure?

Test it thoroughly. Attempt to read sensitive files, write outside allowed directories, access the network, and escalate privileges. Use tools like lynis or docker-bench-security to audit your setup. Regularly review logs for anomalies.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.