<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3.6-runtime-isolation -->

# Runtime Isolation

- src/config/mod.rs
- src/config/types.rs
- 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

This page documents ZeptoClaw's runtime isolation system, which provides configurable sandboxing for shell command execution. Runtime isolation wraps tool executions (particularly the `shell` tool) in various container/sandbox environments to enforce security boundaries and limit blast radius from malicious or buggy commands.

**Scope:** This page covers the `ContainerRuntime` trait, the six available runtime implementations, their configuration, and how they integrate with the tool execution pipeline. For tool-level security controls (approval gates, policy engine), see [6.3. Agent Mode Policies](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.3. Agent Mode Policies) For Docker deployment of the entire gateway, see [12.2. Docker Deployment](https://github.com/qhkm/zeptoclaw/blob/2c743d31/12.2. Docker Deployment)

## Architecture Overview

ZeptoClaw's runtime isolation system is based on the `ContainerRuntime` trait, which abstracts command execution across six different backends. Each runtime provides a different trade-off between isolation strength, platform compatibility, and overhead.

### Runtime Trait Design

The "Code Entity Space" for runtimes is centered around the `ContainerRuntime` trait and the `factory` which instantiates them based on `RuntimeConfig`.

```
subgraph "Tool Execution Layer"
    ShellTool["ShellTool [src/tools/shell.rs]"]
    BinaryPluginTool["BinaryPluginTool [src/plugins/mod.rs]"]
end

subgraph "Runtime Abstraction [src/runtime/types.rs]"
    ContainerRuntime["<<trait>>\nContainerRuntime"]
    ContainerRuntime -->|defines| execute["execute(command, config)"]
    ContainerRuntime -->|defines| is_available["is_available()"]
end

subgraph "Runtime Factory [src/runtime/factory.rs]"
    create_runtime["create_runtime(config)"]
end

subgraph "Implementations"
    NativeRuntime["NativeRuntime\n[src/runtime/native.rs]"]
    DockerRuntime["DockerRuntime\n[src/runtime/docker.rs]"]
    AppleRuntime["AppleContainerRuntime\n[src/runtime/apple.rs]"]
    LandlockRuntime["LandlockRuntime\n[src/runtime/landlock.rs]"]
    FirejailRuntime["FirejailRuntime\n[src/runtime/firejail.rs]"]
    BubblewrapRuntime["BubblewrapRuntime\n[src/runtime/bubblewrap.rs]"]
end

ShellTool --> create_runtime
create_runtime --> ContainerRuntime

ContainerRuntime <|-- NativeRuntime
ContainerRuntime <|-- DockerRuntime
ContainerRuntime <|-- AppleRuntime
ContainerRuntime <|-- LandlockRuntime
ContainerRuntime <|-- FirejailRuntime
ContainerRuntime <|-- BubblewrapRuntime
```

```|
Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L1-L30" min=1 max=30 file-path="src/runtime/mod.rs">Hii</FileRef> <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L132-L147" min=132 max=147 file-path="src/runtime/types.rs">Hii</FileRef> <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103" min=16 max=103 file-path="src/runtime/factory.rs">Hii</FileRef>

The `ContainerRuntime` trait defines three key methods:
- `fn name(&self) -> &str`: Returns the runtime identifier (e.g., "docker", "landlock") <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L136-L136" min=136  file-path="src/runtime/types.rs">Hii</FileRef>
- `async fn is_available(&self) -> bool`: Checks if the platform supports the runtime and if necessary binaries/features are present <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L139-L139" min=139  file-path="src/runtime/types.rs">Hii</FileRef>
- `async fn execute(&self, command: &str, config: &ContainerConfig) -> RuntimeResult<CommandOutput>`: Performs the actual sandboxed execution <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L142-L146" min=142 max=146 file-path="src/runtime/types.rs">Hii</FileRef>

---

## Runtime Selection and Initialization

Runtimes are created via the `create_runtime` function in `src/runtime/factory.rs`. This function maps `RuntimeType` configuration to specific implementation instances.

| Diagram: Runtime Initialization Flow |
| :--- |
| ```mermaid
flowchart TD
    Config["RuntimeConfig [src/config/types.rs]"] --> Factory["create_runtime() [src/runtime/factory.rs]"]
    Factory --> TypeCheck{"match runtime_type"}
    
    TypeCheck -->|Native| Native["NativeRuntime::new()"]
    TypeCheck -->|Docker| Docker["DockerRuntime::new()"]
    TypeCheck -->|Landlock| Landlock["LandlockRuntime::new()"]
    TypeCheck -->|Firejail| Firejail["FirejailRuntime::new()"]
    TypeCheck -->|Bubblewrap| Bubblewrap["BubblewrapRuntime::new()"]
    TypeCheck -->|Apple| Apple["AppleContainerRuntime::new()"]

    Docker --> Avail{"is_available()"}
    Avail -->|No| Err["Return RuntimeError::NotAvailable"]
    Avail -->|Yes| Success["Return Arc<dyn ContainerRuntime>"]
``` |
Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103" min=16 max=103 file-path="src/runtime/factory.rs">Hii</FileRef> <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L9-L29" min=9 max=29 file-path="src/runtime/types.rs">Hii</FileRef> <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L75-L76" min=75 max=76 file-path="src/config/types.rs">Hii</FileRef>

---

## Native Runtime

The `NativeRuntime` provides no isolation and executes commands directly on the host system using `tokio::process::Command` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/native.rs#L15-L40" min=15 max=40 file-path="src/runtime/native.rs">Hii</FileRef>

- **Platform**: Cross-platform (Linux, macOS, Windows).
- **Security Boundary**: None. Runs with the same permissions as the ZeptoClaw process.
- **Implementation**: Uses `sh -c` to execute the provided command string <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/native.rs#L40-L41" min=40 max=41 file-path="src/runtime/native.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/native.rs#L1-L68" min=1 max=68 file-path="src/runtime/native.rs">Hii</FileRef>

---

## Docker Runtime

`DockerRuntime` executes commands inside ephemeral Docker containers. It supports resource limits (CPU, Memory, PIDs) and network isolation <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L14-L29" min=14 max=29 file-path="src/runtime/docker.rs">Hii</FileRef>

- **Isolation Strategy**: Ephemeral containers created via `docker run --rm` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L120-L121" min=120 max=121 file-path="src/runtime/docker.rs">Hii</FileRef>
- **Default Network**: `none` (isolated from network by default) <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L38-L38" min=38  file-path="src/runtime/docker.rs">Hii</FileRef>
- **Resource Limits**: Configurable memory (default 512m), CPU (default 1.0), and PIDs (default 100) <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L36-L41" min=36 max=41 file-path="src/runtime/docker.rs">Hii</FileRef>
- **Data Flow**: Host directories are bind-mounted into the container based on `ContainerConfig.mounts` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L149-L161" min=149 max=161 file-path="src/runtime/docker.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L31-L198" min=31 max=198 file-path="src/runtime/docker.rs">Hii</FileRef>

---

## Linux Sandbox Runtimes

ZeptoClaw leverages Linux-specific kernel features for lightweight isolation without the overhead of full container engines.

### Landlock Runtime
`LandlockRuntime` uses the Linux Landlock LSM to restrict filesystem access. Rules are applied in the child process using `pre_exec` to ensure the parent ZeptoClaw process remains unrestricted <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L7-L14" min=7 max=14 file-path="src/runtime/landlock.rs">Hii</FileRef>

- **Mechanism**: Kernel-level filesystem ACLs <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L158-L190" min=158 max=190 file-path="src/runtime/landlock.rs">Hii</FileRef>
- **Implementation**: Uses `landlock` crate to create a ruleset and `ruleset.restrict_self()` in a `pre_exec` closure <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L114-L127" min=114 max=127 file-path="src/runtime/landlock.rs">Hii</FileRef>
- **Graceful Degradation**: If the kernel doesn't support Landlock, it degrades to a warning <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L5-L6" min=5 max=6 file-path="src/runtime/landlock.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/landlock.rs#L23-L151" min=23 max=151 file-path="src/runtime/landlock.rs">Hii</FileRef>

### Firejail Runtime
`FirejailRuntime` wraps commands with the `firejail` binary, utilizing namespaces and seccomp <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/firejail.rs#L1-L4" min=1 max=4 file-path="src/runtime/firejail.rs">Hii</FileRef>

- **Command Structure**: `firejail [--profile=...] [extra_args] -- sh -c <command>` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/firejail.rs#L15-L15" min=15  file-path="src/runtime/firejail.rs">Hii</FileRef>
- **Configuration**: Supports custom profiles or `--noprofile` mode <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/firejail.rs#L43-L46" min=43 max=46 file-path="src/runtime/firejail.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/firejail.rs#L19-L134" min=19 max=134 file-path="src/runtime/firejail.rs">Hii</FileRef>

### Bubblewrap Runtime
`BubblewrapRuntime` (bwrap) is an OCI-compatible sandbox that creates new namespaces and explicit bind mounts <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L1-L5" min=1 max=5 file-path="src/runtime/bubblewrap.rs">Hii</FileRef>

- **Mounts**: Explicitly binds `/usr`, `/lib`, etc. as read-only, and the workspace as read-write <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L27-L56" min=27 max=56 file-path="src/runtime/bubblewrap.rs">Hii</FileRef>
- **Arguments**: Constructs a complex argument list including `--ro-bind`, `--proc`, `--dev`, and `--bind` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L30-L65" min=30 max=65 file-path="src/runtime/bubblewrap.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/bubblewrap.rs#L15-L141" min=15 max=141 file-path="src/runtime/bubblewrap.rs">Hii</FileRef>

---

## Apple Container Runtime (macOS)

`AppleContainerRuntime` is an **experimental** implementation for macOS 15+ (Sequoia) using Apple's native containerization framework <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L6-L16" min=6 max=16 file-path="src/runtime/apple.rs">Hii</FileRef>

- **Availability**: Checks for the `container` binary and validates CLI syntax compatibility with `container run --help` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L70-L111" min=70 max=111 file-path="src/runtime/apple.rs">Hii</FileRef>
- **Mechanism**: Translates `ContainerConfig` into `container run` arguments, including `--mount` specs for bind mounts <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L126-L188" min=126 max=188 file-path="src/runtime/apple.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L35-L206" min=35 max=206 file-path="src/runtime/apple.rs">Hii</FileRef>

---

## Data Structures and Flow

The `ContainerConfig` struct is the primary vehicle for passing execution context from tools to runtimes.

| Field | Type | Description |
| :--- | :--- | :--- |
| `workdir` | `Option<PathBuf>` | The working directory inside the isolated environment <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L89-L89" min=89  file-path="src/runtime/types.rs">Hii</FileRef> |
| `mounts` | `Vec<(PathBuf, PathBuf, bool)>` | Host path, Container path, and Read-only flag <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L91-L91" min=91  file-path="src/runtime/types.rs">Hii</FileRef> |
| `env` | `Vec<(String, String)>` | Environment variables to inject <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L93-L93" min=93  file-path="src/runtime/types.rs">Hii</FileRef> |
| `timeout_secs` | `u64` | Execution timeout (default 60s) <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L95-L95" min=95  file-path="src/runtime/types.rs">Hii</FileRef> |

Execution results are returned as a `CommandOutput` containing captured `stdout`, `stderr`, and the `exit_code` <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L36-L43" min=36 max=43 file-path="src/runtime/types.rs">Hii</FileRef>

Sources: <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L86-L130" min=86 max=130 file-path="src/runtime/types.rs">Hii</FileRef> <FileRef file-url="https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L35-L83" min=35 max=83 file-path="src/runtime/types.rs">Hii</FileRef>
```
