Container Sandboxing

AgentLoop supports optional container-based isolation using Podman, providing an extra layer of security for agent execution. When enabled, agents run inside containers with restricted filesystem and network access.

Docker support is on the roadmap.

Overview

Why Use Sandboxing?

Benefit	Description
Security	Agents cannot access sensitive files outside the project
Isolation	Failed or misbehaving agents can’t affect the host system
Reproducibility	Consistent execution environment across different machines
Resource Control	Limit CPU and memory usage per agent

Configuration

Configure container sandboxing in your TOML config:


[orchestrator.container_sandbox]
enabled = false                    # Enable Podman sandboxing
container_image = "agentloop-worker"
network_mode = "slirp4netns"       # none, slirp4netns, or host
memory_limit = "4g"
cpu_limit = "2"
 
[orchestrator.container_sandbox.agent_images]
engineer = "agentloop-worker"
qa-tester = "agentloop-qa-worker"
analyzer = "agentloop-worker"
product-manager = "agentloop-worker"

Options

Option	Default	Description
`enabled`	`false`	Enable container sandboxing
`container_image`	`agentloop-worker`	Default container image for agents
`network_mode`	`slirp4netns`	Network isolation mode
`memory_limit`	`4g`	Memory limit per container
`cpu_limit`	`2`	CPU limit per container

Network Modes

Mode	Description
`none`	Complete network isolation — no network access
`slirp4netns`	User-mode networking with NAT (recommended)
`host`	Full host network access (no isolation)

Per-Agent Images

You can specify different container images for each agent type:


[orchestrator.container_sandbox.agent_images]
engineer = "agentloop-worker"        # Standard worker image
qa-tester = "agentloop-qa-worker"    # Image with testing tools
analyzer = "agentloop-worker"
product-manager = "agentloop-worker"

How It Works

When sandboxing is enabled:

Container creation — Before task execution, a container is created
Project mount — The project (or worktree) directory is mounted at /workspace
Agent execution — The agent runs inside the container
Resource limits — CPU and memory are capped per container
Cleanup — The container is removed after task completion

Example Configuration

Project-level config with sandboxing enabled alongside parallel worktrees:


[orchestrator]
max_parallel_agents = 4
use_worktrees = true
 
[orchestrator.container_sandbox]
enabled = true
network_mode = "slirp4netns"
memory_limit = "8g"
cpu_limit = "4"
 
[orchestrator.container_sandbox.agent_images]
engineer = "agentloop-worker"
qa-tester = "agentloop-qa-worker"

Combining with Worktrees

Sandboxing pairs naturally with git worktrees:

A worktree is created for the task
The worktree directory is mounted into the container
The agent works in isolation — both at the branch level and the OS level
Changes are committed from inside the container

This gives you both branch isolation and execution isolation.

Requirements

Podman must be installed on the host system
The user must have permission to run Podman (rootless mode is supported)
Container images must be available locally or pullable

Troubleshooting

Podman not found

Install Podman from your platform’s package manager and verify with podman --version

Permission denied

Ensure your user can run Podman (try a rootless setup)

Container fails to start

Check available disk space
Verify container images exist: podman images
Check Podman logs: podman logs <container-id>

Network issues

Try network_mode = "host" while debugging
Check firewall settings for slirp4netns mode

Branch isolation for parallel development.

Git Worktrees

Full configuration reference.

Configuration