Updates to New User flows from user feedback

openhands/usage/agent-canvas/overview.mdx

@@ -1,35 +1,90 @@
 ---
 title: Agent Canvas Overview
-description: A lightweight platform to run agents and automations — locally or in the cloud.
+description: Understand Agent Canvas, how it runs agents, and which setup path to choose.
 ---
 
-## Why Agent Canvas
+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.
 
-- **One UI to drive any agent**: run conversations with OpenHands, Claude Code, Codex, or Gemini CLI through the same browser interface.
-- **Bring your own LLM**: connect Anthropic, OpenAI, Google, or any OpenAI-compatible provider. Switch models per conversation.
-- **Built-in automations**: schedule cron jobs or wire up event-driven workflows against GitHub, Linear, Slack, and custom webhooks.
-- **Run it anywhere**: a single `agent-canvas` command starts the full stack locally. Self-host on a VM, or connect to OpenHands Cloud.
+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](/openhands/usage/cloud/openhands-cloud).
 
-## Key Concepts
+## When To Use Agent Canvas
 
-| Concept | What It Means |
-|---------|----------------|
-| **Agent Canvas** | A UI and backend server for running agents and automations. The `agent-canvas` command starts both together. |
-| **Backend** | Any Canvas UI can securely connect to any Canvas backend: running locally, on a remote machine, or on [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud). Register multiple and switch between them. |
-| **Conversation** | A single agent session tied to a backend. Each conversation has its own message history, tool calls, and file changes. |
-| **Automation** | A workflow that runs on a cron schedule or in response to events from GitHub, Linear, Slack, or custom webhooks. Automations may start agent conversations as needed. |
+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.
 
-## How It Fits with Other OpenHands Products
+| If you want to... | Start here |
+|-------------------|------------|
+| Run OpenHands locally in a browser | [Install Agent Canvas](/openhands/usage/agent-canvas/setup) |
+| Use a sandboxed local environment | [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) |
+| Run agents on an always-on machine | [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) |
+| Connect to managed cloud sandboxes | [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud) |
+| Use Claude Code, Codex, Gemini CLI, or another ACP agent | [ACP Agents](/openhands/usage/agent-canvas/acp-agents) |
+| Create scheduled or event-driven workflows | [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) |
 
-- **Agent Canvas**: the recommended browser-based UI for running OpenHands locally or self-hosted.
-- **Local GUI (Legacy)**: legacy UI requiring Docker.
-- **OpenHands Cloud**: a fully managed version of OpenHands.
-- **OpenHands SDK**: the Python framework behind the agent system.
+## How Agent Canvas Works
 
-## Where to Start
+Agent Canvas has four pieces to understand:
 
-- [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) — Get started with a ready-made automation workflow.
-- [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) — Run backend-only or full Canvas on a VM and connect remotely.
+| 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. |
+
+<Note>
+  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.
+</Note>
+
+## 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. |
+
+<Warning>
+  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.
+</Warning>
+
+## 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](/openhands/usage/agent-canvas/llm-profiles) and [ACP Agents](/openhands/usage/agent-canvas/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
+
+- [Install Agent Canvas](/openhands/usage/agent-canvas/setup)
+- [First Time Setup](/openhands/usage/agent-canvas/first-time-setup)
+- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
+- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles)
+- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting)