When To Use Agent Canvas
Choose the path that matches where and how you want your agents to run:Install Agent Canvas
Run OpenHands locally in a browser.
Use Docker
Use a sandboxed local environment with mounted project directories.
VM / Self-Hosted
Run agents on an always-on machine you control.
Cloud Backend
Connect to managed cloud sandboxes.
ACP Agents
Use Claude Code, Codex, Gemini CLI, or another ACP agent.
Desktop Preview
Test a preview build of the native desktop app.
How Agent Canvas Works
Agent Canvas is the browser client. It connects to backend services that own execution and persistent state:
The
agent-canvas launcher can package the client and backend services into one local stack. You can also run the client separately and connect it to services on a VM, in Docker or Kubernetes, or through OpenHands Cloud or OpenHands Enterprise.
See Agent Canvas Architecture for the complete service and deployment model.
Switching backends switches the environment the agent is using. For details on how conversations and workspaces remain separate, see Conversations and Backends.
Enterprise License Warnings
On an instance-locked OpenHands Enterprise Canvas, check the banner at the top of the page for license warnings, such as a missing or expired license or an upcoming trial end. The banner appears only when the instance reports a relevant status. It does not appear for a license in good standing, when enforcement is off, or when the instance does not provide a supported license status route.Choosing A Trust Boundary
Before installing, decide where you want the agent to run and what files it should be able to access.What Happens When You Close the Terminal?
For a local npm or npx installation, closing the terminal stops the Agent Canvas process, so the browser UI can no longer use its local backend. Start Agent Canvas again with the same command to continue. A Docker container, VM, or cloud backend continues running until that backend is stopped. See Install to restart Agent Canvas and Troubleshooting if the browser cannot reconnect.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 LLM API key — use an OpenHands LLM 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.
Customize Your Agent
After the first conversation, choose the extension point that matches your need:Repository Context
Add always-on repository guidance with
AGENTS.md.Skills
Add reusable task-specific instructions.
MCP Settings
Connect external tools or services.
Plugins
Extend the agent with packaged capabilities.
Automations
Run work on a schedule or in response to events.
How It Fits With Other OpenHands Products
Agent Canvas vs “openhands serve”
agent-canvas starts the current Agent Canvas UI and backend stack. openhands serve starts the legacy OpenHands CLI GUI server and will not run if you have only installed agent-canvas.
How Conversations and Workspaces Are Isolated
A conversation belongs to one active backend and has its own history, agent configuration, and backend-managed state. Its workspace is the folder, mount, or sandbox attached to that backend. Start a new conversation for a separate task, or branch a conversation to explore another path while preserving the original.Before You Start
For the normal local setup, you need:- Node.js 24 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
Where To Go Next
First Time Setup
Configure your agent, backend, and model after installing.
Conversations
Start, branch, and manage agent conversations.
Troubleshooting
Fix install, startup, backend, and model issues.

