Determining how to host OpenClaw¶
OpenClaw Gateway¶
It's important to talk about goals and the objectives of our agents as well, what level of isolation do they need. With any self hosted tool, we don't want to muddy our host. Many tools we can run just fine in docker. Other tools may need to actually orchestrate additional containers of have software installed on the host. These types of tools we tend to prefer running in a proxmox VM where they are free to do so. Home Assistant OS is one example where it's simply smoother to run this in a VM.
OpenClaw is a whole other beast though because now we're talking about agents. Agents can be restricted on the filesystem to workspace, that's great, but what about tooling, what about versioning of tooling. What about potential container orchestration or developing software. Again, we're trying to not pollute the host in any way. Agents aren't particularly great in maintaining software and if we have multiple agents, we may not want them accessing tools from the host.
The Gateway can be installed via
- Docker
- A VM (or bare metal)
- (Can still use a dockerized gateway within a VM)
Let's consider what we may want our agents to do, and even if one agent is sufficient, we should plan our architecture for the event that we want multiple agents.
A coding agent for example may need tooling, it needs to develop software with cli tools, run the software, and perhaps even take screen shots of what it looks like in development. For a full stack application, it may need to run the front end, back end, and a database. If we had two developers that need access to a repo, it could be messy, so we want to ensure good separation between the agents. Does that mean they can't run on the same server? Not necessarily.
Let's first consider multiple agents not running in a sandbox, they each just have their own workspace of file system. If our software development architecture is planned well, all of our developer tooling can be in its own docker container itself, with the clone repo as a volume mount. The Dockerfile for this image can ensure all tooling is needed (angular cli, gradle, playwright & chromium). Ok, but if they are going to run docker, then they need access to a docker engine. This is possible with a VM installation, of course. With a docker installation, we'd need to pass the docker sock and then they'd be able to create docker containers, which run on the host, and this may not be what we want. In this scenario, a VM seems like a win.
Sandboxing¶
When agents are sandboxed, they can run in docker containers, and we can specify something somethings that we might dow with a normal compose file, like (https://docs.openclaw.ai/gateway/sandboxing#custom-bind-mounts)[Bind Mounts]. The sandboxes can also be set up with common tooling installed, or a browser image.
An example of a personal agent and a restricted family agent: https://docs.openclaw.ai/tools/multi-agent-sandbox-tools#example-1-personal-+-restricted-family-agent
Sandboxed agents can use host tools such as a (https://docs.openclaw.ai/help/faq#can-the-openclaw-browser-run-headless)[headless browser]
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
Here's a (https://docs.openclaw.ai/install/docker#enable-sandboxing)[full example],
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared (agent is default)
workspaceAccess: "none", // none | ro | rw
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256,
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "openclaw-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"],
},
prune: {
idleHours: 24, // 0 disables idle pruning
maxAgeDays: 7, // 0 disables max-age pruning
},
},
},
},
tools: {
sandbox: {
tools: {
allow: [
"exec",
"process",
"read",
"write",
"edit",
"sessions_list",
"sessions_history",
"sessions_send",
"sessions_spawn",
"session_status",
],
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
},
},
},
}
An important note is that for that setup command with the apt-get installation, the user must be root. I'm not sure if that means that in this example it wouldn't actually have permission to work as intended.
Note that we need to actually build the container ourselves, and then the agent can use that container. i.e.
There are a couple setup scripts for images that can be used by agents: sandbox-setup.sh, sandbox-browser-setup.sh, sandbox-common-setup.sh for example. These utilize the other Dockerfiles, i.e. Dockerfile.sandbox-browser and Dockerfile.sandbox-common. Or you can create your own image with all the tooling that you'd want in the image. i.e. this could be the tooling Dockerfile of a repo.
Docker¶
When installing from docker, a setup script can be run which runs a cli tool that generates some of our config and .env variables. We can build the project from the provided Dockerfile, or from prebuilt images. See https://docs.openclaw.ai/install/docker#docker.
Previously, when I wanted to install extra packages, I did so in the Dockerfile, but this isn't a very good long term solutions. Instead, you should use the variables to (export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential" ./docker-setup.sh)[Install extra apt packages]