OpenClaw Architecture¶
TL;DR / when to use this: Where to host the OpenClaw gateway depends on what the agents are allowed to do. Rule of thumb: Docker for restricted/workspace-only agents, a VM for agents that need tooling or container orchestration — passing the docker sock to a containerized agent lets it run containers on the host, which is usually not what you want.
The isolation question¶
With any self-hosted tool, don't muddy the host. Agents are a different beast: they can be filesystem-restricted to a workspace, but tooling, tooling versions, and container orchestration are the real questions. Agents aren't great at maintaining software, and with multiple agents you may not want them sharing host tools.
The gateway installs via:
- Docker
- A VM (or bare metal) — a dockerized gateway inside a VM is fine
Planning for multiple agents¶
Even if one agent is enough today, plan for several. A coding agent needs CLI tooling, must run its software, and may screenshot the UI — a full-stack app needs frontend, backend, and a database. Two developers sharing a repo gets messy, so enforce separation.
Non-sandboxed agents with separate workspaces: put all developer tooling in its own container (Dockerfile installs angular cli, gradle, playwright & chromium), with the cloned repo as a volume mount. But if agents run Docker, they need a docker engine — a VM is the clean win here; a docker install requires passing the docker sock, and containers then run on the host.
Sandboxing¶
Sandboxed agents run in containers with compose-style options like custom bind mounts, common tooling preinstalled, or a browser image. Example: a personal agent plus a restricted family agent (multi-agent sandbox example).
Headless browser for sandboxed agents:
{
"browser": { "headless": true },
"agents": {
"defaults": {
"sandbox": { "browser": { "headless": true } }
}
}
}
Full example: install/docker#enable-sandboxing.