Skip to main content
Use per-conversation Docker mode when you want Agent Canvas and the outer Agent Server to remain trusted host processes while each conversation runs in a separate, hardened Docker container. This mode differs from running the entire Agent Canvas distribution in Docker. Here, only conversations run in containers; Agent Canvas and the outer Agent Server stay on the host.

​
Prerequisites

  • Docker installed and running on the Agent Server host
  • Permission for the user running agent-canvas to invoke Docker
  • An Agent Server image compatible with the installed Agent Server version

​
Start Agent Canvas

Set the conversation runtime and image before starting Agent Canvas:
You can combine these variables with other launcher options. For example, to use another port:
The launcher forwards the variables to the local Agent Server. No separate frontend configuration is required.

​
How Isolation Works

For each conversation, the outer Agent Server starts a dedicated Docker container running a full Agent Server. The container starts lazily when the conversation first needs it.
  • The inner server runs with OH_CONVERSATION_RUNTIME=local, so it runs the agent loop and its own tools inside the container.
  • Each container has its own generated OH_SECRET_KEY, its own session API key, and its own persistence.
  • The outer Agent Server proxies and mediates conversation requests to the container, and resolves agent and profile settings before forwarding them.
The container is hardened as follows:
  • Runs as the host user’s UID and GID rather than root.
  • Drops all Linux capabilities (--cap-drop ALL) and sets no-new-privileges.
  • Publishes its API only on 127.0.0.1, authenticated with the per-conversation session API key.
  • Maps host.docker.internal to the host gateway.
  • Is limited by the memory, CPU, and PID settings in the configuration reference.

​
Workspace and Persistence

Each container bind-mounts three host directories: Because these are bind mounts, workspace files and conversation history persist after the container is removed. Conversations that share a host workspace share the same files.
The /workspace mount gives tools in the container read and write access to that host directory. Point conversations at a dedicated workspace if you do not want the agent to modify existing project files.
Containers are stopped when a conversation has been idle for the idle timeout (OH_CONVERSATION_IDLE_TTL_SECONDS, 20 minutes by default). The conversation is not lost; its container is started again on next use. Stale containers from a previous Agent Server run are removed when the server starts.

​
Verify Isolation

Create a new conversation and ask the agent to run:
The command should report /workspace as PWD, and a HOME of /var/openhands/.openhands rather than your host home directory. On the host, inspect the active conversation container:
The mounts output should list three bind mounts, with destinations /var/openhands/conversations/<id>, /var/openhands/.openhands, and /workspace. To check the other settings:

​
Configuration Reference