Skip to main content

​
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:
ModeEnvironmentWhen Used
cloudRemote cloud sandbox (E2B / OpenSandbox / Daytona)Web users; default for all requests
localLocal container on your machineDesktop users with a working directory selected
noneNo code execution at allPure 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

AspectApple ContainerizationDocker
Isolation boundaryVM (dedicated kernel)Namespace (shared kernel)
Kernel exploit riskContained to micro-VMCould affect all containers
Directory sharing protocolvirtiofs (native)virtiofs via Docker Desktop
macOS version required26+ (Tahoe)12+
Cross-platformApple Silicon onlymacOS, Windows, Linux
Startup timeunder 1s~1-2s
Image formatOCIOCI
Runtime detectioncontainer --versiondocker 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: 
# 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:
LayerMechanismEnforced By
1. LLM instructionSystem prompt says “only access /workspace”AI model compliance
2. Container filesystemOnly /workspace is mounted; host paths don’t existContainer runtime (kernel)
3. No fallbackIf no container runtime exists, execution is refused entirelyApplication 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
  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/