1. The Core Bottleneck: What Architectural Flaw Does It Shatter?

Terminal-bound CLI coding agents have hit an engineering ceiling. The common habit of granting LLMs bare-metal shell execution across developer workstations introduces two irreconcilable trade-offs: context starvation via single-task blocking, and catastrophic exposure of the host filesystem to unverified execution. The moment a developer shuts their laptop lid, execution state collapses. Collaboration remains impossible, and integrating asynchronous workflows like webhooks requires cumbersome duct-tape scripts.

OpenHands, surpassing 90K stars, restructures its operational model with Agent Canvas. It elevates the tool from a standalone code generation runtime into a self-hosted developer control center. The fundamental breakthrough lies in the physical and architectural decoupling of the agent execution runtime from the control plane.

💡 Core Architectural Insight: Decoupling the cognitive agent plane from the execution environment via the Agent-Client Protocol (ACP) enables a unified control plane to orchestrate local processes, team-shared VMs, and multi-tenant Docker sandboxes with zero runtime lock-in.

This architecture eliminates the false dichotomy between uncontained host execution and proprietary, black-box cloud sandboxes. Engineering automations—such as issue decomposition, automated test repair, and event-driven Slack bots—run deterministically across scalable, long-lived server backends.

2. Deep Dive: Core Architecture and Component Data Flow

Agent Canvas operates across three primary layers: the frontend control plane (Static Frontend & Ingress), the routing engine (Automation Backend & Session Router), and polymorphic execution runtimes (Agent Server Sandboxes).

+-------------------------------------------------------------+
|              Agent Canvas UI / CLI / Webhook                |
+-------------------------------------------------------------+
                               │ HTTP / WebSocket
                               ▼
+-------------------------------------------------------------+
|         Ingress & Automation Gateway (Node.js / uv)         |
|   - Event Triggers (Slack / GitHub / Cron)                  |
|   - Session Manager & Agent-Client Protocol (ACP) Router    |
+-------------------------------------------------------------+
          │                           │                       │
          ▼ (Local IPC)               ▼ (Docker Socket)       ▼ (Remote mTLS)
+-------------------+   +---------------------------+   +-------------------+
| Local Agent Server|   | OH_CONVERSATION_RUNTIME   |   | Remote Cloud / VM |
| (Bare Metal / Dev)|   | - Container per Session   |   | - Shared Enterprise
| - Host FS Access  |   | - Projects Volume Mount   |   |   Infrastructure  |
+-------------------+   +---------------------------+   +-------------------+

Upon ingesting instructions, the ingress gateway avoids direct shell invocation. Instead, it routes the payload according to OH_CONVERSATION_RUNTIME. In single-container deployments, the project directory mounts directly to /projects. Under multi-container configurations, the control plane communicates with the host Docker daemon to spin up an isolated execution sandbox per conversation session.

All internal communication strictly complies with ACP specifications. Whether handling the native OpenHands engine, Claude Code, or Codex backends, payloads move through standardized event streams containing tool invocations and system states, neutralizing technical debt associated with vendor-specific SDK adaptations.

3. Technology Trade-offs and Comparative Matrix

Technical Dimension OpenHands Agent Canvas Traditional CLI (e.g., Aider) Closed Cloud Agents (e.g., Devin) Production Value
Runtime Topology Split control/execution plane; hot-swaps Local, Docker, and Remote VMs Single-process runtime tightly bound to terminal lifecycle Proprietary hosted runtime; black-box infrastructure Background task survivability independent of developer workstations
Isolation Security Multi-container Docker isolation with granular mount points Zero containment; direct access to host shell and storage Cloud-isolated, but source code leaves enterprise perimeter Zero risk of host corruption; guarantees compliance and IP privacy
Protocol Interop Standardized ACP layer; supports Claude Code, Codex, and custom backends Proprietary script binding; hardwired execution loops Proprietary APIs; locked model and agent topologies Zero vendor lock-in; swappable models and execution sandboxes
Automation Flow Native webhook triggers for GitHub, Slack, Linear, and Cron jobs Manual invocation only; requires custom bash orchestrators Turnkey automations limited by strict SaaS quotas and pricing Reliable unattended pipelines for bug triage and PR analysis

OpenHands prioritizes distributed systems infrastructure over quick-and-dirty CLI wrappers. While requiring dependencies such as Node.js 24 and the Docker engine, this approach provides stability, predictable failure domains, and horizontal scalability.

4. Hands-on Engineering: Constructing the Minimal Stack

This guide demonstrates spinning up Agent Canvas on Linux/macOS with session-level Docker isolation enabled.

Step 1: Verification and CLI Installation

Ensure Node.js 24+, uv, and an active Docker daemon are present on the host system.

# Verify Node.js runtime compatibility (must be >= 24)
node -v

# Ensure non-root access to the Docker daemon
docker ps

# Globally register the Agent Canvas CLI orchestrator
npm install -g @openhands/agent-canvas

Step 2: Bootstrapping Multi-Sandbox Mode

Initialize the workspace directory and execute the runtime orchestrator:

#!/usr/bin/env bash
# Configure workspace volume mounted to internal agents
export PROJECTS_PATH="$HOME/dev_workspaces"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

# Enforce Docker container isolation per conversation thread
# Spawns host control plane while dynamic sandboxes handle execution
OH_CONVERSATION_RUNTIME=docker \
PROJECTS_PATH="$PROJECTS_PATH" \
agent-canvas

Step 3: Verifying Control Plane & Sandbox Lifecycles

Verify that the service ingress is operational and inspect container allocation:

# Probe Gateway Health status
curl -s -o /dev/null -w "Ingress Status: %{http_code}\n" http://localhost:8000

# Inspect ephemeral containers spawned on demand per conversation
docker ps --filter "ancestor=ghcr.io/openhands/agent-canvas:1.24.0"

Expected output:

Ingress Status: 200
CONTAINER ID   IMAGE                                     COMMAND                  CREATED         STATUS         PORTS
4c8e71fa08d3   ghcr.io/openhands/agent-canvas:1.24.0   "./entrypoint.sh ..."    5 seconds ago   Up 4 seconds   127.0.0.1:32768->8000/tcp

5. Production Hardening and Gotchas

Deploying Agent Canvas within continuous integration or enterprise environments requires addressing several platform-level pitfalls:

⚠️ Gotcha Warning [Docker-in-Docker Socket Exploitation]: Running OH_CONVERSATION_RUNTIME=docker inside an already-containerized control plane by mounting /var/run/docker.sock exposes the host daemon to container escape vectors. Autonomous agent logic could gain root control over the host engine. Production deployments should isolate the daemon via rootless Docker or enforce strict AppArmor profiles.

⚠️ Gotcha Warning [POSIX Permissions Collision on Mounted Volumes]: If the sandboxed agent processes operate under non-root UIDs, host volumes mounted under PROJECTS_PATH can trigger Permission Denied failures during file write operations. Set chmod -R 775 $PROJECTS_PATH prior to mounting, or match the internal container runtime UID/GID to the host user via deployment manifests.

⚠️ Gotcha Warning [Resource Exhaustion via Unbounded Concurrent Sessions]: Spawning dedicated containers per session consumes memory overhead and local disk cache rapidly. In teams running concurrent agent sessions, enforce explicit memory constraints (e.g., --memory=4g) on the Docker daemon and schedule automated cron jobs to purge dangling volumes and exited containers.