Container Mode: Running AI Agents in Complete Isolation

Authensor Team · 2026-02-13

Container Mode: Running AI Agents in Complete Isolation

SafeClaw's action gating ensures that every tool call is evaluated against a policy before it executes. But for teams that want defense in depth -- gating plus environment isolation -- we built container mode. It runs your AI agent inside a Docker or Podman container with a hardened security posture.

``bash


safeclaw run --container "refactor the authentication module"



That single flag changes where and how the agent operates. This post explains the design, the security boundaries, and the trade-offs.

What Container Mode Does

When you add --container to a task, SafeClaw does the following:



Detects the container runtime. It checks for Docker first, then Podman. If neither is installed, the command fails with a clear message.

Builds the image (if it does not already exist). The Dockerfile is based on node:20-alpine, installs SafeClaw's dependencies, copies the source, creates a non-root safeclaw user, and sets the entrypoint to the CLI.



Launches the container with a hardened configuration:

- Read-only root filesystem (--read-only)

- Writable tmpfs mounts for /tmp (256 MB, noexec, nosuid) and /home/safeclaw (64 MB, noexec, nosuid)

- Your workspace directory mounted as a volume at /workspace


   - API keys passed via environment variables (never baked into the image)
   - Memory limit: 2 GB
   - CPU limit: 2 cores
   - PID limit: 256 processes

- Non-root user (safeclaw)

Runs the task inside the container. The agent operates on files in /workspace and goes through the same SafeClaw gateway for every action. Output streams back to your terminal.



Security Boundaries

Container mode provides three layers of isolation on top of SafeClaw's policy gating:

Filesystem Isolation

The container's root filesystem is read-only. The agent cannot modify system binaries, configuration files, or SafeClaw's own code. Writable areas are limited to:

/tmp -- a tmpfs mount capped at 256 MB with noexec (cannot execute binaries from tmp) and nosuid (cannot escalate privileges via setuid)

/home/safeclaw -- a tmpfs mount capped at 64 MB for the Claude SDK's home directory requirements

/workspace -- your mounted workspace directory, which is the only persistent writable area

The agent can read and write files in your workspace. It cannot write anywhere else. If the agent tries to rm -rf /, the read-only root filesystem blocks it at the kernel level, independent of SafeClaw's policy.



Resource Limits

Container mode enforces hard resource limits:

2 GB memory. If the agent's process exceeds this, the container is killed by the OOM killer. This prevents runaway memory consumption from affecting the host.
2 CPU cores. The agent cannot monopolize your machine's compute.
256 PIDs. The agent cannot fork-bomb or spawn unbounded subprocesses.

These limits are enforced by the container runtime's cgroup integration. They apply regardless of what the agent does inside the container.

Network Scope

The container has network access -- it needs to reach the Anthropic/OpenAI APIs and the Authensor control plane. But it runs in the default bridge network, isolated from your host's network stack. The agent cannot access services running on localhost on your host machine.

For teams that want stricter network control, the container can be run with custom network policies or in a network namespace with specific egress rules. SafeClaw's policy engine also gates network requests (network.http, network.search) at the action level.



API Key Handling

API keys are the most sensitive data SafeClaw handles. In container mode, keys are passed via environment variables at runtime using Docker's -e flag, which inherits the value from the host's environment. The key is never:

Written to the Dockerfile or image layers
Passed as a build argument

Visible in docker inspect or ps output (because we use -e KEY_NAME without =value, which reads from the process environment)


Inside the container, the key exists only in the process's environment memory. It is not written to disk.

When to Use Container Mode

Container mode is not required to use SafeClaw safely. The gateway and policy engine enforce action gating regardless of where the agent runs. Container mode adds environment-level isolation for teams that want:

Defense in depth. Policy gating prevents the agent from taking unauthorized actions. Container isolation prevents the agent from affecting the host even if there were a bug in the gating layer.
Untrusted tasks. If you are running tasks from external sources (user-submitted prompts, queued jobs), container isolation limits the blast radius.
Compliance requirements. Some frameworks require process isolation as a control. Container mode provides documented, auditable isolation boundaries.
Shared machines. If multiple users or agents share a host, container isolation prevents cross-contamination.

Trade-offs

Container mode has costs:

Startup time. Building the image (first run only) takes 15-30 seconds. Subsequent runs start in 2-3 seconds.
Docker/Podman required. The container runtime must be installed on the host.
File system boundaries. The agent can only access files in the mounted workspace. If your task requires reading files outside the workspace, you need to adjust the mount.
No direct host access. The agent cannot interact with host services, databases, or tools outside the container. This is a feature for security but a limitation for some workflows.

Using Container Mode from the Dashboard

You can also enable container mode from the browser dashboard. The task runner includes a "Container Mode" checkbox and a workspace path input. When enabled, the task runs inside the container with the same hardened configuration.

The dashboard streams the container's output via SSE, just like a non-containerized task. Approvals work the same way -- the gateway inside the container communicates with the Authensor control plane, and approval requests appear in your dashboard.

Try It

bash
Run a task in a container
safeclaw run --container "analyze the codebase and create a summary"

Specify a workspace directory
safeclaw run --container --workspace /path/to/project "run the test suite"

Rebuild the container image (after updating SafeClaw)
safeclaw run --container --rebuild "check for security issues"

For more details on container isolation patterns for AI agents, see our container isolation deep-dive.