<!-- source: https://deepwiki.com/qhkm/zeptoclaw/6.5-container-isolation -->

# Container Isolation

- .github/dependabot.yml
- docs/plans/2026-02-23-linux-sandbox-runtimes-plan.md
- src/main.rs
- src/runtime/apple.rs
- src/runtime/bubblewrap.rs
- src/runtime/docker.rs
- src/runtime/factory.rs
- src/runtime/firejail.rs
- src/runtime/landlock.rs
- src/runtime/mod.rs
- src/runtime/native.rs
- src/runtime/types.rs
- src/tools/web.rs
- tests/integration.rs

## Purpose and Scope

This document provides a detailed technical overview of ZeptoClaw's container isolation backends. These runtimes provide kernel-level and userspace sandboxing for shell command execution, ensuring that autonomous agents operate within strictly defined security boundaries. ZeptoClaw supports six distinct runtime modes: Native (no isolation), Docker, Apple Container, Landlock, Firejail, and Bubblewrap.

For broader security architecture including injection detection and policy enforcement, see **6.1 Security Architecture**. For shell command validation and SSRF prevention, see **6.4 Shell Security**.

## Runtime Architecture

### The ContainerRuntime Trait

The isolation system is built around the `ContainerRuntime` trait, which abstracts the underlying sandbox mechanics from the tool execution logic. This allows the `AgentLoop` and `ToolRegistry` to execute commands without needing to know which specific isolation technology is active.

Title: Runtime Entity Relationship

```

```

**Sources:** [src/runtime/types.rs132-147](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L132-L147) [src/runtime/mod.rs1-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L1-L30) [src/runtime/factory.rs15-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L15-L103)

### Runtime Factory and Selection

Runtimes are instantiated via the `create_runtime` function in `src/runtime/factory.rs`. This factory reads the `RuntimeConfig` and initializes the requested backend, performing availability checks (e.g., verifying if the `docker` or `bwrap` binaries exist on the system path).

Title: Runtime Creation Flow

```

```

**Sources:** [src/runtime/factory.rs16-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103) [src/runtime/types.rs9-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L9-L29)

## Linux Sandbox Runtimes

ZeptoClaw provides three specialized Linux sandboxing options that leverage kernel features or existing security utilities.

### Landlock LSM

Landlock uses the Linux Security Module (LSM) API (available in kernel 5.13+) to enforce filesystem access control. Restrictions are applied in the **child process** via a `pre_exec` closure, ensuring the parent ZeptoClaw process remains unrestricted.

- Implementation : Uses the landlock crate to create a Ruleset src/runtime/landlock.rs 176-182
- Mechanism : Rules are added for read and write access to specific directories src/runtime/landlock.rs 185-191
- Safety : The pre_exec closure is marked unsafe because it runs between fork() and exec() , but it only performs async-signal-safe operations src/runtime/landlock.rs 126-132

**Sources:** [src/runtime/landlock.rs1-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L1-L15) [src/runtime/landlock.rs165-191](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L165-L191)

### Firejail

Firejail provides a sandbox using Linux namespaces and seccomp-bpf. It is a userspace utility that wraps the command execution.

- Availability : The runtime checks for the firejail binary on the system PATH src/runtime/factory.rs 122-126
- Configuration : Supports custom profiles and extra arguments through the FirejailConfig src/config/types.rs 184-192

**Sources:** [src/runtime/factory.rs108-129](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L108-L129) [src/config/types.rs184-192](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L184-L192)

### Bubblewrap (bwrap)

Bubblewrap is a lightweight, unprivileged sandbox used by projects like Flatpak. It focuses on mount namespace isolation.

- Mount Strategy : Automatically mounts /usr , /lib , /etc , and /bin as read-only, while providing writable mounts for the workspace and /tmp src/runtime/bubblewrap.rs 30-57
- Network Isolation : Can be configured via extra_args (e.g., --unshare-net ) src/runtime/bubblewrap.rs 201-207

**Sources:** [src/runtime/bubblewrap.rs1-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L1-L17) [src/runtime/bubblewrap.rs27-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L27-L66)

## Containerized Runtimes (Docker & Apple)

### Docker Runtime

The Docker backend executes commands in ephemeral containers. It is the most portable isolation method across Linux, macOS, and Windows.

- Resource Limits : Supports memory_limit , cpu_limit , and pids_limit to prevent fork bombs and resource exhaustion src/runtime/docker.rs 126-141
- Isolation : Uses the none network mode by default to prevent data exfiltration src/runtime/docker.rs 38
- Cleanup : Containers are spawned with --rm to ensure they are deleted immediately after the command finishes src/runtime/docker.rs 121

**Sources:** [src/runtime/docker.rs12-43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L12-L43) [src/runtime/docker.rs114-197](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L114-L197)

### Apple Container (macOS)

This is an experimental runtime for macOS 15+ (Sequoia) using Apple's native containerization framework.

- Warning : This implementation is based on the expected CLI for the container tool and is marked as experimental src/runtime/apple.rs 6-16
- Mechanism : Uses container run with --mount and --env flags to isolate the execution environment src/runtime/apple.rs 126-187

**Sources:** [src/runtime/apple.rs1-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L1-L35) [src/runtime/apple.rs113-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L113-L206)

## Data Flow and Execution

When a tool (like `shell` or `read_file`) requires execution, the following flow occurs:

1. Context Construction : The system creates a ContainerConfig containing the working directory, environment variables, and timeout src/runtime/types.rs 86-130
2. Execution : The active ContainerRuntime calls execute() .
3. Result Capture : The runtime returns a CommandOutput struct containing stdout , stderr , and the exit_code src/runtime/types.rs 36-43

Title: Execution Pipeline

```

```

**Sources:** [src/runtime/types.rs45-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L45-L83) [src/runtime/native.rs35-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/native.rs#L35-L67) [src/runtime/docker.rs114-197](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L114-L197)

## Summary of Configuration Options

**Sources:** [src/config/types.rs144-209](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L144-L209) [src/runtime/factory.rs15-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L15-L103)
