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.
Where To Go Next
