diff --git a/openhands/usage/agent-canvas/backend-setup/docker.mdx b/openhands/usage/agent-canvas/backend-setup/docker.mdx index 87d349a0..8e8633fa 100644 --- a/openhands/usage/agent-canvas/backend-setup/docker.mdx +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -3,7 +3,7 @@ title: Docker Backend description: Run Agent Canvas in a Docker container as a sandboxed backend. --- -The official Docker image packages the full Agent Canvas stack — agent server, automation backend, and frontend — in a single container. The agent runs inside the container rather than directly on your host, giving you a sandboxed environment out of the box. +The official Docker image packages the full Agent Canvas stack — backend and frontend — in a single container. The agent runs inside the container rather than directly on your host, giving you a sandboxed environment out of the box. ## Prerequisites diff --git a/openhands/usage/agent-canvas/backend-setup/local.mdx b/openhands/usage/agent-canvas/backend-setup/local.mdx index 69ca4347..4d18882c 100644 --- a/openhands/usage/agent-canvas/backend-setup/local.mdx +++ b/openhands/usage/agent-canvas/backend-setup/local.mdx @@ -3,7 +3,7 @@ title: Local Backend description: Run one or more local backends and connect to them from the Agent Canvas UI. --- -Use `--backend-only` to start a local backend. Each backend runs an agent server and automation backend behind an ingress proxy on its own port. +Use `--backend-only` to start a local backend. Each backend runs behind an ingress proxy on its own port. ## Start a Backend @@ -11,7 +11,7 @@ Use `--backend-only` to start a local backend. Each backend runs an agent server agent-canvas --backend-only ``` -This starts the agent server and automation backend on `127.0.0.1:8000`. No frontend is served. +This starts the backend on `127.0.0.1:8000`. No frontend is served. ## Running Multiple Backends @@ -23,7 +23,7 @@ agent-canvas --backend-only --port 8002 agent-canvas --backend-only --port 8003 ``` -Each instance gets its own agent server, automation backend, and ingress proxy. +Each instance gets its own backend and ingress proxy. ## Connect the Frontend diff --git a/openhands/usage/agent-canvas/backend-setup/vm.mdx b/openhands/usage/agent-canvas/backend-setup/vm.mdx index 834ab19e..79ab742a 100644 --- a/openhands/usage/agent-canvas/backend-setup/vm.mdx +++ b/openhands/usage/agent-canvas/backend-setup/vm.mdx @@ -3,7 +3,7 @@ title: VM / Self-Hosted Backend description: Run Agent Canvas on a VM or dedicated machine and connect to it remotely. --- -Use `--backend-only` to run the agent server and automation backend on a remote machine, then connect from your local frontend with `--frontend-only`. +Use `--backend-only` to run the backend on a remote machine, then connect from your local frontend with `--frontend-only`. The agent server can read and write the host filesystem, execute shell commands, and access the network. Lock down the machine before starting. @@ -41,7 +41,7 @@ On macOS, install Node and `uv` via Homebrew instead. LOCAL_BACKEND_API_KEY= npx @openhands/agent-canvas --backend-only --public ``` -- `--backend-only` starts only the agent server and automation backend (no frontend). +- `--backend-only` starts only the backend (no frontend). - `--public` requires `LOCAL_BACKEND_API_KEY` — every API request must carry a matching `X-Session-API-Key` header. diff --git a/openhands/usage/agent-canvas/backends.mdx b/openhands/usage/agent-canvas/backends.mdx index 7d1fa2ef..b2741b43 100644 --- a/openhands/usage/agent-canvas/backends.mdx +++ b/openhands/usage/agent-canvas/backends.mdx @@ -1,75 +1,21 @@ --- -title: Connect and Manage Backends -description: Use Agent Canvas with local, remote, or cloud-backed OpenHands backends. +title: Backends +description: Understand and manage Agent Canvas backends. --- -Agent Canvas always works against an **active backend**. Conversations, backend-synced settings, and some feature availability depend on which backend is currently selected. +A **backend** is an [agent server](/sdk/guides/agent-server/overview#what-is-a-remote-agent-server) and the workspace it operates in. All conversations, settings, and automations run against whichever backend is currently selected. -## What is a "Backend"? -A **backend** is any environment where the OpenHands agent can execute work. +## Connecting to a Backend -Each backend includes: -- An **[OpenHands Agent Server](/sdk/guides/agent-server/overview#what-is-a-remote-agent-server)** that servers as a lightweight HTTP API server for remote agent execution. -- A **workspace** where files are made available to the agent, and where the agent runs. +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. -With the backend concept, users can setup a backend for each code repository (thus having a unique backend and execution environment for each repo). +Settings, LLM configuration, MCP servers, and automations are all scoped to the active backend — switching backends switches all of these. -Users can also connect Agent Canvas to [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) as a backend, enabling conversations and [automations](/openhands/usage/automations/overview) to use OpenHands Cloud on-demand sandboxes for agent execution. +## Recommended Setups -## Default Local Backend - -On first launch, Agent Canvas seeds a default local backend that points to the stack started by the `agent-canvas` command. - -That default backend is a good fit when you want to: - -- Run OpenHands entirely on your current machine -- Test configuration changes quickly -- Use the bundled automation backend locally - -## Managing Additional Backends - -Use the backend switcher in the UI to open `Manage Backends`, then add or edit backend entries. - -Each backend entry stores: - -- A display name -- A host or base URL -- An API key when the backend requires one - -Agent Canvas also tracks whether a backend is local or cloud so it can adjust the available flows. - -## Local vs. Cloud Backends - -| Backend Type | Typical Use | -|--------------|-------------| -| **Local** | A machine you control directly, such as your laptop, a VM, or a team-managed host | -| **Cloud** | A compatible backend running an agent-server or OpenHands Cloud | - -## What Changes When You Switch Backends - -Switching the active backend changes more than just where conversations run. - -- `Settings` read and write against the active backend -- LLM availability depends on what that backend exposes -- `Customize > MCP Servers` acts on the active backend's MCP configuration -- Automations depend on whether the active backend has the automation service available - - - If a backend is unreachable, Agent Canvas can still open the backend management flow so you can fix the host, API key, or selection without leaving the app. - - -## Recommended Setup Pattern - -A common setup is to keep one local backend for experimentation and add one or more remote backends for longer-running or more powerful workloads. - -Examples: - -- A laptop backend for quick local tasks -- A dedicated VM backend for always-on work -- A cloud backend for hosted conversations - -## Related Guides - -- [Setup](/openhands/usage/agent-canvas/setup) -- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) -- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) +| 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](/openhands/usage/agent-canvas/backend-setup/local). | +| **Backend-only (remote)** | Always-on server, more powerful hardware, or team-shared access | Run `agent-canvas --backend-only --public` on a VM with a `LOCAL_BACKEND_API_KEY`, connect via SSH tunnel or reverse proxy. See [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm). | +| **Cloud** | Managed sandboxes without local resources | Connect to [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) from **Manage Backends**. See [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud). | diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx index 3e9d0f45..65a62795 100644 --- a/openhands/usage/agent-canvas/overview.mdx +++ b/openhands/usage/agent-canvas/overview.mdx @@ -35,5 +35,5 @@ description: A lightweight platform to run agents and automations — locally or - [Install](/openhands/usage/agent-canvas/setup) — Use the published npm package to run Agent Canvas from your terminal. - [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) — Switch between local and remote backends. - [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) — Configure skills, MCP servers, and backend-synced settings. -- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) — Work with the bundled automation backend. +- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) — Get started with a ready-made automation workflow. - [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) — Run a backend on a VM and connect remotely. diff --git a/openhands/usage/agent-canvas/prebuilt-automations.mdx b/openhands/usage/agent-canvas/prebuilt-automations.mdx index e16a1862..0f9c2b98 100644 --- a/openhands/usage/agent-canvas/prebuilt-automations.mdx +++ b/openhands/usage/agent-canvas/prebuilt-automations.mdx @@ -15,7 +15,7 @@ Agent Canvas ships with a set of pre-built automations for the most common agent --- -Agent Canvas can work with the OpenHands automation backend so you can run agents on a schedule or in response to external events. +Every canvas backend includes an automation service, so you can run agents on a schedule or in response to external events. ## What You Can Do @@ -37,29 +37,4 @@ In practice, new automation setup often starts in one of two ways: Visit the Automations Docs have a more [detailed guide on creating automations](/openhands/usage/automations/creating-automations). -## Local Stack Behavior - -When you start Agent Canvas with the `agent-canvas` command, the local stack includes the automation backend by default. - -That makes the built-in local setup a good starting point for: - -- Scheduled maintenance tasks -- Event-driven coding workflows -- Testing automation ideas before deploying them elsewhere - -## Backend Availability Matters - -The `Automations` view depends on the active backend. - -- If the active backend has a healthy automation service, Agent Canvas can load and manage automations. -- If it does not, Agent Canvas shows a backend-not-configured or unavailable state. - - - Some automation editing flows are currently focused on local backends first, while the broader hosted experience continues to evolve. - - -## Related Guides - -- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) -- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) -- [Automations Overview](/openhands/usage/automations/overview) +Automations run against the active backend. Use [Manage Backends](/openhands/usage/agent-canvas/backends) to see and switch which backend your automations run on. diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index 6db32068..819ff8c8 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -29,7 +29,7 @@ description: Install and run Agent Canvas via npm or Docker. |------|-------------| | `-p`, `--port ` | Set the ingress port (default `8000`) | | `--public` | Enable public mode — requires `LOCAL_BACKEND_API_KEY`. The key is **not** injected into the frontend; users must enter it when the UI loads. Use this for any deployment reachable by others. See [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm). | - | `--backend-only` | Start only the agent server and automation backend behind ingress (no frontend). Use this to run a headless backend on a VM or server. | + | `--backend-only` | Start only the backend behind ingress (no frontend). Use this to run a headless backend on a VM or server. | | `--frontend-only` | Start only the static frontend behind ingress (no agent server or automation). Use this to point a local UI at a remote backend. | | `-v`, `--version` | Show the version number | | `--info` | Show the version and default stack configuration (agent server version, ports, etc.) |