docs: document how to let the agent use Docker in Agent Canvas

[simonrosenberg]

Why

The Agent Canvas image ships Docker, but the agent cannot use it as documented — the
docker run in our Docker backend guide grants no privilege, so dockerd fails:

failed to start daemon: Error initializing network controller:
error creating default "bridge" network: operation not permitted

It does work if the user adds --privileged (verified against published
latest-python: daemon 29.7.2 starts normally). But nothing told them that. The only
writeup is enterprise/docker-in-sandbox.mdx, where a self-hoster would not look, and no
Canvas page mentioned --privileged at all.

So a genuinely useful capability — build a Dockerfile and run it to prove the change
works, bring up a docker compose stack to reproduce a bug, use an image-only toolchain
— was reachable only by users who worked it out themselves.

What this adds

openhands/usage/agent-canvas/backend-setup/docker.mdx — a "Let the Agent Use
Docker" section covering:

• what the capability is for, and what the agent can't do without it
• that it needs --privileged, with a complete docker run
• a <Warning> on the isolation cost, since this is a real security tradeoff on the
  user's own machine
• a <Note> explaining that no safer middle ground exists, and pointing at how
  Enterprise does it unprivileged

enterprise/docker-in-sandbox.mdx — a reverse <Note> for readers who land there
while self-hosting Canvas.

On "no safer middle ground"

Stated in the docs because it is the obvious next question, and it is measured rather
than assumed:

• Rootless Docker with seccomp=unconfined, apparmor=unconfined, --device /dev/fuse
  and --device /dev/net/tun gets the daemon fully up ("Daemon has completed
  initialization", server 29.7.2) — but containers it creates then fail with
  error mounting "proc" to rootfs: operation not permitted.
• Same wall with rootless BuildKit, and identically under BuildKit and the legacy
  builder, with both overlayfs and vfs storage drivers.
• runc needs CAP_SYS_ADMIN to mount /proc, and privilege is granted by the host at
  container start — it cannot be acquired later. That is what the Enterprise hardened
  runtime provides at host level, and it is not something an image can ship.

Caveat worth knowing: these were run on Docker Desktop for macOS, where the outer
container already sits in a VM. On a native Linux host with unprivileged user namespaces
enabled, rootless may get further. The docs therefore describe --privileged as the
supported path rather than claiming rootless is impossible everywhere.

How to Test

# Renders correctly and links resolve
npm i && npx mint dev     # or the repo's usual preview command

# The behaviour the docs describe
docker run -d --name c -p 8000:8000 ghcr.io/openhands/agent-canvas:latest
docker exec c sh -c 'dockerd 2>&1 | tail -2'      # fails: bridge network not permitted
docker rm -f c

docker run -d --name c --privileged -p 8000:8000 ghcr.io/openhands/agent-canvas:latest
docker exec c sh -c 'dockerd >/tmp/d.log 2>&1 & sleep 10; docker info >/dev/null && echo OK'
docker rm -f c

Check both new cross-links resolve in the preview — the Canvas anchor
(#let-the-agent-use-docker) and the Enterprise page link.

Issue Number

Relates to OpenHands/software-agent-sdk#4643

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Sep 1, 2026, 3:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[enyst]

Thank you!