Agent Canvas Architecture

Understand how Agent Canvas connects to execution, automation, and sandbox services.

Agent Canvas is the open-source browser client and control center for OpenHands conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent process executes tools, and the selected workspace or sandbox provides the execution boundary.

Core Components

Component	Responsibility	Source
Agent Canvas	Browser interface for conversations, files, settings, backends, and automations	OpenHands/OpenHands
Agent Server	Runs conversations, agents, tools, and workspace operations; streams events to clients	OpenHands/software-agent-sdk
Automation Server	Stores schedules and event triggers, tracks runs, and dispatches conversations	OpenHands/automation
Workspace or sandbox	Defines which files, processes, credentials, and networks an agent can access	Deployment-specific

Sandbox Server is a community-driven standalone API and sandbox control plane. Learn more about Sandbox Server.

Service Relationships

The normal browser path is Browser → Agent Canvas → selected backend. Agent Server owns conversation execution. Automation Server owns scheduled and event-driven run lifecycle. A backend distribution can expose both services behind one URL, but they remain separate responsibilities.

A remote backend uses the same Agent Server API as a local backend. The Agent Server can run on another machine, or in a separate container on the same machine as Canvas. OpenHands Cloud and OpenHands Enterprise are managed backend platforms: their platform control planes create conversation sandboxes that host Agent Server.

Client And Launcher Boundaries

Agent Canvas can refer to two related surfaces:

• Canvas client — The React browser application. It renders state and sends requests to backend services.
• agent-canvas launcher and distributions — Packaging that can start the Canvas client, Agent Server, Automation Server, and ingress together.

The launcher supports split modes:

Mode	Services started
agent-canvas	Canvas client, Agent Server, Automation Server, and ingress
agent-canvas --frontend-only	Canvas client and ingress
agent-canvas --backend-only	Agent Server, Automation Server, and ingress

Docker and Helm packages can also bundle the client and backend services. A bundled deployment changes how services are installed, not which component owns execution or isolation.

Execution and Isolation

When you send a message, Agent Canvas sends it to the selected backend. Agent Server starts or resumes the conversation, runs the selected agent, invokes tools, updates backend state, and streams events to Canvas.

The workspace determines the execution boundary:

Workspace type	Execution and isolation boundary
Local process	Agent Server and tools run directly on the backend host without container isolation.
Docker or Kubernetes	Agent Server and tools run inside the configured container or pod with its mounts and network policy.
Remote Agent Server	Agent Server runs on another machine or in a separate container, with the workspace boundary configured there.
OpenHands Cloud or Enterprise	The managed platform creates and operates the conversation sandbox that hosts Agent Server.

Connecting Canvas to a remote backend does not grant the browser direct access to that backend’s filesystem. Canvas displays files and terminal output returned by Agent Server.

State Ownership

State belongs to backend services rather than the browser client:

• Agent Server stores conversation history, agent and LLM profiles, secrets, MCP configuration, and related settings.
• Automation Server stores automation definitions, schedules, events, and run history.
• The workspace or sandbox stores files produced or changed by the agent.
• Agent Canvas stores connection information needed to reach configured backends.

Switching backends changes which backend-managed conversations, settings, automations, and workspaces Canvas displays.

Deployment Patterns

Pattern	Relationship
Local all-in-one	The launcher starts Canvas and local backend services on one machine.
Remote Agent Server	Canvas connects to an Agent Server running on another machine or in a separate container on the same machine.
Self-hosted backend services	You deploy Agent Server, and optionally Automation Server, on a VM, Docker host, Kubernetes cluster, or Modal.
Managed platform	Canvas connects to OpenHands Cloud or OpenHands Enterprise, which operate their backend and sandbox infrastructure.

Next Steps

• Install Agent Canvas
• Connect And Manage Backends
• Self-Host On A VM
• Use Docker
• Agent Server Overview