Docker sandboxing

Docker sandboxing runs each agent inside an isolated container with controlled resource limits, restricted filesystem access and optional network isolation. It is designed for situations where you want agents to operate autonomously while limiting the blast radius of any unintended actions.

Prerequisites

Docker sandboxing requires:

• Docker Desktop installed and running on your machine
• The Docker daemon must be accessible (Ironspire connects via the local Docker socket)
• Sufficient system resources to run containers alongside the Electron app

Ironspire checks for Docker availability at startup. If Docker is not installed or the daemon is not running, the sandboxing option is hidden from the agent configuration UI.

Enabling sandboxing

Sandboxing is configured per agent, not globally. To enable it:

1. Right-click an agent in the sidebar and select Reconfigure, or click the agent's settings icon
2. In the Reconfigure modal, find the Sandboxing section
3. Toggle Docker sandbox to on
4. Click Save

The next time the agent starts, it launches inside a Docker container instead of running directly on your host system.

You can enable or disable sandboxing at any time. The change takes effect the next time the agent is started. Running agents are not affected until they are stopped and restarted.

Container specifications

Ironspire uses two container profiles depending on the context:

Agent containers

Agent containers are sized for typical development tasks: running build tools, executing tests, reading and writing project files. The project directory is mounted so the agent can access your codebase, and the npm cache mount avoids repeated dependency downloads across container restarts.

Marketplace containers

Marketplace containers are locked down. They run installed plugins and MCP servers in complete isolation with no network access and no ability to write to disk. This prevents a misbehaving plugin from modifying your files or making outbound network calls.

Container lifecycle

The Docker Service manages the full container lifecycle:

Creation

When you start a sandboxed agent, Ironspire calls createContainer with the appropriate profile (agent or marketplace). The container is created from a base image, resource limits are applied, and volume mounts are configured.

Running

While the agent is active, its terminal sessions route through the container's PTY. Commands the agent executes run inside the container, not on your host. The agent's terminal in Ironspire shows output from the containerised session.

Stopping

When you stop an agent (or it finishes its work), the container is stopped via stopContainer. The container is not removed immediately, allowing you to inspect logs if needed.

Removal

Stopped containers are cleaned up via removeContainer. Ironspire handles this automatically when the agent is reconfigured or the profile is closed.

Health monitoring

Each sandboxed agent displays a container health badge on its agent card in the sidebar. The badge shows:

You can view detailed container metrics by hovering over the badge:

• CPU usage: current CPU utilisation as a percentage of the allocated cores
• Memory usage: current RAM consumption vs. the container limit
• Uptime: how long the container has been running

These metrics come from the Docker Service's getResourceUsage method, which polls the Docker API at regular intervals.

Terminal routing

When an agent is sandboxed, its terminal sessions are routed through the container. This means:

• Commands execute inside the container's filesystem and environment
• Environment variables are scoped to the container
• Installed tools and runtimes are those available in the container image, not your host

The terminal experience in Ironspire looks the same whether the agent is sandboxed or not. The container badge on the agent card is the visual indicator that commands are running in isolation.

If you need to install additional tools inside a container (e.g., a specific CLI tool the agent needs), the agent can do so using standard package managers. Installed tools persist for the lifetime of the container but are lost when the container is removed.

Container logs

To view the raw container logs for a sandboxed agent, use the Docker Service's getContainerLogs method. Ironspire surfaces these logs in the agent's terminal panel. You can also inspect them via Docker Desktop or the Docker CLI:

docker logs <container-id>

The container ID is logged in Ironspire's developer console when the container is created.

E-STOP integration

When you trigger the Emergency Stop, all Docker containers for running agents are terminated as part of the shutdown sequence:

1. Agent statuses are updated to "stopped" (UI updates immediately)
2. Agent PTY sessions are killed
3. Docker containers are stopped and removed via the ShutdownManager
4. Backend cleanup runs with a 3-second timeout

The ShutdownManager ensures containers are cleaned up even if the normal shutdown path fails. No orphaned containers are left running after an E-STOP.

When to use sandboxing

Sandboxing adds a layer of isolation but comes with trade-offs:

Use sandboxing when agents are working on untrusted code, running unfamiliar plugins, or operating with elevated permissions. For trusted agents doing routine development work on your own codebase, running without sandboxing is perfectly reasonable.

Troubleshooting

Common issues and their solutions:

Resource monitoring

Keep an eye on your system's total resource usage when running multiple sandboxed agents. Each agent container reserves its allocated memory (4 GB) and CPU cores (2). Three sandboxed agents consume 12 GB of RAM and 6 CPU cores from your Docker resource pool.

Monitor container resource usage from two places: the health badge tooltip on each agent card (per-agent view) or Docker Desktop's dashboard (system-wide view). If you notice performance degradation, consider reducing the number of simultaneous sandboxed agents or increasing Docker Desktop's resource allocation.

Next steps

• Learn about the Emergency Stop system
• Understand security protections
• Configure agent settings