Skip to main content
Agent Canvas is an open-source control surface for agentic work. From one place, you can manage conversations, files, terminals, model configuration, backends, and automations. The browser interface connects to one or more backends that run the agent and its tools. By default, that backend runs on your machine, but you can instead use Docker, a VM, Modal, or OpenHands Cloud. The LLM models can run locally, through a provider API or be accessed through an ACP agent.

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.
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.

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.
See Configure a Model, Manage LLM Profiles, and ACP Agents for details.

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
For a sandboxed local setup, use Docker instead of the direct npm backend path.

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.