- Updating this Diagram
-
- We maintain architecture diagrams inline with Mermaid in this MDX.
+- An [OpenHands Cloud](https://app.all-hands.dev) account
+- Agent Canvas installed — see [Setup](/openhands/usage/agent-canvas/setup)
- Guidance:
- - Edit the Mermaid blocks directly (flowchart/classDiagram).
- - Quote labels and edge text for GitHub preview compatibility.
- - Keep relationships concise and reflect stable abstractions (agents, runtime client/server, plugins).
- - Verify accuracy against code:
- - openhands/runtime/impl/action_execution/action_execution_client.py
- - openhands/runtime/impl/docker/docker_runtime.py
- - openhands/runtime/impl/local/local_runtime.py
- - openhands/runtime/action_execution_server.py
- - openhands/runtime/plugins/*
- - Build docs locally or view on GitHub to confirm diagrams render.
+## Add a Cloud Backend
-
-
+1. Open Agent Canvas and click the backend switcher in the top bar.
+2. Choose **Manage Backends** → **Add Backend**.
+3. Click **Login with OpenHands Cloud** and sign in with your account.
-### Runtime Architecture
-Source: https://docs.openhands.dev/openhands/usage/architecture/runtime.md
+Once connected, select it as the active backend. Conversations will now run in OpenHands Cloud.
-The OpenHands Docker Runtime is the core component that enables secure and flexible execution of AI agent's action.
-It creates a sandboxed environment using Docker, where arbitrary code can be run safely without risking the host system.
+### OpenHands Enterprise
-## Why do we need a sandboxed runtime?
+If your organization runs OpenHands Enterprise, click **Advanced** in the Add Backend flow and enter your enterprise host URL before signing in.
-OpenHands needs to execute arbitrary code in a secure, isolated environment for several reasons:
+## What's Different with a Cloud Backend
-1. Security: Executing untrusted code can pose significant risks to the host system. A sandboxed environment prevents malicious code from accessing or modifying the host system's resources
-2. Consistency: A sandboxed environment ensures that code execution is consistent across different machines and setups, eliminating "it works on my machine" issues
-3. Resource Control: Sandboxing allows for better control over resource allocation and usage, preventing runaway processes from affecting the host system
-4. Isolation: Different projects or users can work in isolated environments without interfering with each other or the host system
-5. Reproducibility: Sandboxed environments make it easier to reproduce bugs and issues, as the execution environment is consistent and controllable
+- **Sandboxed execution** — each conversation runs in an isolated cloud sandbox rather than on your host filesystem.
+- **Cloud integrations** — GitHub, GitLab, Bitbucket, Slack, and other integrations configured in OpenHands Cloud are available.
+- **Settings are per-backend** — LLM configuration, secrets, and MCP servers saved against the Cloud backend are independent from your local backend settings.
-## How does the Runtime work?
+## Related Guides
-The OpenHands Runtime system uses a client-server architecture implemented with Docker containers. Here's an overview of how it works:
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud)
+- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local)
-```mermaid
-graph TD
- A[User-provided Custom Docker Image] --> B[OpenHands Backend]
- B -->|Builds| C[OH Runtime Image]
- C -->|Launches| D[Action Executor]
- D -->|Initializes| E[Browser]
- D -->|Initializes| F[Bash Shell]
- D -->|Initializes| G[Plugins]
- G -->|Initializes| L[Jupyter Server]
+### Docker Backend
+Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/docker.md
- B -->|Spawn| H[Agent]
- B -->|Spawn| I[EventStream]
- I <--->|Execute Action to
- Get Observation
- via REST API
- | D
+The official Docker image packages the full Agent Canvas stack — backend and frontend — in a single container. The agent runs inside the container rather than directly on your host, giving you a sandboxed environment out of the box.
- H -->|Generate Action| I
- I -->|Obtain Observation| H
+## Prerequisites
- subgraph "Docker Container"
- D
- E
- F
- G
- L
- end
-```
+- [Docker](https://docs.docker.com/get-docker/) installed and running (Docker Desktop on macOS/Windows, or Docker Engine on Linux)
+- Agent Canvas installed locally (if connecting from another instance) — see [Setup](/openhands/usage/agent-canvas/setup)
-1. User Input: The user provides a custom base Docker image
-2. Image Building: OpenHands builds a new Docker image (the "OH runtime image") based on the user-provided image. This new image includes OpenHands-specific code, primarily the "runtime client"
-3. Container Launch: When OpenHands starts, it launches a Docker container using the OH runtime image
-4. Action Execution Server Initialization: The action execution server initializes an `ActionExecutor` inside the container, setting up necessary components like a bash shell and loading any specified plugins
-5. Communication: The OpenHands backend (client: `openhands/runtime/impl/action_execution/action_execution_client.py`; runtimes: `openhands/runtime/impl/docker/docker_runtime.py`, `openhands/runtime/impl/local/local_runtime.py`) communicates with the action execution server over RESTful API, sending actions and receiving observations
-6. Action Execution: The runtime client receives actions from the backend, executes them in the sandboxed environment, and sends back observations
-7. Observation Return: The action execution server sends execution results back to the OpenHands backend as observations
+## Run the Official Image
-The role of the client:
+Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access.
-- It acts as an intermediary between the OpenHands backend and the sandboxed environment
-- It executes various types of actions (shell commands, file operations, Python code, etc.) safely within the container
-- It manages the state of the sandboxed environment, including the current working directory and loaded plugins
-- It formats and returns observations to the backend, ensuring a consistent interface for processing results
+