<!-- source: https://deepwiki.com/qhkm/zeptoclaw/12.3-container-gateway-mode -->

# Container Gateway Mode

- src/gateway/container_agent.rs
- src/gateway/ipc.rs
- src/gateway/mod.rs
- src/main.rs
- src/runtime/apple.rs
- src/runtime/docker.rs
- src/runtime/factory.rs
- src/runtime/mod.rs
- src/runtime/native.rs
- src/runtime/types.rs
- tests/integration.rs

Container Gateway Mode provides full request-level isolation for multi-tenant ZeptoClaw deployments by spawning a containerized agent process for each incoming message. This mode is designed for scenarios where you need strong isolation boundaries between different users or channels, preventing potential cross-contamination of state, credentials, or session data.

For general gateway setup without containerization, see [Gateway Service](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Gateway Service) For multi-tenant configuration patterns, see [Multi-tenant Configuration](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Multi-tenant Configuration)

## Overview

Container Gateway Mode executes each agent request in a separate container instance (Docker or Apple Container), with the gateway process acting as a coordinator that:

- Receives messages from communication channels via the MessageBus src/gateway/container_agent.rs 189-191
- Serializes concurrent requests from the same session using per-session locks src/gateway/container_agent.rs 222-225
- Spawns isolated containers up to a configurable concurrency limit via a Semaphore src/gateway/container_agent.rs 142
- Communicates with containerized agents via stdin/stdout IPC using AgentRequest and AgentResponse src/gateway/ipc.rs 48-85
- Persists session snapshots across container invocations using SessionManager src/gateway/container_agent.rs 260-265
- Enforces timeouts and resource limits per container src/gateway/container_agent.rs 372-385

This architecture enables running multiple isolated tenants, providing security isolation equivalent to separate OS-level processes.

**Sources:** [src/gateway/container_agent.rs1-180](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L1-L180) [src/gateway/mod.rs1-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/mod.rs#L1-L17) [src/gateway/ipc.rs1-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/ipc.rs#L1-L42)

## Architecture

### Core Components

The `ContainerAgentProxy` is the central entity managing the lifecycle of containerized agents. It resolves the available backend (`Docker` or `Apple`) and dispatches incoming `InboundMessage` objects to freshly spawned containers.

#### Component Interaction Diagram

```

```

**Key Types:**

**Sources:** [src/gateway/container_agent.rs40-88](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L40-L88) [src/gateway/ipc.rs17-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/ipc.rs#L17-L85) [src/gateway/mod.rs7-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/mod.rs#L7-L24)

## Request Processing Flow

The processing flow ensures that every message is handled in a clean environment, with session state passed in and out via the IPC protocol.

```

```

### Concurrency Control

The gateway uses an `Arc<Semaphore>` to limit concurrent container executions [src/gateway/container_agent.rs142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L142-L142) The limit is defined by `container_agent.max_concurrent` (default: 5) [src/gateway/container_agent.rs95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L95-L95) If the limit is reached, `consume_inbound` tasks will block at the semaphore until a running container finishes and releases its permit.

**Sources:** [src/gateway/container_agent.rs92-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L92-L105) [src/gateway/container_agent.rs142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L142-L142) [src/gateway/container_agent.rs195-245](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L195-L245)

## Runtime Backend Implementations

ZeptoClaw uses a factory pattern to instantiate the appropriate `ContainerRuntime` based on configuration [src/runtime/factory.rs16-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103)

### Docker Runtime

The `DockerRuntime` executes commands using the `docker run --rm` pattern [src/runtime/docker.rs120-121](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L120-L121)

- Resource Limits: Supports memory limits, CPU limits, and PID limits to prevent fork bombs src/runtime/docker.rs 127-138
- Isolation: Uses network: none by default to prevent lateral movement src/runtime/docker.rs 38
- Mounts: Supports host-to-container bind mounts with optional read-only flags src/runtime/docker.rs 149-161

### Apple Container Runtime (macOS 15+)

The `AppleContainerRuntime` provides native isolation on macOS using Apple's `container` utility [src/runtime/apple.rs28-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L28-L29)

- Syntax: Uses container run with --mount and --env flags src/runtime/apple.rs 126-187
- Experimental Status: This runtime is currently marked as experimental and requires allow_experimental: true in the configuration src/runtime/factory.rs 55-60

### Other Runtimes

On Linux, ZeptoClaw also supports `Landlock`, `Firejail`, and `Bubblewrap` for non-Docker isolation [src/runtime/mod.rs8-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L8-L10) These are managed through the `create_runtime` factory [src/runtime/factory.rs91-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L91-L103)

**Sources:** [src/runtime/docker.rs14-88](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L14-L88) [src/runtime/apple.rs36-62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L36-L62) [src/runtime/factory.rs16-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103) [src/runtime/mod.rs1-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L1-L30)

## IPC Protocol

Communication between the Gateway and the containerized agent uses a specific protocol over standard I/O streams.

### Code Entity to System Protocol Mapping

```

```

### Protocol Markers

To distinguish agent results from general log output, the protocol uses explicit markers:

- RESPONSE_START_MARKER : <<<AGENT_RESPONSE_START>>> src/gateway/ipc.rs 38
- RESPONSE_END_MARKER : <<<AGENT_RESPONSE_END>>> src/gateway/ipc.rs 41

The `parse_marked_response` function searches for these markers in the stdout buffer to extract the `AgentResponse` JSON [src/gateway/ipc.rs151-157](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/ipc.rs#L151-L157)

### Data Structures

- AgentRequest: Contains InboundMessage , AgentDefaults , and the current Session snapshot src/gateway/ipc.rs 48-57
- AgentResponse: Contains the AgentResult (Success or Error) and a UsageSnapshot src/gateway/ipc.rs 76-85
- UsageSnapshot: Tracks input_tokens , output_tokens , tool_calls , and errors occurring within the container src/gateway/ipc.rs 18-23

**Sources:** [src/gateway/ipc.rs1-157](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/ipc.rs#L1-L157) [src/gateway/container_agent.rs346-405](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/container_agent.rs#L346-L405)

## Security Features

### Isolation and Resource Limits

The `ContainerAgentProxy` and the underlying runtimes enforce several layers of security:

1. Filesystem Isolation: Containers only see the specific directories mounted to them.
2. Resource Constraints: CPU and memory limits are applied via the backend (e.g., --memory 512m for Docker) src/runtime/docker.rs 36
3. Network Isolation: Runtimes can be configured with specific network modes (e.g., none ) src/runtime/docker.rs 38
4. Timeouts: Every container invocation is wrapped in a tokio::time::timeout src/runtime/native.rs 57-59 If the agent does not respond within timeout_secs , the process is killed src/runtime/types.rs 22-24

### Mount Validation

Before spawning a container, the system validates extra mounts against an allowlist and blocks sensitive host paths (like SSH keys or credentials) to prevent data leakage [src/runtime/factory.rs20-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L20-L22)

**Sources:** [src/runtime/types.rs8-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/types.rs#L8-L29) [src/runtime/docker.rs114-197](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/docker.rs#L114-L197) [src/runtime/factory.rs20-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L20-L22)
