diff --git a/docs.json b/docs.json index 1a6784c5..0675373a 100644 --- a/docs.json +++ b/docs.json @@ -20,7 +20,7 @@ "navigation": { "tabs": [ { - "tab": "Documentation", + "tab": "Home", "pages": [ { "group": "Get Started", @@ -40,16 +40,23 @@ ] }, { - "group": "Onboarding OpenHands", + "group": "Use Cases", "pages": [ - "openhands/usage/customization/repository", - "openhands/usage/customization/hooks" + "openhands/usage/use-cases/overview", + "openhands/usage/use-cases/vulnerability-remediation", + "openhands/usage/use-cases/code-review", + "openhands/usage/use-cases/qa-changes", + "openhands/usage/use-cases/incident-triage", + "openhands/usage/use-cases/cobol-modernization", + "openhands/usage/use-cases/dependency-upgrades", + "openhands/usage/use-cases/spark-migrations" ] }, { "group": "Product Guides", "pages": [ "openhands/usage/key-features", + "openhands/usage/customization/hooks", "overview/model-context-protocol", { "group": "Skills", @@ -74,6 +81,7 @@ "openhands/usage/automations/managing-automations" ] }, + "openhands/usage/customization/repository", { "group": "Settings", "pages": [ @@ -190,21 +198,34 @@ ] }, { - "tab": "Use Cases", + "tab": "Agent Canvas", "pages": [ - "openhands/usage/use-cases/overview", + "openhands/usage/agent-canvas/overview", + "openhands/usage/agent-canvas/setup", + "openhands/usage/agent-canvas/first-time-setup", { - "group": "Use Cases", + "group": "Pre-built Automations", "pages": [ - "openhands/usage/use-cases/vulnerability-remediation", - "openhands/usage/use-cases/code-review", - "openhands/usage/use-cases/qa-changes", - "openhands/usage/use-cases/incident-triage", - "openhands/usage/use-cases/cobol-modernization", - "openhands/usage/use-cases/dependency-upgrades", - "openhands/usage/use-cases/spark-migrations" + "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": "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/development", + "openhands/usage/agent-canvas/troubleshooting" ] }, { @@ -524,6 +545,10 @@ ] }, "redirects": [ + { + "source": "/openhands/usage/agent-canvas/self-hosting", + "destination": "/openhands/usage/agent-canvas/backend-setup/vm" + }, { "source": "/modules/:slug*", "destination": "/:slug*" 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..11a13595 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/cloud.mdx @@ -0,0 +1,43 @@ +--- +title: Cloud Backend +description: Connect Agent Canvas to OpenHands Cloud for on-demand sandboxed execution. +--- + +You can connect Agent Canvas to [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) as a backend. Conversations and automations then run in OpenHands Cloud's on-demand sandboxes instead of on your local machine. + +## When to Use It + +A Cloud backend is a good fit when you want to: + +- Run agents without tying up local resources +- Use OpenHands Cloud's managed sandboxes and integrations +- Keep your local machine for development while offloading agent work + +## Prerequisites + +- An [OpenHands Cloud](https://app.all-hands.dev) account +- Agent Canvas installed — see [Setup](/openhands/usage/agent-canvas/setup) + +## Add a Cloud Backend + +1. Open Agent Canvas and click the backend switcher in the top bar. +2. Choose **Manage Backends** → **Add Backend**. +3. Click **Login with OpenHands Cloud** and sign in with your account. + +Once connected, select it as the active backend. Conversations will now run in OpenHands Cloud. + +### OpenHands Enterprise + +If your organization runs OpenHands Enterprise, click **Advanced** in the Add Backend flow and enter your enterprise host URL before signing in. + +## What's Different with a Cloud Backend + +- **Sandboxed execution** — each conversation runs in an isolated cloud sandbox rather than on your host filesystem. +- **Cloud integrations** — GitHub, GitLab, Bitbucket, Slack, and other integrations configured in OpenHands Cloud are available. +- **Settings are per-backend** — LLM configuration, secrets, and MCP servers saved against the Cloud backend are independent from your local backend settings. + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) +- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local) 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..87d349a0 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -0,0 +1,63 @@ +--- +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. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) installed and running +- Agent Canvas installed locally (if connecting from another instance) — see [Setup](/openhands/usage/agent-canvas/setup) + +## Run the Official Image + +Mount a persistence directory for settings, secrets, and conversation history, and a projects directory for workspace access: + +```bash +docker run -it --rm \ + -p 8000:8000 \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest +``` + +Agent Canvas is now running at `http://localhost:8000`. The agent can access any project under the mounted `/projects` path. + +### 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. | + + + The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set `LOCAL_BACKEND_API_KEY` to a strong secret. + + +## Connect from the Frontend + +Start the frontend separately and point it at the container: + +```bash +agent-canvas --frontend-only +``` + +Then add the Docker backend: + +1. Click the backend switcher → **Manage Backends** → **Add Backend**. +2. Fill in: + - **Name** — e.g. `docker-backend` + - **Host / Base URL** — `http://localhost:8000` + - **API Key** — the `LOCAL_BACKEND_API_KEY` value (check container logs if auto-generated) +3. Save and select it as the active backend. + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local) +- [VM Backend](/openhands/usage/agent-canvas/backend-setup/vm) +- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) 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..69ca4347 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/local.mdx @@ -0,0 +1,53 @@ +--- +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. + +## Start a Backend + +```bash +agent-canvas --backend-only +``` + +This starts the agent server and automation backend on `127.0.0.1:8000`. No frontend is served. + +## Running Multiple Backends + +You can run several backends at the same time on different ports — for example, one per project or toolchain: + +```bash +agent-canvas --backend-only --port 8001 +agent-canvas --backend-only --port 8002 +agent-canvas --backend-only --port 8003 +``` + +Each instance gets its own agent server, automation backend, and ingress proxy. + +## Connect the Frontend + +Start the frontend separately: + +```bash +agent-canvas --frontend-only +``` + +Then add your backends through **Manage Backends**: + +1. Click the backend switcher → **Manage Backends** → **Add Backend**. +2. Fill in the **Host / Base URL** (e.g. `http://localhost:8001`) and **API Key**. +3. Repeat for each backend you started. + +Switch between them from the backend selector depending on what you're working on. + + + If you just want a quick single-machine setup, running `agent-canvas` without any flags starts the full stack (frontend + backend) on one port. The split approach above is useful when you want multiple backends or want to keep the frontend and backends on separate processes. + + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [VM Backend](/openhands/usage/agent-canvas/backend-setup/vm) — headless backend on a remote machine +- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) — backend on a remote machine +- [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) — run in a container 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..834ab19e --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/vm.mdx @@ -0,0 +1,170 @@ +--- +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`. + + + The agent server can read and write the host filesystem, execute shell commands, and access the network. Lock down the machine before starting. + + +## 1. Provision and Secure the Machine + +Any always-on Linux or macOS host: + +- **Cloud VM** — Ubuntu 24.04 LTS, 2 vCPU / 4 GB RAM is enough for a single user. +- **Dedicated hardware** — Mac Mini, Intel NUC, spare laptop. + +Lock down inbound traffic **before** starting the backend: + +- **Port 22 (SSH)** — your IP or VPN CIDR only. +- **Everything else** — drop. + +## 2. Install Prerequisites + +On Ubuntu: + +```bash +apt-get update && apt-get install -y curl git + +# Node.js 22.x (via nvm, asdf, or NodeSource) +# uv (for the agent server runtime): +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +On macOS, install Node and `uv` via Homebrew instead. + +## 3. Start the Backend + +```bash +LOCAL_BACKEND_API_KEY= npx @openhands/agent-canvas --backend-only --public +``` + +- `--backend-only` starts only the agent server and automation backend (no frontend). +- `--public` requires `LOCAL_BACKEND_API_KEY` — every API request must carry a matching `X-Session-API-Key` header. + + + To also serve the UI from the VM (e.g. to access it from a phone), drop `--backend-only`. With the full stack, `--public` requires users to enter the API key in the UI before interacting with the agent. + + +## 4. Connect from Your Local Machine + +On your laptop, start the frontend: + +```bash +agent-canvas --frontend-only +``` + +Then add the VM as a backend: + +1. Click the backend switcher → **Manage Backends** → **Add Backend**. +2. Fill in: + - **Name** — e.g. `my-vm` + - **Host / Base URL** — `http://localhost:8000` (if using an SSH tunnel) or the VM's URL if you've set up a reverse proxy + - **API Key** — the `LOCAL_BACKEND_API_KEY` from step 3 +3. Save and select it as the active backend. + +### Using an SSH Tunnel + +The simplest way to reach the backend without exposing ports: + +```bash +ssh -L 8000:127.0.0.1:8000 user@your-vm +``` + +Then use `http://localhost:8000` as the backend URL. + +## 5. (Optional) Add a Domain with nginx + TLS + +If you want direct HTTPS access without an SSH tunnel, point a domain at the machine and front it with nginx + Let's Encrypt. + +### Point a Domain at the Machine + +Create an `A` record pointing to the machine's public IP (e.g. `canvas.example.com`): + +```bash +dig +short canvas.example.com +``` + +### Open Ports 80 and 443 + +Update your network firewall to additionally allow: + +- **Port 80 (HTTP)** — open to `0.0.0.0/0` (required for Let's Encrypt HTTP-01 challenges). nginx redirects all HTTP to HTTPS. +- **Port 443 (HTTPS)** — restrict to your IP if possible. If you need it world-open, `LOCAL_BACKEND_API_KEY` is your primary defense. + +### Install nginx and Certbot + +```bash +apt-get install -y nginx certbot python3-certbot-nginx +``` + +### Configure nginx + +Save this at `/etc/nginx/sites-available/canvas.example.com`, replacing the domain: + +```nginx +server { + listen 80; + listen [::]:80; + server_name canvas.example.com; + + location /.well-known/acme-challenge/ { + root /var/www/html; + } + + location / { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket / SSE support — required for live agent events. + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_read_timeout 3600s; + proxy_send_timeout 3600s; + } +} +``` + +Enable the site and issue a certificate: + +```bash +ln -sf /etc/nginx/sites-available/canvas.example.com \ + /etc/nginx/sites-enabled/canvas.example.com +nginx -t && systemctl reload nginx + +certbot --nginx -d canvas.example.com \ + --non-interactive --agree-tos \ + --email you@example.com \ + --redirect +``` + +### Verify + +```bash +curl -I https://canvas.example.com/ # → 200 +curl -I http://canvas.example.com/ # → 301 redirect to HTTPS +``` + +Use `https://canvas.example.com` as the **Host / Base URL** when adding the backend in Manage Backends. + +## Security Checklist + +Before exposing the backend to a broader network: + +1. **Restrict inbound network access** — only open ports you need (SSH, 80/443 for the reverse proxy). +2. **Use `--public` mode** with a strong `LOCAL_BACKEND_API_KEY`. +3. **Use TLS** — put a reverse proxy in front with Let's Encrypt if the backend is internet-reachable. +4. **Treat the host as sensitive infrastructure** — it stores secrets, conversations, and working copies. + +## Related Guides + +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Local Backend](/openhands/usage/agent-canvas/backend-setup/local) +- [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) +- [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud) diff --git a/openhands/usage/agent-canvas/backends.mdx b/openhands/usage/agent-canvas/backends.mdx new file mode 100644 index 00000000..7d1fa2ef --- /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) +- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) 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..b7bc37be --- /dev/null +++ b/openhands/usage/agent-canvas/customize-and-settings.mdx @@ -0,0 +1,59 @@ +--- +title: Customize and Settings +description: Teach your agent with skills and MCP servers, and configure how it runs with settings. +--- + +Agent Canvas separates **Customize** from **Settings**. + +- **Customize** — teach the agent new things. **Skills** give it domain knowledge and specific instructions. **MCP Servers** connect it to external tools and data sources. +- **Settings** — configure how the agent runs. Choose your LLM, store secrets, tune context handling, and set agent behavior. Settings are saved per 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. + +## Configuration Is Per Backend + +Both Customize and Settings are tied to the **active backend**. That means: + +- Changing backends changes which configuration you are editing +- Skills, MCP servers, secrets, and other settings saved for one backend do 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..999cd848 --- /dev/null +++ b/openhands/usage/agent-canvas/development.mdx @@ -0,0 +1,20 @@ +--- +title: Contributing +description: Contribute to Agent Canvas development. +--- + +Agent Canvas is open source. To work on it from source: + +1. Clone the repo and install dependencies: + ```bash + git clone https://github.com/OpenHands/agent-canvas.git + cd agent-canvas + npm install + ``` + +2. Start the full development stack: + ```bash + npm run dev + ``` + +For development workflows, environment variables, testing, and advanced configuration, see the [Development Guide](https://github.com/OpenHands/agent-canvas/blob/main/docs/DEVELOPMENT.md) in the repository. diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx new file mode 100644 index 00000000..92221e6b --- /dev/null +++ b/openhands/usage/agent-canvas/first-time-setup.mdx @@ -0,0 +1,69 @@ +--- +title: First Time Setup +description: Configure Agent Canvas after installation — choose your agent, connect a backend, add an LLM, and launch your first automation. +--- + +When you open Agent Canvas for the first time, a four-step setup wizard walks you through the core configuration. Each step can be skipped and revisited later from `Settings`. + +## Step 1: Choose Your Agent + +![Agent Canvas first-time setup — Choose your agent screen showing OpenHands, Claude Code, Codex, and Gemini CLI options](/openhands/static/img/agent-canvas-setup-step-1.png) + +Agent Canvas uses the **Agent-Client Protocol (ACP)** to communicate with agents, which means you're not locked into a single provider. + +- **OpenHands** (selected by default) — the general-purpose OpenHands agent, best for coding and exploration. +- **Claude Code** — Anthropic's Claude Code agent. +- **Codex** — OpenAI's Codex agent. +- **Gemini CLI** — Google's Gemini CLI agent. + +Choosing a third-party agent lets you interact with it through the Agent Canvas interface and bring your existing subscriptions from those providers. + +You can change your agent at any time from `Settings`. + +## Step 2: Check Your Backend + +![Agent Canvas first-time setup — Check your backend screen showing a connected local backend at 127.0.0.1:8000](/openhands/static/img/agent-canvas-setup-step-2.png) + +Agent Canvas routes all conversations through an **agent server backend**. By default, it connects to your local machine (`http://127.0.0.1:8000`), which is ideal for working on local projects. + +The setup screen shows your current backend connection status. If the server is running, you'll see a **"You're connected!"** confirmation. + +Each backend entry stores: + +- A display name (e.g. `Local`) +- A host URL +- An optional API key + + + To add remote or cloud backends, or to manage multiple backend connections, see [Connect and Manage Backends](/openhands/usage/agent-canvas/backends). + + +## Step 3: Set Up Your LLM + +![Agent Canvas first-time setup — Set up your LLM screen showing provider and model selection with an API key field](/openhands/static/img/agent-canvas-setup-step-3.png) + +Agent Canvas supports **bring-your-own LLM key**. Select your LLM provider and model, then paste in your API key. + +Available options: + +- **Direct provider keys** — use your own API key from Anthropic, OpenAI, Google, or any other supported provider. +- **OpenHands Cloud** — use an [OpenHands Cloud](https://app.all-hands.dev) API key to access verified models without managing provider accounts directly. Find your API key in the `API Keys` tab of OpenHands Cloud. + +The setup screen defaults to `OpenHands` as the provider and pre-selects a recommended model. Switch the `LLM Provider` dropdown to choose a different provider. + +## Step 4: Start From a Proven Workflow + +![Agent Canvas first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest](/openhands/static/img/agent-canvas-setup-step-4.png) + +Agent Canvas is designed as an **automation-centric developer control center**. The final setup step invites you to kick things off with a pre-built workflow template rather than starting from a blank conversation. + +Each template bundles an agent prompt, an implementation sketch, and the MCP connections needed to run it. Pick one to open a pre-filled conversation and finish the details with the agent. + +A recommended starting point is the **[GitHub PR Review Copilot](/openhands/usage/agent-canvas/prebuilt/github-pr-review)**. This automation uses your GitHub MCP connection to poll for new pull requests and run agent review conversations locally — no cloud infrastructure required. + +Other available templates include: + +- **GitHub Repository Monitor** — watch a repository for `@OpenHands` mentions and respond automatically. +- **Slack Standup Digest** — summarize yesterday's Slack activity into an async standup note. + +You can browse all pre-built automations from the `Automate` view at any time. See [Pre-built Automations](/openhands/usage/agent-canvas/prebuilt-automations) for the full list. 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..3e9d0f45 --- /dev/null +++ b/openhands/usage/agent-canvas/overview.mdx @@ -0,0 +1,39 @@ +--- +title: Agent Canvas Overview +description: A lightweight platform to run agents and automations — locally or in the cloud. +--- + + + 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. + +## 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. +- [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 new file mode 100644 index 00000000..e16a1862 --- /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) +- [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) +- [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..1965e65e --- /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) and [First-Time Setup](/openhands/usage/agent-canvas/first-time-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..f83f5f7c --- /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) and [First-Time Setup](/openhands/usage/agent-canvas/first-time-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..f4322e0b --- /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) and [First-Time Setup](/openhands/usage/agent-canvas/first-time-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/setup.mdx b/openhands/usage/agent-canvas/setup.mdx new file mode 100644 index 00000000..6db32068 --- /dev/null +++ b/openhands/usage/agent-canvas/setup.mdx @@ -0,0 +1,89 @@ +--- +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 [VM / Self-Hosted Backend](/openhands/usage/agent-canvas/backend-setup/vm) 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 [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. | + | `--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.) | + | `-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..2f5665f8 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. +[Get started with Agent Canvas](/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..689a9c66 100644 --- a/overview/quickstart.mdx +++ b/overview/quickstart.mdx @@ -3,30 +3,13 @@ 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 + + + The recommended way to run OpenHands. Install via npm or Docker and start your first conversation in minutes. - - 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 + + No installation required — sign in and start coding.