Agent Canvas Overview

Agent Canvas is an open-source control surface for agentic work. It gives you one browser UI for conversations, files, terminal output, model configuration, backends, and automations. By default, Agent Canvas runs on your own machine. You can also connect the same UI to backends running in Docker, on a VM, on Modal, or in OpenHands Cloud.

When To Use Agent Canvas

Use Agent Canvas when you want a self-hosted or local browser UI for agents that can work with real files, terminals, tools, and automations.

If you want to…	Start here
Run OpenHands locally in a browser	Install Agent Canvas
Use a sandboxed local environment	Docker Backend
Run agents on an always-on machine	VM / Self-Hosted Installation
Connect to managed cloud sandboxes	Cloud Backend
Use Claude Code, Codex, Gemini CLI, or another ACP agent	ACP Agents
Create scheduled or event-driven workflows	Pre-built Automations

How Agent Canvas Works

Agent Canvas has four pieces to understand:

Concept	What It Means	Why It Matters
Browser UI	The web interface you open in your browser.	This is where you chat, inspect files, manage settings, and configure automations.
Backend	The agent server that runs conversations, tools, settings, secrets, and automations.	This determines where the agent runs and what machine or sandbox it can access.
Workspace	The folder, repository, container mount, or cloud sandbox the agent works in.	This determines which files the agent can read and write.
Agent and model	The OpenHands agent or an ACP agent, plus the model credentials it uses.	This determines which LLM or provider receives conversation context and powers the agent.

Settings, secrets, LLM configuration, MCP servers, skills, conversations, and automations are scoped to the active backend. Switching backends switches the environment the agent is using.

Choosing A Trust Boundary

Before installing, decide where you want the agent to run and what files it should be able to access.

Setup	Trust Boundary	Best For
npm local install	Runs directly on your machine. The agent server can operate on the local filesystem.	Fastest local setup when you trust the machine and understand the file access.
Docker	Runs inside a container and only sees the directories you mount.	Local sandboxing and clearer file boundaries.
VM or dedicated machine	Runs on the remote host you control.	Always-on agents, heavier compute, team-shared backends, or personal/work separation.
OpenHands Cloud	Runs in managed OpenHands Cloud sandboxes.	Cloud execution without maintaining your own machine or VM backend.

Agent Canvas can run agents that execute shell commands, read files, write files, and use connected tools. Only connect a backend to files, secrets, and networks that you are willing to let the agent use.

Model Access

Agent Canvas supports several model access patterns:

Direct provider key — enter an API key from Anthropic, OpenAI, Google, or another supported provider.
OpenHands Cloud key — use an OpenHands Cloud API key for verified hosted models.
ACP agent subscription login — use a signed-in provider, such as Claude Code, Codex, or Gemini, when the backend runs on the same machine as that login.
Local or OpenAI-compatible provider — connect providers such as Ollama, LM Studio, LiteLLM, or a compatible gateway through model settings.

See LLM Profiles and Model Configuration and ACP Agents for details.

How It Fits With Other OpenHands Products

Product	Use It When
Agent Canvas	You want a self-hosted browser UI for local, remote, or cloud-backed agents and automations.
OpenHands Cloud	You want a fully managed hosted experience with no local installation.
OpenHands SDK	You want to build agents or agent-powered applications in Python.
Local GUI (Legacy)	You are following older Docker-based Local GUI documentation. New local browser workflows should use Agent Canvas.

Before You Start

For the normal local setup, you need:

Node.js 22.12 or later
npm
A model access path, such as a provider API key, OpenHands Cloud LLM key, ACP subscription login, or local model server
A folder, repository, or project workspace for the agent to work in

For a sandboxed local setup, use Docker instead of the direct npm backend path.

Pre-built Automations

Backends

When To Use Agent Canvas

How Agent Canvas Works

Choosing A Trust Boundary

Model Access

How It Fits With Other OpenHands Products

Before You Start

Where To Go Next

​When To Use Agent Canvas

​How Agent Canvas Works

​Choosing A Trust Boundary

​Model Access

​How It Fits With Other OpenHands Products

​Before You Start

​Where To Go Next

When To Use Agent Canvas

How Agent Canvas Works

Choosing A Trust Boundary

Model Access

How It Fits With Other OpenHands Products

Before You Start

Where To Go Next