> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Container Isolation

> How Zeus Desktop isolates command execution using containers

## Why Container Isolation?

When an AI agent executes shell commands on your machine, it has the same file access as your user account — it can read `~/.ssh`, delete files in `~/Documents`, or modify system configs. This is unacceptable for a production tool.

Zeus solves this with **container isolation**: when you select a working directory on Desktop, all commands execute inside an isolated Linux container. The container can only see that one directory, mounted at `/workspace`. Everything else on your machine is invisible and unreachable.

## Architecture Overview

Zeus has two distinct execution environments depending on where you use it:

```
Web User (browser)                    Desktop User (Electron app)
     │                                         │
     ▼                                         ▼
sandbox_mode: "cloud"                 sandbox_mode: "local"
     │                                         │
     ▼                                         ▼
Cloud Sandbox                         Local Container
(E2B / OpenSandbox / Daytona)         (Docker / Apple Containerization)
     │                                         │
     ▼                                         ▼
Remote VM, full isolation             Local container, bind mount
Files stored remotely                 Files stay on your disk
```

The `sandbox_mode` field in the API request controls which path is taken:

| Mode    | Environment                                        | When Used                                                    |
| ------- | -------------------------------------------------- | ------------------------------------------------------------ |
| `cloud` | Remote cloud sandbox (E2B / OpenSandbox / Daytona) | Web users; default for all requests                          |
| `local` | Local container on your machine                    | Desktop users with a working directory selected              |
| `none`  | No code execution at all                           | Pure chat mode; no sandbox tools are injected into the agent |

When `sandbox_mode` is `"local"`, the cloud sandbox is completely bypassed — no remote VM is provisioned, no sandbox tools (write/read/edit/bash) are injected. Instead, the agent uses `desktop_exec` routed through a local container.

## How `local` Mode Works End-to-End

Here is the complete data flow when a Desktop user sends a message with a working directory:

```
1. User selects ~/Projects/my-app as working directory
2. Desktop renderer sets sandbox_mode = "local" + working_directory = "~/Projects/my-app"
3. Request reaches AI Backend (Python)
4. AgentService.invoke() sees sandbox_mode = "local"
   → Skips cloud sandbox tool injection
   → Injects system prompt: "You operate in /workspace, use desktop_exec"
5. LLM decides to run: desktop_exec(command="npm install")
6. Backend sends tool call via WebSocket to Desktop app
7. Desktop actions.ts receives the call with working_directory in payload
8. actions.ts detects container runtime (Apple Containerization > Docker)
9. Container is started (or reused) with bind mount:
   docker run -v ~/Projects/my-app:/workspace ...
10. Command executes inside container: docker exec <id> bash -c "npm install"
11. Output returns through WebSocket → Backend → SSE → UI
```

### System Prompt Injection

When `sandbox_mode == "local"`, the backend injects this into the agent's system prompt:

```
## Working Directory (Desktop Local Workspace)
You are operating in the user's local workspace: ~/Projects/my-app
- All commands execute inside an isolated container with this directory mounted at /workspace
- You can ONLY access files within /workspace
- Use desktop_exec for all file operations and shell commands
- Do NOT attempt to access paths outside /workspace
```

This is a **soft constraint** (the LLM follows instructions). The **hard constraint** is the container runtime itself — even if the LLM tries to access `/etc/passwd`, the container filesystem doesn't have it.

## Container Runtimes

Zeus Desktop detects runtimes at startup in priority order. The result is cached for the session.

### 1. Apple Containerization (Preferred)

Available on macOS 26+ (Tahoe) with Apple Silicon.

**How it works:**

Unlike Docker, which shares the host's Linux kernel via namespaces, Apple Containerization runs each container in its own **micro-VM** — a lightweight virtual machine with a dedicated Linux kernel, managed by Apple's Virtualization.framework.

```
┌─────────────────────────────────────────┐
│ macOS Host                              │
│                                         │
│  ┌────────────────────────────────────┐ │
│  │ micro-VM (Virtualization.framework)│ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Linux Kernel (dedicated)     │  │ │
│  │  │                              │  │ │
│  │  │ Container Process            │  │ │
│  │  │  /workspace ← virtiofs mount │  │ │
│  │  └──────────────────────────────┘  │ │
│  └────────────────────────────────────┘ │
│                                         │
│  ~/Projects/my-app ──virtiofs──┘        │
└─────────────────────────────────────────┘
```

Key characteristics:

* **Isolation**: VM-level. Even a kernel exploit inside the container cannot reach the host.
* **Directory sharing via virtiofs**: Apple's implementation of the virtio-fs protocol. The host exposes a directory to the guest VM over a virtio transport. Inside the VM, it appears as a regular mount at `/workspace`. Reads and writes are passed through in real-time, but the guest cannot navigate outside the shared directory.
* **Performance**: Near-native. virtiofs uses shared memory regions (DAX) and avoids the 9p protocol overhead that plagued early Docker for Mac file sharing.
* **Startup**: Sub-second. The micro-VM boots a minimal Linux kernel optimized for fast start.
* **OCI compatible**: Uses standard OCI container images — the same Dockerfile works for both Docker and Apple Containerization.

**Detection**: Zeus runs `container --version` with a 3-second timeout.

### 2. Docker (Fallback)

Available on macOS, Windows, and Linux. Requires Docker Desktop (or Docker Engine on Linux).

**How it works:**

Docker uses Linux namespaces and cgroups to isolate processes. On macOS, Docker Desktop runs a hidden Linux VM (using Apple Virtualization.framework under the hood), and containers run inside that shared VM.

```
┌────────────────────────────────────────────┐
│ macOS Host                                 │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │ Docker Desktop VM (shared Linux)     │  │
│  │                                      │  │
│  │  Container A     Container B         │  │
│  │  /workspace      /workspace          │  │
│  │      ↑               ↑              │  │
│  └──────│───────────────│──────────────┘  │
│         │               │                  │
│  bind mount        bind mount              │
│         │               │                  │
│  ~/Projects/a    ~/Projects/b              │
└────────────────────────────────────────────┘
```

Key characteristics:

* **Isolation**: Container-level (namespace isolation). All containers share the same Linux kernel inside Docker's VM. A kernel exploit could compromise other containers.
* **Directory sharing via bind mount**: The `-v host:container` flag maps a host directory into the container's filesystem. Docker Desktop uses virtiofs (on macOS 12.5+) or gRPC-FUSE to bridge between the macOS host and the Linux VM.
* **Performance**: Good. Bind mounts with virtiofs backend (Docker Desktop 4.15+) approach native speed. Older gRPC-FUSE backend was significantly slower for `node_modules`-heavy workloads.
* **Startup**: \~1-2 seconds for the container (the VM is already running).
* **OCI compatible**: Standard Docker images.

**Detection**: Zeus runs `docker info` with a 5-second timeout.

### 3. No Runtime Available

If neither runtime is detected, Zeus **refuses to execute** any commands when `working_directory` is set. The error message returned to the agent is:

> "No container runtime detected. Please install Docker Desktop or upgrade to macOS 26 for Apple Containerization."

This is a deliberate design choice — **there is no soft-isolation fallback**. We do not attempt to restrict paths via `cwd` or shell tricks, because those can be trivially bypassed (`cd /`, symlinks, `$HOME` expansion, etc.).

## Comparison: Apple Containerization vs Docker

| Aspect                     | Apple Containerization | Docker                      |
| -------------------------- | ---------------------- | --------------------------- |
| Isolation boundary         | VM (dedicated kernel)  | Namespace (shared kernel)   |
| Kernel exploit risk        | Contained to micro-VM  | Could affect all containers |
| Directory sharing protocol | virtiofs (native)      | virtiofs via Docker Desktop |
| macOS version required     | 26+ (Tahoe)            | 12+                         |
| Cross-platform             | Apple Silicon only     | macOS, Windows, Linux       |
| Startup time               | under 1s               | \~1-2s                      |
| Image format               | OCI                    | OCI                         |
| Runtime detection          | `container --version`  | `docker info`               |

## Container Lifecycle

Zeus manages one container per session:

1. **Start**: When the first `desktop_exec` command arrives with `working_directory`, Zeus detects the runtime, creates a container (`docker run -d` or `container run -d`), and bind-mounts the directory.
2. **Exec**: Subsequent commands are sent to the running container via `docker exec` / `container exec`.
3. **Reuse**: If a container for the session already exists and is running, it is reused.
4. **Stop**: When the session ends (or the Desktop app closes), the container is removed (`docker rm -f` / `container rm -f`).

The container runs `sleep infinity` as its entrypoint — it stays alive until explicitly stopped.

## The Sandbox Image

Both runtimes use the same OCI image: `zeus-desktop-sandbox:latest`.

Contents (defined in `apps/desktop/docker/Dockerfile`):

* **Base**: Ubuntu 22.04
* **Languages**: Python 3 + pip + venv, Node.js 22 LTS + npm + pnpm
* **Tools**: git, curl, wget, jq, build-essential (gcc, make, etc.)
* **Working directory**: `/workspace`

To build:

```bash theme={null}
# Docker
cd apps/desktop/docker
docker build -t zeus-desktop-sandbox:latest .

# Apple Containerization
cd apps/desktop/docker
container build -t zeus-desktop-sandbox:latest .
```

The image is intentionally minimal (\~300MB). Users can extend it by building their own image and changing the `IMAGE_NAME` constant in the sandbox implementation.

## Security Model Summary

Zeus applies **defense in depth** with three layers:

| Layer                   | Mechanism                                                     | Enforced By                |
| ----------------------- | ------------------------------------------------------------- | -------------------------- |
| 1. LLM instruction      | System prompt says "only access /workspace"                   | AI model compliance        |
| 2. Container filesystem | Only `/workspace` is mounted; host paths don't exist          | Container runtime (kernel) |
| 3. No fallback          | If no container runtime exists, execution is refused entirely | Application logic          |

Layer 1 alone is insufficient (LLMs can hallucinate or be jailbroken). Layer 2 provides the hard boundary. Layer 3 ensures we never degrade to an unsafe state.

## Installation Guide

### Docker Desktop

1. Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)
2. Install and start Docker Desktop
3. Verify: run `docker info` in terminal — should show server version and storage driver
4. Build the image: `docker build -t zeus-desktop-sandbox:latest apps/desktop/docker/`

### Apple Containerization (macOS 26+)

1. Upgrade to macOS 26 (Tahoe) or later
2. The `container` CLI is included with the OS (part of the Containerization framework)
3. Verify: run `container --version` in terminal
4. Build the image: `container build -t zeus-desktop-sandbox:latest apps/desktop/docker/`