Backends - OpenHands Docs

A backend is an agent server and the workspace it operates in. All conversations, settings, and automations run against whichever backend is currently selected.

Connecting to a Backend

Any Agent Canvas frontend can connect to any Agent Canvas backend. Use the backend switcher in the UI to open Manage Backends, where you can add, edit, or remove entries. Each entry stores a display name, host URL, and an API key for authentication. Settings, LLM configuration, MCP servers, and automations are all scoped to the active backend — switching backends switches all of these.

Recommended Setups

Setup	When to use	How
Default local	Quick local work on your machine	Run `agent-canvas` — a local backend is created automatically
Backend-only (local)	Multiple projects, or separate frontend and backend processes	Run `agent-canvas --backend-only` (optionally on different ports), connect with `--frontend-only`. See Local Backend.
Self-hosted VM	Always-on server, more powerful hardware, team-shared access, or a full self-hosted Canvas	Run `agent-canvas --backend-only --public` for backend-only mode, or `agent-canvas --public` for the full UI and backend. Expose it with SSH, ngrok, or a reverse proxy. See VM / Self-Hosted Installation.
Cloud	Managed sandboxes without local resources	Connect to OpenHands Cloud from Manage Backends. See Cloud Backend.
Modal	Cloud backend with per-second billing, no VM management	Deploy the agent server on Modal with a single command. See Modal Backend.

​Connecting to a Backend

​Recommended Setups

Connecting to a Backend

Recommended Setups