diff --git a/docs.json b/docs.json index 1a6784c5..b5408c90 100644 --- a/docs.json +++ b/docs.json @@ -40,16 +40,41 @@ ] }, { - "group": "Onboarding OpenHands", + "group": "Onboarding Agent Canvas", "pages": [ - "openhands/usage/customization/repository", - "openhands/usage/customization/hooks" + "openhands/usage/agent-canvas/overview", + "openhands/usage/agent-canvas/setup", + { + "group": "Setup a Pre-built Automation", + "pages": [ + "openhands/usage/agent-canvas/prebuilt-automations", + "openhands/usage/agent-canvas/prebuilt/github-pr-review", + "openhands/usage/agent-canvas/prebuilt/github-repo-monitor", + "openhands/usage/agent-canvas/prebuilt/slack-channel-monitor" + ] + }, + { + "group": "Connect and Manage Backends", + "pages": [ + "openhands/usage/agent-canvas/backends", + "openhands/usage/agent-canvas/backend-setup/local", + "openhands/usage/agent-canvas/backend-setup/vm", + "openhands/usage/agent-canvas/backend-setup/docker", + "openhands/usage/agent-canvas/backend-setup/cloud" + ] + }, + "openhands/usage/agent-canvas/customize-and-settings", + "openhands/usage/agent-canvas/acp-agents", + "openhands/usage/agent-canvas/self-hosting", + "openhands/usage/agent-canvas/development", + "openhands/usage/agent-canvas/troubleshooting" ] }, { "group": "Product Guides", "pages": [ "openhands/usage/key-features", + "openhands/usage/customization/hooks", "overview/model-context-protocol", { "group": "Skills", @@ -74,6 +99,7 @@ "openhands/usage/automations/managing-automations" ] }, + "openhands/usage/customization/repository", { "group": "Settings", "pages": [ diff --git a/openhands/static/img/agent-canvas-setup-step-1.png b/openhands/static/img/agent-canvas-setup-step-1.png new file mode 100644 index 00000000..6de5c8a9 Binary files /dev/null and b/openhands/static/img/agent-canvas-setup-step-1.png differ diff --git a/openhands/static/img/agent-canvas-setup-step-2.png b/openhands/static/img/agent-canvas-setup-step-2.png new file mode 100644 index 00000000..5fc24fad Binary files /dev/null and b/openhands/static/img/agent-canvas-setup-step-2.png differ diff --git a/openhands/static/img/agent-canvas-setup-step-3.png b/openhands/static/img/agent-canvas-setup-step-3.png new file mode 100644 index 00000000..9edab0f2 Binary files /dev/null and b/openhands/static/img/agent-canvas-setup-step-3.png differ diff --git a/openhands/static/img/agent-canvas-setup-step-4.png b/openhands/static/img/agent-canvas-setup-step-4.png new file mode 100644 index 00000000..d023bf95 Binary files /dev/null and b/openhands/static/img/agent-canvas-setup-step-4.png differ diff --git a/openhands/usage/agent-canvas/acp-agents.mdx b/openhands/usage/agent-canvas/acp-agents.mdx new file mode 100644 index 00000000..4a9b4517 --- /dev/null +++ b/openhands/usage/agent-canvas/acp-agents.mdx @@ -0,0 +1,94 @@ +--- +title: ACP Agents +description: Drive Agent Canvas conversations with an external coding agent — Claude Code, Codex, or Gemini CLI — over the Agent Client Protocol. +--- + +Agent Canvas can drive your conversations with the built-in **OpenHands** agent or with an external **ACP agent** — Claude Code, Codex, or Gemini CLI. This guide explains what ACP agents are, how to onboard one, and how to switch agents or models later. + +## What is an ACP agent? + +The [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/overview) is a standard for talking to coding agents over JSON-RPC on stdio. Instead of Agent Canvas calling an LLM directly, the Agent Server spawns the agent's own CLI as a subprocess and relays each turn to it. The external agent manages its own LLM, tools, and execution; Agent Canvas sends messages and renders what comes back. + +```mermaid +flowchart LR + canvas["Agent Canvas
(this UI)"] + server["Agent Server"] + acp["ACP subprocess
(e.g. claude-agent-acp)"] + llm["LLM provider
(Anthropic / OpenAI / Google)"] + canvas -- "PATCH /api/settings
(agent_kind, acp_*)" --> server + canvas -- "conversation turns" --> server + server -- "spawn + JSON-RPC over stdio" --> acp + acp -- "API calls" --> llm +``` + +The Agent Server owns the subprocess and the credentials; Agent Canvas only records *which* agent to run and surfaces a form for the secrets it needs. The agent choice is stored per backend, so switching backends can switch agents. + +## Supported providers + +| Provider | Default command | +|---|---| +| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` | +| **Codex** | `npx -y @zed-industries/codex-acp` | +| **Gemini CLI** | `npx -y @google/gemini-cli --acp` | + +The provider list is sourced from the OpenHands SDK registry (`openhands.sdk.settings.acp_providers`, mirrored into `@openhands/typescript-client`) and enriched with Canvas UI metadata. Adding or changing a provider happens upstream in the SDK. + +## Authentication + + + ACP agents authenticate **two ways: a subscription login, or an API key** — and the onboarding fields are optional. If you're already signed in to the provider's CLI on the machine the agent runs on, it reuses that login automatically, so locally you often don't need a key at all. **The login takes priority over an API key:** while you're signed in, a key set in the environment isn't used — so the onboarding key fields do nothing and can be left blank. + + +A "subscription login" is the credential the provider's own CLI stores when you sign in once — a file in your home directory, or, for Claude Code on macOS, the system **Keychain**. When the Agent Server runs **on that same machine** (a local or self-hosted backend), the provider CLI finds that login automatically — no API key required. On a clean cloud sandbox there's no stored login, so an API key is needed instead. + +| Provider | Subscription login (auto-detected) | API key | +|---|---|---| +| **Claude Code** | A Claude Code login (Pro/Max), from Claude Code's own credential store: the **macOS Keychain**, or `~/.claude/.credentials.json` on Linux | `ANTHROPIC_API_KEY` | +| **Codex** | A ChatGPT login (`codex login`) cached at `~/.codex/auth.json` | `OPENAI_API_KEY` | +| **Gemini CLI** | Your Google login (`gemini`/`gemini --acp`) cached at `~/.gemini/oauth_creds.json` | `GEMINI_API_KEY` | + +All three collect an *optional* API key (plus base URL) in onboarding. As noted above, a subscription / OAuth login takes priority over an API key — when the provider's CLI is signed in, a key set in the environment is not used: + +- **Codex** — `codex login status` keeps reporting the ChatGPT login even with `OPENAI_API_KEY` set. +- **Gemini CLI** — uses the OAuth auth type chosen at `gemini` login; `GEMINI_API_KEY` is only consulted if you switch the auth type. The free Google login is the common no-key path locally — sign in once and it just works. +- **Claude Code** — with both present, `claude auth status` reports it is authenticated via the subscription (`claude.ai`), not the key. The login is auto-detected from the macOS Keychain (or `~/.claude/.credentials.json` on Linux); `CLAUDE_CONFIG_DIR` is **not** required for it — it only relocates Claude Code's config directory (settings/history, not the token) and signals the SDK to strip a conflicting `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. + +The one exception is the **base URL** (`*_BASE_URL`): a custom value points the CLI at a different endpoint (a proxy or gateway) and *does* take effect even under a login — for Gemini it rides the ACP `gateway` param. It's an advanced override, not needed for normal use. + +## Onboarding an ACP agent + +First-time users get a four-step onboarding modal. To onboard an ACP agent: + +1. **Choose agent** — pick Claude Code, Codex, or Gemini CLI instead of OpenHands. The choice is saved immediately to your backend's settings. +2. **Check backend** — confirms Agent Canvas can reach the Agent Server. +3. **Set up credentials** — enter the provider's API key (and, optionally, a custom base URL for a proxy or gateway). All three providers collect these here, and every field is optional. +4. **Say hello** — creates your first conversation and closes the modal. + + + Every credential field is optional and the step is skippable. Leave a field blank to reuse a key already set on the backend, or to authenticate the agent through a subscription / OAuth login instead. + + +### How credentials reach the agent + +Each credential you enter is saved as a **global secret** whose name is exactly the environment variable the Agent Server exports into the ACP subprocess (e.g. `ANTHROPIC_API_KEY`). Saving in onboarding is identical to adding the secret under **Settings → Secrets**, where you can edit or remove it anytime. Keeping the secret name equal to the env var is what makes a saved key actually reach the provider CLI. + +## Switching agent or model later + +Open **Settings → Agent** at any time: + +- **Agent** — switch between **OpenHands** and **ACP**. +- **Preset** — pick a built-in provider (Claude Code, Codex, Gemini CLI) or **Custom** to point at any other ACP server. +- **Command** — the command line used to spawn the subprocess. Selecting a preset fills this in; editing it to match another preset re-detects that provider. API keys are *not* entered here — they live in the Secrets panel. +- **Model** — choose a suggested model for the provider or enter a custom model override. Built-in providers save a concrete model rather than leaving it blank. + +Saving writes an `agent_settings_diff` (`agent_kind`, `acp_server`, `acp_command`, `acp_model`) to `PATCH /api/settings`. A running conversation keeps the agent it started with; the new choice applies to conversations you start afterward. + +## Custom ACP servers + +Any stdio ACP server works: choose **Custom** in Settings → Agent and enter its launch command. Custom servers have no curated model list, so enter the model ID the server expects (if any) as a custom model. Pass credentials by adding the env vars the server reads as global secrets under **Settings → Secrets**. + +## Related Guides + +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) diff --git a/openhands/usage/agent-canvas/backend-setup/cloud.mdx b/openhands/usage/agent-canvas/backend-setup/cloud.mdx new file mode 100644 index 00000000..7d908e43 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/cloud.mdx @@ -0,0 +1,6 @@ +--- +title: Setup an OpenHands Cloud Backend +description: Connect Agent Canvas to an OpenHands Cloud backend. +--- + +Coming soon. diff --git a/openhands/usage/agent-canvas/backend-setup/docker.mdx b/openhands/usage/agent-canvas/backend-setup/docker.mdx new file mode 100644 index 00000000..9d1dd127 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -0,0 +1,155 @@ +--- +title: Setup a Docker Backend +description: Build a custom OpenHands Agent Server image and connect Agent Canvas to it. +--- + +This guide walks through building a **custom Agent Server image** that layers extra tooling (for example, the JDK) on top of the official base image, running it locally with Docker, and registering it as a backend in Agent Canvas. + +Use this approach when the default backend's toolchain is missing something your agent needs, such as a specific language runtime, build tool, or CLI. + +## Prerequisites + +- Docker installed and running +- An LLM API key (Anthropic, OpenAI, etc.) +- Agent Canvas installed and running locally — see [Setup](/openhands/usage/agent-canvas/setup) + +## 1. Build a Custom Image + +The OpenHands Agent Server publishes a base image at `ghcr.io/openhands/agent-server`. Extend it with a small `Dockerfile` that installs whatever your agent needs. + +The example below adds the JDK and a few common utilities. Save it as `Dockerfile`: + +```dockerfile icon="docker" +FROM ghcr.io/openhands/agent-server:1-python + +USER root + +# Install Java (JDK) and common build/diagnostic utilities. +RUN apt-get update \ + && apt-get install -y --no-install-recommends \ + default-jdk \ + maven \ + unzip \ + vim \ + less \ + && rm -rf /var/lib/apt/lists/* + +# Switch back to the unprivileged user that the base image runs as. +USER openhands +``` + + + The base image already ships with Python, Node.js, `git`, `jq`, `tmux`, build tools, and a VS Code Web + VNC stack. Only add what you actually need on top. + + + + For fully reproducible builds, pin to a more specific tag like `1.24.0-python` instead of `1-python`. + + +Build the image with a tag you can reference later: + +```bash +docker build -t agent-server-java:latest . +``` + + + For ARM hosts (Apple Silicon, Graviton), prefer the matching base tag (for example `latest-python` already supports multi-arch). If you need to force a platform, pass `--platform linux/amd64` to `docker build`. + + +## 2. Run the Custom Image + +Start the image, expose the agent server's HTTP port, and protect it with a session API key. The agent server reads `SESSION_API_KEY` from the environment and requires the same value on the `X-Session-API-Key` header for every request. + +Use the same name for the container as you'll use for the Agent Canvas backend — it makes it easy to tell which container backs which backend later. + +```bash +# Pick any sufficiently random value; you'll paste it into Agent Canvas later. +export SESSION_API_KEY="$(openssl rand -hex 32)" + +docker run -d \ + --name agent-server-java \ + -p 8001:8000 \ + -e SESSION_API_KEY="$SESSION_API_KEY" \ + agent-server-java:latest +``` + +Verify the server is reachable: + +```bash +curl -H "X-Session-API-Key: $SESSION_API_KEY" http://localhost:8001/health +``` + + + The agent server can execute arbitrary shell commands inside the container. Treat `SESSION_API_KEY` like a production credential and **do not expose port 8001 to the public internet** without a TLS-terminating reverse proxy in front of it. + + +To follow logs or stop the container: + +```bash +docker logs -f agent-server-java +docker stop agent-server-java +``` + +## 3. Add the Backend in Agent Canvas + +With the container running, point Agent Canvas at it: + +1. Open Agent Canvas. +2. Click the backend switcher in the top bar and choose **Manage Backends**. +3. Click **Add Backend** and fill in: + - **Name** — `agent-server-java` (matching the container name) + - **Host / Base URL** — `http://localhost:8001` + - **API Key** — the `SESSION_API_KEY` value from step 2 + - **Type** — `Local` +4. Save the backend and select it as the **active backend**. + +Agent Canvas will run a health check against the URL. Once it passes, the backend is ready to handle conversations using the tools you baked into the image. + + + See [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) for what changes when you switch the active backend (settings, LLM availability, MCP servers, automations). + + +## Running Multiple Custom Backends + +You can build as many custom images as you need and run each one as its own backend in Agent Canvas. A common pattern is one image per language or repo toolchain — for example a `agent-server-java` for JVM work, a `agent-server-rust` for Cargo projects, and a `agent-server-data` image with the Python data stack pre-installed. + +Give each container its own name, its own host port, and its own `SESSION_API_KEY`, then add a matching backend entry in Agent Canvas for each one: + +```bash +# JVM toolchain on port 8001 +docker run -d --name agent-server-java \ + -p 8001:8000 -e SESSION_API_KEY="$JAVA_KEY" \ + agent-server-java:latest + +# Rust toolchain on port 8002 +docker run -d --name agent-server-rust \ + -p 8002:8000 -e SESSION_API_KEY="$RUST_KEY" \ + agent-server-rust:latest + +# Python data stack on port 8003 +docker run -d --name agent-server-data \ + -p 8003:8000 -e SESSION_API_KEY="$DATA_KEY" \ + agent-server-data:latest +``` + +In **Manage Backends**, add one entry per container using the matching name, URL, and API key. You can then switch between them from the backend selector depending on what kind of task you're working on. + +## Updating the Image + +When you want to add more tooling or pick up a newer agent server release: + +```bash +docker pull ghcr.io/openhands/agent-server:1-python +docker build -t agent-server-java:latest . +docker stop agent-server-java && docker rm agent-server-java +# then re-run the `docker run` from step 2 +``` + +The existing backend entry in Agent Canvas keeps working as long as the host, port, and `SESSION_API_KEY` stay the same. + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Setup a Local Backend](/openhands/usage/agent-canvas/backend-setup/local) +- [Setup a VM Backend](/openhands/usage/agent-canvas/backend-setup/vm) +- [Agent Server Overview](/sdk/guides/agent-server/overview) diff --git a/openhands/usage/agent-canvas/backend-setup/local.mdx b/openhands/usage/agent-canvas/backend-setup/local.mdx new file mode 100644 index 00000000..7755b99f --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/local.mdx @@ -0,0 +1,6 @@ +--- +title: Setup a Local Backend +description: Run an OpenHands agent server locally and connect Agent Canvas to it. +--- + +Coming soon. diff --git a/openhands/usage/agent-canvas/backend-setup/vm.mdx b/openhands/usage/agent-canvas/backend-setup/vm.mdx new file mode 100644 index 00000000..f0e6987a --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/vm.mdx @@ -0,0 +1,6 @@ +--- +title: Setup a VM Backend +description: Run an OpenHands agent server on a VM and connect Agent Canvas to it. +--- + +Coming soon. diff --git a/openhands/usage/agent-canvas/backends.mdx b/openhands/usage/agent-canvas/backends.mdx new file mode 100644 index 00000000..75035475 --- /dev/null +++ b/openhands/usage/agent-canvas/backends.mdx @@ -0,0 +1,75 @@ +--- +title: Connect and Manage Backends +description: Use Agent Canvas with local, remote, or cloud-backed OpenHands backends. +--- + +Agent Canvas always works against an **active backend**. Conversations, backend-synced settings, and some feature availability depend on which backend is currently selected. + +## What is a "Backend"? +A **backend** is any environment where the OpenHands agent can execute work. + +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. + +With the backend concept, users can setup a backend for each code repository (thus having a unique backend and execution environment for each repo). + +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. + +## 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) +- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting) diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx new file mode 100644 index 00000000..2e204166 --- /dev/null +++ b/openhands/usage/agent-canvas/customize-and-settings.mdx @@ -0,0 +1,59 @@ +--- +title: Customize and Settings +description: Configure skills, MCP servers, and backend-synced settings in Agent Canvas. +--- + +Agent Canvas separates **Customize** from **Settings**. + +- `Customize` is where you extend what the agent can use. +- `Settings` is where you configure backend-synced behavior for the active backend. + +## Customize + +Open the top-level `Customize` area to manage: + +- [Skills](/overview/skills) +- [MCP Servers](/openhands/usage/settings/mcp-settings) + +Use the section navigation inside `Customize` to switch between those pages. + + + MCP configuration lives under `Customize > MCP Servers`, not under `Settings`. + + +## Settings + +The `Settings` area currently includes the following sections: + +| Section | Purpose | +|---------|---------| +| `Agent` | Agent behavior and agent-specific capabilities | +| `LLM` | Provider, model, API key, and profile configuration | +| `Condenser` | Context compression and summarization behavior | +| `Verification` | Approval and verification-related behavior | +| `Application` | UI-level preferences and app behavior | +| `Secrets` | Stored secrets used by the active backend | + +On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles. + +## Backend-Synced Behavior + +Each settings section is synced with the **active backend**. That means: + +- Changing backends changes which settings you are editing +- A setting saved for one backend does not automatically apply to every other backend +- The available options can differ depending on backend capabilities + +## Practical Example + +You might use this split like this: + +- Add a GitHub review skill in `Customize > Skills` +- Add a Slack or fetch MCP server in `Customize > MCP Servers` +- Save your preferred model in `Settings > LLM` +- Store tokens in `Settings > Secrets` + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) diff --git a/openhands/usage/agent-canvas/development.mdx b/openhands/usage/agent-canvas/development.mdx new file mode 100644 index 00000000..11b50989 --- /dev/null +++ b/openhands/usage/agent-canvas/development.mdx @@ -0,0 +1,104 @@ +--- +title: Contribute / Development +description: Clone Agent Canvas, run it from source, and use the developer workflows. +--- + +This page is for contributors and advanced users who want to run Agent Canvas from a local checkout. If you only want to use Agent Canvas, follow the [Setup](/openhands/usage/agent-canvas/setup) guide instead. + +## Clone the Repository + +```bash +git clone https://github.com/OpenHands/agent-canvas.git +cd agent-canvas +npm install +``` + +## Recommended Local Workflow + +The standard development flow runs the full local stack with live frontend updates: + +```bash +npm run dev +``` + +That workflow uses `uvx` to start the agent server and automation backend, then fronts them with the Vite dev server and ingress proxy. + +That workflow starts: + +- the Agent Canvas frontend +- the OpenHands agent server +- the automation backend +- the ingress proxy that ties them together + +## Other Useful Development Modes + +| Command | When to Use It | +|---------|----------------| +| `npm run dev` | Full local development stack | +| `npm run dev:static` | Serve a static frontend build instead of the Vite dev server | +| `npm run dev:minimal` | Run only the agent server and Vite, without automation or ingress | +| `npm run dev:extra-backend` | Start an additional local backend that shares the main dev stack's persistence | +| `npm run dev:frontend` | Point the frontend at a separately managed backend | +| `npm run dev:mock` | Work on the UI without a live backend | + +`npm run dev:minimal` serves the frontend directly on `http://localhost:3001`. + +`npm run dev:frontend` expects a separately managed backend at `127.0.0.1:8000` unless you override the frontend proxy settings. + +## Verification Commands + +Use the repo's built-in checks before sending a change upstream: + +```bash +npm run test +npm run build +``` + +## Development Environment Variables + +You can place frontend overrides in a local `.env` file based on `.env.sample`. + +These variables are mainly useful when you are running Agent Canvas from a local checkout. + +### Launcher Variables + +| Variable | Purpose | +|----------|---------| +| `PORT` | Ingress port for the bundled development stack | +| `OH_AUTOMATION_GIT_REF` | Git ref used for the automation backend | +| `OH_CANVAS_SAFE_BACKEND_PORT` | Backend port for the isolated local agent server | +| `OH_CANVAS_SAFE_VSCODE_PORT` | VS Code sidecar port for the isolated local agent server | +| `OH_CANVAS_SAFE_STATE_DIR` | Base directory for isolated local state | + +### Frontend Variables + +| Variable | Purpose | +|----------|---------| +| `VITE_BACKEND_BASE_URL` | Base URL used by browser-side requests | +| `VITE_BACKEND_HOST` | Backend target for the Vite dev proxy | +| `VITE_SESSION_API_KEY` | Session API key to send when the backend requires one | +| `VITE_WORKING_DIR` | Workspace path used for new conversations; defaults to the current checkout | +| `VITE_WORKER_URLS` | Optional worker URLs for Browser integrations | +| `VITE_ENABLE_BROWSER_TOOLS` | Disable browser tools for new conversations when set to `false` | +| `VITE_LOAD_PUBLIC_SKILLS` | Enable loading public skills when set to `true` | +| `VITE_FRONTEND_PORT` | Frontend dev server port | +| `VITE_USE_TLS` | Use HTTPS or WSS for the dev proxy | +| `VITE_INSECURE_SKIP_VERIFY` | Skip TLS verification for proxied backend requests | +| `VITE_MOCK_API` | Enable mock API responses | + +## Advanced Source Overrides + +The development stack also supports source and version overrides for the agent server: + +- `OH_AGENT_SERVER_LOCAL_PATH` +- `OH_AGENT_SERVER_GIT_REF` +- `OH_AGENT_SERVER_VERSION` + +When more than one is set, the effective precedence is local source path, then git ref, then pinned version. + +These are useful when you are developing Agent Canvas alongside a local `software-agent-sdk` checkout. + +## Learn More + +- [Agent Canvas Repository](https://github.com/OpenHands/agent-canvas) +- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting) diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx new file mode 100644 index 00000000..d5665111 --- /dev/null +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -0,0 +1,49 @@ +--- +title: LLM Profiles and Model Configuration +description: Configure models in Agent Canvas and use saved LLM profiles during conversations. +--- + +Agent Canvas supports configuring your LLM provider, model, and credentials from the UI. It also supports saved **LLM profiles**, which make it easier to switch models without re-entering provider settings each time. + +## Where to Configure Models + +Open `Settings > LLM` to: + +- choose a provider +- select or enter a model +- add the required API key +- save reusable LLM profiles + +## Working with LLM Profiles + +LLM profiles are useful when you want different model setups for different tasks, such as: + +- a fast profile for iteration +- a stronger profile for planning or review +- a local model profile for offline experiments + +## Switching Profiles in a Conversation + +You can switch profiles from the chat input with the `/model` command: + +- `/model` — list the saved profiles available to the conversation +- `/model ` — switch to a specific saved profile + +Agent Canvas also shows model-switch events in the conversation timeline so you can see when a profile changed during a task. + + + LLM profiles are fully supported in Agent Canvas and are still rolling out in OpenHands Cloud. If you connect Agent Canvas to a cloud backend, profiles you configure in Agent Canvas may be available there before the same profiles appear in the hosted OpenHands Cloud UI for your account. + + +## Recommended Workflow + +1. Configure a default profile in `Settings > LLM`. +2. Create additional profiles for specific tasks or cost levels. +3. Start a conversation. +4. Use `/model` when you want to switch profiles without leaving the chat. + +## Related Guides + +- [Setup](/openhands/usage/agent-canvas/setup) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +- [LLM Settings](/openhands/usage/settings/llm-settings) diff --git a/openhands/usage/agent-canvas/overview.mdx b/openhands/usage/agent-canvas/overview.mdx new file mode 100644 index 00000000..5d79fa45 --- /dev/null +++ b/openhands/usage/agent-canvas/overview.mdx @@ -0,0 +1,56 @@ +--- +title: Agent Canvas Overview +description: Run OpenHands through the Agent Canvas UI and connect to local or remote backends. +--- + +The **Agent Canvas** is the Beta UI for running OpenHands from your own machine or against backends you manage. It gives you one place to start conversations, switch backends, configure models, manage MCP servers, and work with automations. + + + Agent Canvas is in Beta. Expect the install path, packaging, and some UI details to keep evolving. + + +## Why Agent Canvas + +- **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. + + + + ![Choose your agent — OpenHands, Claude Code, Codex, or Gemini CLI](/openhands/static/img/agent-canvas-setup-step-1.png) + + + ![Check your backend connection](/openhands/static/img/agent-canvas-setup-step-2.png) + + + ![Select an LLM provider and model](/openhands/static/img/agent-canvas-setup-step-3.png) + + + ![Pick a pre-built workflow template](/openhands/static/img/agent-canvas-setup-step-4.png) + + + +## Key Concepts + +| 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. | + +## How It Fits with Other OpenHands Products + +- **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. + +## Where to Start + +- [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. +- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting) — Run Agent Canvas on a VM or other dedicated machine. diff --git a/openhands/usage/agent-canvas/prebuilt-automations.mdx b/openhands/usage/agent-canvas/prebuilt-automations.mdx new file mode 100644 index 00000000..acf24bd6 --- /dev/null +++ b/openhands/usage/agent-canvas/prebuilt-automations.mdx @@ -0,0 +1,65 @@ +--- +title: Setup a Pre-built Automation +description: Get started quickly with a pre-built automation for common workflows. +--- + +Agent Canvas ships with a set of pre-built automations for the most common agent workflows. Each one is a ready-to-use starting point — pick the one that fits your use case, connect it to the right backend, and you can have an automation running in minutes. + +## Available Pre-built Automations + +| Automation | What It Does | +|------------|-------------| +| [GitHub PR Review Assistant](/openhands/usage/agent-canvas/prebuilt/github-pr-review) | Automatically reviews pull requests and posts feedback as a comment | +| [GitHub Repository Monitor](/openhands/usage/agent-canvas/prebuilt/github-repo-monitor) | Watches a repository for events and triggers agent actions in response | +| [Slack Channel Monitor](/openhands/usage/agent-canvas/prebuilt/slack-channel-monitor) | Listens to a Slack channel and triggers an agent when a message matches a pattern | + +--- + +Agent Canvas can work with the OpenHands automation backend so you can run agents on a schedule or in response to external events. + +## What You Can Do + +In the `Automate` view, you can: + +- Browse existing automations +- Inspect automation configuration and activity +- Enable or disable automations +- Work with recommended automation flows + +## How Creation Flows Usually Start + +The `Automations` view is mainly for browsing and managing automations that already exist. + +In practice, new automation setup often starts in one of two ways: + +- From a conversation, where you ask OpenHands to create an automation for you +- From a recommended automation flow in the `Automations` view + +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) +- [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting) +- [Automations Overview](/openhands/usage/automations/overview) diff --git a/openhands/usage/agent-canvas/prebuilt/github-pr-review.mdx b/openhands/usage/agent-canvas/prebuilt/github-pr-review.mdx new file mode 100644 index 00000000..d83ffbc3 --- /dev/null +++ b/openhands/usage/agent-canvas/prebuilt/github-pr-review.mdx @@ -0,0 +1,115 @@ +--- +title: GitHub PR Review Assistant +description: Automatically review pull requests using an OpenHands agent. +--- + +Use the GitHub PR Review Assistant when you want Agent Canvas to watch pull requests and have an OpenHands agent review them. + +The setup has two parts: + +- Give the active backend access to GitHub +- Start the pre-built PR review workflow from `Automate` + +## Prerequisites + +Before you start, make sure you have: + +- Agent Canvas installed and running +- An LLM configured for the backend that will run the automation +- Access to create a GitHub token for the repository you want to review +- Access to install MCP servers and save secrets in Agent Canvas + +If you are new to Agent Canvas, start with [Install](/openhands/usage/agent-canvas/setup) . + +## Create a GitHub Access Token + +1. Go to [GitHub Developer Settings](https://github.com/settings/tokens). +2. Click `Generate new token`. +3. Prefer a fine-grained personal access token if your organization supports it. +4. Give the token a clear name, such as `Agent Canvas PR Reviewer`. +5. Select repository access: + - Choose `Only select repositories` for the safest setup. + - Choose `All repositories` only if the automation needs broad access. +6. Set an expiration date that matches your team's security policy. + +## Add Repository Permissions + +In the token setup screen, grant the permissions the reviewer needs. + +For a PR review automation, use: + +| Permission | Access | +|------------|--------| +| `Contents` | Read and write | +| `Issues` | Read and write | +| `Pull requests` | Read and write | +| `Metadata` | Read-only | +| `Actions` | Read-only, if the automation should inspect CI results | +| `Checks` | Read-only, if the automation should inspect check runs | + +Then click `Generate token` and copy the token immediately. + + + GitHub only shows the token once. Store it somewhere secure until you finish configuring Agent Canvas. + + +## Add the GitHub MCP Server + +The GitHub MCP server gives the agent tools for reading repositories, inspecting pull requests, and posting review output. + +1. In Agent Canvas, check the backend switcher in the bottom-left corner. +2. Make sure the active backend is the backend where you want the PR review automation to run. +3. Open `Customize`. +4. Open `MCP Servers`. +5. Select `GitHub` from the MCP library. +6. Paste the GitHub token you created earlier. +7. Save the MCP server configuration. + +## Add the GitHub Token as a Secret + +Some automations also need the token available as a backend secret, especially when the agent runs GitHub commands or accesses private repositories. + +1. Open `Settings`. +2. Open `Secrets`. +3. Click `Add a new Secret`. +4. Set the secret name to `GITHUB_TOKEN`. +5. Paste the GitHub token as the secret value. +6. Save the secret. + +## Start the PR Review Workflow + +1. Open `Automate` in the left navigation. +2. Find `Start from a proven workflow`. +3. Choose the GitHub PR review workflow. +4. Agent Canvas opens a new conversation with a prefilled setup prompt. +5. Send the prompt as-is, or edit it first if you already know what you want. + +After you send the prompt, the agent starts a setup conversation. It uses the preconfigured skills and GitHub access to interview you, clarify the review workflow, and create the automation. + +## Customize the Review + +You do not need to know every detail before sending the prefilled prompt. The agent will ask follow-up questions to clarify: + +- The repository owner and name +- Which pull requests to review +- Whether the agent should post a single summary comment or detailed inline feedback +- Whether the agent should inspect CI results before commenting +- Any files, directories, or checks the reviewer should ignore + +You can edit the prefilled prompt before sending it if you want to provide any of those details up front. + +## Verify the Automation + +After the automation is created: + +1. Open `Automate`. +2. Confirm the new automation appears in the list. +3. Open the automation details and check that it is enabled. +4. Trigger or wait for a matching pull request event. +5. Confirm that the agent run appears and that the review is posted to GitHub. + +## Related Guides + +- [GitHub Repository Monitor](/openhands/usage/agent-canvas/prebuilt/github-repo-monitor) +- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) diff --git a/openhands/usage/agent-canvas/prebuilt/github-repo-monitor.mdx b/openhands/usage/agent-canvas/prebuilt/github-repo-monitor.mdx new file mode 100644 index 00000000..c22c12d2 --- /dev/null +++ b/openhands/usage/agent-canvas/prebuilt/github-repo-monitor.mdx @@ -0,0 +1,119 @@ +--- +title: GitHub Repository Monitor +description: Monitor a GitHub repository and trigger agent actions on events. +--- + +Use the GitHub Repository Monitor when you want Agent Canvas to watch a repository and trigger an OpenHands agent when matching activity happens. + +Common examples include: + +- Monitoring new issues and pull requests +- Watching failed CI runs +- Checking for dependency or release activity +- Creating follow-up work when a repository changes + +## Prerequisites + +Before you start, make sure you have: + +- Agent Canvas installed and running +- An LLM configured for the backend that will run the automation +- Access to create a GitHub token for the repository you want to monitor +- Access to install MCP servers and save secrets in Agent Canvas + +If you are new to Agent Canvas, start with [Install](/openhands/usage/agent-canvas/setup) . + +## Create a GitHub Access Token + +1. Go to [GitHub Developer Settings](https://github.com/settings/tokens). +2. Click `Generate new token`. +3. Prefer a fine-grained personal access token if your organization supports it. +4. Give the token a clear name, such as `Agent Canvas Repo Monitor`. +5. Select repository access: + - Choose `Only select repositories` for the safest setup. + - Choose `All repositories` only if the automation needs broad access. +6. Set an expiration date that matches your team's security policy. + +## Add Repository Permissions + +In the token setup screen, grant only the permissions your monitor needs. + +For most repository monitors, start with: + +| Permission | Access | +|------------|--------| +| `Contents` | Read-only, or read and write if the agent will open changes | +| `Issues` | Read and write if the agent will triage or comment on issues | +| `Pull requests` | Read and write if the agent will inspect or comment on pull requests | +| `Metadata` | Read-only | +| `Actions` | Read-only, if the automation should inspect workflow runs | +| `Checks` | Read-only, if the automation should inspect check runs | + +Then click `Generate token` and copy the token immediately. + + + If you change token permissions later, you may need to update the token or create a new one. + + +## Add the GitHub MCP Server + +The GitHub MCP server gives the agent tools for reading repository state and taking GitHub actions. + +1. In Agent Canvas, check the backend switcher in the bottom-left corner. +2. Make sure the active backend is the backend where you want the repository monitor to run. +3. Open `Customize`. +4. Open `MCP Servers`. +5. Select `GitHub` from the MCP library. +6. Paste the GitHub token you created earlier. +7. Save the MCP server configuration. + +## Add the GitHub Token as a Secret + +Some automations also need the token available as a backend secret, especially when the agent runs GitHub commands or accesses private repositories. + +1. Open `Settings`. +2. Open `Secrets`. +3. Click `Add a new Secret`. +4. Set the secret name to `GITHUB_TOKEN`. +5. Paste the GitHub token as the secret value. +6. Save the secret. + +## Start the Repository Monitor Workflow + +1. Open `Automate` in the left navigation. +2. Find `Start from a proven workflow`. +3. Choose the GitHub repository monitor workflow. +4. Agent Canvas opens a new conversation with a prefilled setup prompt. +5. Send the prompt as-is, or edit it first if you already know what you want. + +After you send the prompt, the agent starts a setup conversation. It uses the preconfigured skills and GitHub access to interview you, clarify the monitoring workflow, and create the automation. + +## Customize the Monitor + +You do not need to know every detail before sending the prefilled prompt. The agent will ask follow-up questions to clarify: + +- The repository owner and name +- The events or conditions the monitor should watch +- How often the automation should check the repository, if it is schedule-based +- What the agent should do when it finds a match +- Where the agent should report results, such as a GitHub comment or Slack channel + +You can edit the prefilled prompt before sending it if you want to provide any of those details up front. + +For example, you can ask the monitor to watch for failed workflow runs, summarize the failure, and open a pull request when the fix is straightforward. + +## Verify the Automation + +After the automation is created: + +1. Open `Automate`. +2. Confirm the new automation appears in the list. +3. Open the automation details and check that it is enabled. +4. Trigger or wait for matching repository activity. +5. Confirm that the agent run appears and performs the action you requested. + +## Related Guides + +- [GitHub PR Review Assistant](/openhands/usage/agent-canvas/prebuilt/github-pr-review) +- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) diff --git a/openhands/usage/agent-canvas/prebuilt/slack-channel-monitor.mdx b/openhands/usage/agent-canvas/prebuilt/slack-channel-monitor.mdx new file mode 100644 index 00000000..c7f04664 --- /dev/null +++ b/openhands/usage/agent-canvas/prebuilt/slack-channel-monitor.mdx @@ -0,0 +1,144 @@ +--- +title: Slack Channel Monitor +description: Watch a Slack channel and trigger agent actions on messages. +--- + +Use the Slack Channel Monitor when you want Agent Canvas to watch a Slack channel and trigger an OpenHands agent when a message matches your instructions. + +Common examples include: + +- Responding when someone mentions a support keyword +- Turning bug reports into GitHub issues +- Summarizing incidents from an alerts channel +- Running a repository task from a Slack request + +## Prerequisites + +Before you start, make sure you have: + +- Agent Canvas installed and running +- An LLM configured for the backend that will run the automation +- Permission to create and install a Slack app in your workspace +- Access to install MCP servers and save secrets in Agent Canvas + +If you are new to Agent Canvas, start with [Install](/openhands/usage/agent-canvas/setup) . + +## Create the Slack App + +1. Go to the [Slack API dashboard](https://api.slack.com/apps). +2. Click `Create New App`. +3. Select `From scratch`. +4. Enter an app name, such as `OpenHands`. +5. Choose the workspace where you want to install the bot. +6. Click `Create App`. + +## Add Bot Token Scopes + +Before Slack gives you a bot token, you need to define what the bot is allowed to do. + +1. In the Slack app settings, open `OAuth & Permissions`. +2. Scroll to `Scopes`. +3. Under `Bot Token Scopes`, click `Add an OAuth Scope`. +4. Add the scopes required by the Slack MCP server and your monitor. + +For a channel monitor, add these bot token scopes: + +| Scope | Purpose | +|-------|---------| +| `app_mentions:read` | View messages that directly mention the app in conversations it belongs to | +| `channels:read` | List and read public channel metadata | +| `channels:history` | Read messages from public channels | +| `chat:write` | Send messages as the app | +| `emoji:read` | View custom emoji in the workspace | +| `groups:history` | Read messages from private channels the app has been added to | +| `reactions:read` | View emoji reactions and associated message content | +| `reactions:write` | Add and edit emoji reactions | +| `users:read` | Resolve Slack users and profiles | + + + Slack may require you to reinstall the app after changing scopes. + + +## Install the App and Copy the Bot Token + +1. Stay on the `OAuth & Permissions` page. +2. Click `Install to Workspace`. +3. Review the requested permissions. +4. Click `Allow`. +5. Copy the `Bot User OAuth Token` from the `OAuth Tokens` section. + +## Invite the Bot to Channels + +The bot does not automatically join channels. + +Invite it to every channel you want the automation to monitor. The Agent Canvas backend can only watch channels the bot can access. + +## Find Your Slack Workspace ID + +The Slack MCP server also needs your workspace ID. + +You can find it from your Slack URL or workspace settings. See Slack's guide to [locating your Slack URL or ID](https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID). + +## Add the Slack MCP Server + +The Slack MCP server gives the agent tools for reading Slack channel activity and posting responses. + +1. In Agent Canvas, check the backend switcher in the bottom-left corner. +2. Make sure the active backend is the backend where you want the Slack monitor to run. +3. Open `Customize`. +4. Open `MCP Servers`. +5. Select `Slack` from the MCP library. +6. Paste the bot token. +7. Enter your Slack workspace ID. +8. Save the MCP server configuration. + +## Add the Slack Bot Token as a Secret + +Some automations also need the token available as a backend secret. + +1. Open `Settings`. +2. Open `Secrets`. +3. Click `Add a new Secret`. +4. Set the secret name to `SLACK_BOT_TOKEN`. +5. Paste the bot token as the secret value. +6. Save the secret. + +## Start the Slack Channel Monitor Workflow + +1. Open `Automate` in the left navigation. +2. Find `Start from a proven workflow`. +3. Choose the Slack channel monitor workflow. +4. Agent Canvas opens a new conversation with a prefilled setup prompt. +5. Send the prompt as-is, or edit it first if you already know what you want. + +After you send the prompt, the agent starts a setup conversation. It uses the preconfigured skills and Slack access to interview you, clarify the channel monitor, and create the automation. + +## Customize the Monitor + +You do not need to know every detail before sending the prefilled prompt. The agent will ask follow-up questions to clarify: + +- The Slack channel or channels to monitor +- The message pattern, keyword, or mention that should trigger the agent +- What the agent should do when a message matches +- Whether the agent should reply in Slack +- Any GitHub repository or external service the agent should use + +You can edit the prefilled prompt before sending it if you want to provide any of those details up front. + +For example, you can ask the monitor to watch an alerts channel, summarize new incidents, and create a GitHub issue when a message includes a production error. + +## Verify the Automation + +After the automation is created: + +1. Open `Automate`. +2. Confirm the new automation appears in the list. +3. Open the automation details and check that it is enabled. +4. Post a test message in a channel the bot has joined. +5. Confirm that the agent run appears and performs the action you requested. + +## Related Guides + +- [GitHub Repository Monitor](/openhands/usage/agent-canvas/prebuilt/github-repo-monitor) +- [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) diff --git a/openhands/usage/agent-canvas/self-hosting.mdx b/openhands/usage/agent-canvas/self-hosting.mdx new file mode 100644 index 00000000..aa938f77 --- /dev/null +++ b/openhands/usage/agent-canvas/self-hosting.mdx @@ -0,0 +1,54 @@ +--- +title: Self-Hosting Agent Canvas +description: Run Agent Canvas on your own machine or VM and secure it before exposing it to a network. +--- + +Self-hosting Agent Canvas lets you keep the UI, agent server, and automation backend on infrastructure you control. + + + Anyone who can reach your Agent Canvas deployment can potentially drive an agent that reads files, runs shell commands, and accesses the network. Lock down the host before exposing it to anyone else. + + +## Quick Start + +1. Provision a Linux or macOS machine and [install Agent Canvas](/openhands/usage/agent-canvas/setup). +2. Lock down the network firewall — only SSH inbound from your IP. +3. Start in **public mode**: + +```bash +LOCAL_BACKEND_API_KEY= agent-canvas --public +``` + +The `--public` flag means the API key is **not** baked into the frontend. Anyone who opens the UI must enter the key before they can interact with the agent. All services bind to `127.0.0.1` by default. + + + Without `--public`, the key is auto-injected into the frontend — convenient for local-only use, but unsafe when the deployment is reachable by others. + + +## Security Checklist + +Before you expose Agent Canvas to a broader network: + +1. **Restrict inbound network access** — only open ports you need (SSH, and 80/443 if using a reverse proxy). +2. **Use `--public` mode** with a strong `LOCAL_BACKEND_API_KEY` so every user must authenticate in the UI. +3. **Use TLS** — put a reverse proxy like nginx in front with Let's Encrypt if the UI is internet-reachable. +4. **Treat the host as sensitive infrastructure** — it stores secrets, conversations, and working copies. + +## Reverse Proxy (Optional) + +If you want browser access beyond localhost (e.g. from a phone or another machine), put nginx in front for TLS termination. Authentication is handled by `--public` mode at the application layer, so nginx only needs to terminate TLS — no `auth_basic` configuration required. + +See the [detailed VM hardening walkthrough](https://github.com/OpenHands/agent-canvas/blob/main/docs/SELF_HOSTING.md) for a complete nginx + Let's Encrypt setup. + +## Connecting from Another Machine + +You do not need to run the UI and the backend on the same computer: + +- **Direct access** — open the UI on the remote host through a reverse proxy or SSH tunnel. +- **Add as a backend** — keep Agent Canvas on your laptop and add the remote machine through **Manage Backends**, using `LOCAL_BACKEND_API_KEY` as the session API key. + +## Related Guides + +- [Install](/openhands/usage/agent-canvas/setup) +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx new file mode 100644 index 00000000..c3d89d33 --- /dev/null +++ b/openhands/usage/agent-canvas/setup.mdx @@ -0,0 +1,87 @@ +--- +title: Install +description: Install and run Agent Canvas via npm or Docker. +--- + + + Agent Canvas starts an agent server on the machine where you run it. Treat that machine as trusted infrastructure and review the guidance in [Self-Hosting Agent Canvas](/openhands/usage/agent-canvas/self-hosting) before exposing it to a network you do not control. + + + + + **Prerequisites:** [Node.js](https://nodejs.org/en/download) 22.12 or later, `npm`, and [`uv`](https://docs.astral.sh/uv/getting-started/installation/). + + **Install:** + ```bash + npm install -g @openhands/agent-canvas + ``` + + **Run:** + ```bash + agent-canvas + ``` + + By default, Agent Canvas starts on `http://localhost:8000`. + + ### CLI Flags + + | Flag | Description | + |------|-------------| + | `-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 [Self-Hosting](/openhands/usage/agent-canvas/self-hosting). | + | `-v`, `--version` | Show the version number | + | `--info` | Show the version and default stack configuration (agent server version, ports, etc.) | + | `-h`, `--help` | Show the built-in help output | + + ### Environment Variables + + | Variable | Purpose | + |----------|---------| + | `LOCAL_BACKEND_API_KEY` | API key for the server. Required in `--public` mode; optional otherwise (auto-generated and persisted across restarts). | + | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | + | `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version (e.g. `0.1.0`) | + + + **Prerequisites:** [Docker](https://docs.docker.com/get-docker/). + + A Docker image is available that sandboxes the entire Agent Canvas stack. Mount your project files and a persistence directory for settings, secrets, and conversation history: + + ```bash + docker run -it --rm \ + -p 8000:8000 \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest + ``` + + ### Environment Variables + + Configuration is passed via `-e` flags on `docker run`: + + | Variable | Purpose | + |----------|---------| + | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | + | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | + | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | + + + + + If you want to clone the repository, run custom dev modes, or configure Vite-specific environment variables, use the [Contribute / Development guide](/openhands/usage/agent-canvas/development) instead. + + +## First Steps After Launch + +After the UI opens: + +1. Confirm the default local backend is healthy. +2. Open `Settings > LLM` and configure a provider, model, and API key. +3. Open `Customize` if you want to add skills or MCP servers. +4. Return to the home screen and enter a prompt to start your first conversation. +5. If you want the conversation tied to a local folder, choose `Open Workspace` first. + +## Next Steps + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) +- [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) diff --git a/openhands/usage/agent-canvas/troubleshooting.mdx b/openhands/usage/agent-canvas/troubleshooting.mdx new file mode 100644 index 00000000..a55d9cc4 --- /dev/null +++ b/openhands/usage/agent-canvas/troubleshooting.mdx @@ -0,0 +1,65 @@ +--- +title: Troubleshooting +description: Common Agent Canvas setup and runtime issues, plus places to ask for help. +--- + +Use this page for the most common Agent Canvas problems. + +## Command Not Found + +If `agent-canvas` is not available after installation: + +- confirm the package installed successfully with `npm install -g @openhands/agent-canvas` +- make sure your npm global bin directory is on your `PATH` +- run `agent-canvas --help` to confirm the binary resolves correctly + +## Missing `uv` + +Agent Canvas relies on `uv` to run the local agent server stack. + +If startup fails because `uv` or `uvx` is missing, install it from the official guide: + +- [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) + +## Port Already in Use + +Agent Canvas listens on port `8000` by default. If that port is busy, start it on another one: + +```bash +agent-canvas --port 3000 +``` + +## Backend Is Unreachable + +If Agent Canvas cannot talk to the active backend: + +- open `Manage Backends` +- verify the backend host or base URL +- verify the API key if the backend requires one +- switch to another backend to confirm the issue is backend-specific + +## LLM Profiles Do Not Match OpenHands Cloud + +Agent Canvas currently has fuller support for LLM profiles than the hosted OpenHands Cloud UI. + +If profiles appear in Agent Canvas but not in OpenHands Cloud directly, that can be expected while the Cloud rollout is still in progress. + +## MCP Settings Are Missing + +MCP configuration does not live under `Settings`. + +Open the top-level `Customize` area, then go to `MCP Servers`. + +## Automation Features Are Unavailable + +If the `Automations` view shows an unavailable or unhealthy state, the active backend may not have a working automation service. + +Start with the default local backend to confirm the UI works, then debug the remote backend separately. + +## Get Help + +If you are still stuck: + +- [Join the OpenHands Slack community](https://openhands.dev/joinslack) +- [Open an issue in the Agent Canvas repository](https://github.com/OpenHands/agent-canvas/issues) +- [Browse the Agent Canvas source](https://github.com/OpenHands/agent-canvas) diff --git a/overview/introduction.mdx b/overview/introduction.mdx index 9f510db4..0a280785 100644 --- a/overview/introduction.mdx +++ b/overview/introduction.mdx @@ -7,31 +7,13 @@ description: Welcome to OpenHands, a community focused on AI-driven development There are a few ways to work with OpenHands: -## OpenHands Software Agent SDK -The SDK is a composable Python library that contains all of our agentic tech. It's the engine that powers everything else below. - -Define agents in code, then run them locally, or scale to 1000s of agents in the cloud - -[Check out the docs](https://docs.openhands.dev/sdk) or [view the source](https://github.com/All-Hands-AI/agent-sdk/) - -## OpenHands CLI -The CLI is the easiest way to start using OpenHands. The experience will be familiar to anyone who has worked -with e.g. Claude Code or Codex. You can power it with Claude, GPT, or any other LLM. - -[Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/cli-mode) or [view the source](https://github.com/OpenHands/OpenHands-CLI) +## Agent Canvas +Agent Canvas is a browser-based UI and backend server for running agents and automations. A single `agent-canvas` command starts the full stack locally. Self-host on a VM, or connect to OpenHands Cloud. -## OpenHands Local GUI -Use the Local GUI for running agents on your laptop. It comes with a REST API and a single-page React application. -The experience will be familiar to anyone who has used Devin or Jules. - -[Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/local-setup) or view the source in this repo. +[Check out the docs](/openhands/usage/agent-canvas/overview) or [view the source](https://github.com/OpenHands/agent-canvas) ## OpenHands Cloud -This is a commercial deployment of OpenHands GUI, running on hosted infrastructure. - -You can try it with a free by [signing in with your GitHub account](https://app.all-hands.dev). - -OpenHands Cloud comes with source-available features and integrations: +A fully managed version of OpenHands with source-available features and integrations: - Deeper integrations with GitHub, GitLab, and Bitbucket - Integrations with Slack, Jira, and Linear - Multi-user support @@ -40,6 +22,8 @@ OpenHands Cloud comes with source-available features and integrations: - Usage reporting - Budgeting enforcement +Try it free by [signing in with your GitHub account](https://app.all-hands.dev). + ## OpenHands Enterprise Large enterprises can work with us to self-host OpenHands Cloud in their own VPC, via Kubernetes. OpenHands Enterprise can also work with the CLI and SDK above. @@ -51,6 +35,29 @@ Enterprise contracts also come with extended support and access to our research Learn more at [openhands.dev/enterprise](https://openhands.dev/enterprise) +## OpenHands Software Agent SDK +The SDK is a composable Python library that contains all of our agentic tech. It's the engine that powers everything else. + +Define agents in code, then run them locally, or scale to 1000s of agents in the cloud. + +[Check out the docs](https://docs.openhands.dev/sdk) or [view the source](https://github.com/All-Hands-AI/agent-sdk/) + +## Legacy + + + **OpenHands CLI** + + The CLI is a terminal-based interface for running OpenHands agents. You can power it with Claude, GPT, or any other LLM. + + [Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/cli-mode) or [view the source](https://github.com/OpenHands/OpenHands-CLI) + + **OpenHands Local GUI** + + A legacy UI requiring Docker for running agents on your laptop. It comes with a REST API and a single-page React application. + + [Check out the docs](https://docs.openhands.dev/openhands/usage/run-openhands/local-setup) or view the source in this repo. + + ## Everything Else Check out our [Product Roadmap](https://github.com/orgs/openhands/projects/1), and feel free to diff --git a/overview/quickstart.mdx b/overview/quickstart.mdx index 843e997f..69750ba1 100644 --- a/overview/quickstart.mdx +++ b/overview/quickstart.mdx @@ -3,30 +3,12 @@ title: Quick Start description: Choose how you want to run OpenHands --- -Get started with OpenHands in minutes. Choose the option that works best for you. +Get started with OpenHands in minutes. - - - **Recommended** - - The fastest way to get started. No setup required—just sign in and start coding. - - - Free usage of MiniMax M2.5 for a limited time - - No installation needed - - Managed infrastructure - - - Use OpenHands from your terminal. Perfect for automation and scripting. - - - IDE integrations available - - Headless mode for CI/CD - - Lightweight installation - - - Run OpenHands locally with a web-based interface. Bring your own LLM and API key. - - - Full control over your environment - - Works offline - - Docker-based setup + + + The recommended way to run OpenHands. Install via npm and start your first conversation in minutes. + +- [OpenHands Cloud](https://app.all-hands.dev) — no installation required, just sign in and start coding