Skip to Content
Container Sandboxing

Container Sandboxing

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

Docker support is coming soon.

Overview

┌─────────────────────────────────────────────────────┐
│                    Host System                      │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │              Podman Container                 │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │            Engineer Agent               │  │  │
│  │  │                                         │  │  │
│  │  │  • Restricted filesystem access         │  │  │
│  │  │  • Network isolation (configurable)     │  │  │
│  │  │  • Resource limits (CPU, memory)        │  │  │
│  │  │  • No access to host system files       │  │  │
│  │  └─────────────────────────────────────────┘  │  │
│  │                       │                       │  │
│  │              Mount: /workspace                │  │
│  │                       │                       │  │
│  └───────────────────────┼───────────────────────┘  │
│                          │                          │
│                          ▼                          │
│              Project Directory (read/write)         │
└─────────────────────────────────────────────────────┘

Why Use Sandboxing?

BenefitDescription
SecurityAgents cannot access sensitive files outside the project
IsolationFailed or misbehaving agents can’t affect the host system
ReproducibilityConsistent execution environment across different machines
Resource ControlLimit CPU and memory usage per agent

Setup Commands

Set up and manage sandboxing in interactive mode:

CommandDescription
/setup podmanInteractive Podman installation and configuration
/setup podman statusCheck Podman installation and container status
/setup podman helpDisplay sandboxing configuration guide
/orchestrator sandboxManage sandbox settings for agent execution

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

OptionDefaultDescription
enabledfalseEnable container sandboxing
container_imageagentloop-workerDefault container image for agents
network_modeslirp4netnsNetwork isolation mode
memory_limit4gMemory limit per container
cpu_limit2CPU limit per container

Network Modes

ModeDescription
noneComplete network isolation - no network access
slirp4netnsUser-mode networking with NAT (recommended)
hostFull 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"        # Standard worker image
product-manager = "agentloop-worker" # Standard worker image

How It Works

When sandboxing is enabled:

  1. Container Creation - Before task execution, a container is created
  2. Project Mount - The project directory is mounted at /workspace
  3. Agent Execution - The agent runs inside the container
  4. Resource Limits - CPU and memory are capped
  5. Cleanup - Container is removed after task completion

Checking Status

View sandbox status:

> /setup podman status

This shows:

  • Podman installation status
  • Active containers
  • Resource usage
  • Configuration summary

Example Configuration

Project-level config with sandboxing enabled:

[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 works with git worktrees:

  1. A worktree is created for the task
  2. The worktree directory is mounted into the container
  3. The agent works in isolation
  4. Changes are committed from within the container

This provides both branch isolation and execution isolation.

Requirements

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

Troubleshooting

Podman not found:

> /setup podman

This guides you through installation.

Permission denied:

  • Ensure your user is in the podman group
  • Try rootless Podman configuration

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" for debugging
  • Check firewall settings for slirp4netns mode

Branch isolation for parallel development.

Git Worktrees

Full configuration reference.

Configuration
Last updated on
Git WorktreesBackground Daemon