diff --git a/docs.json b/docs.json index 09aa9485..526e86d2 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", + "openhands/usage/agent-canvas/first-time-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/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/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..201241d0 --- /dev/null +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -0,0 +1,6 @@ +--- +title: Setup a Docker Backend +description: Run an OpenHands agent server in Docker and connect Agent Canvas to it. +--- + +Coming soon. 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..8b9a88d4 --- /dev/null +++ b/openhands/usage/agent-canvas/backends.mdx @@ -0,0 +1,64 @@ +--- +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. + +## 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/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..0e490e34 --- /dev/null +++ b/openhands/usage/agent-canvas/overview.mdx @@ -0,0 +1,45 @@ +--- +title: Agent Canvas Overview +description: Run OpenHands through the Agent Canvas UI and connect it 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. + + +## What Agent Canvas Includes + +When you run `agent-canvas`, you get a complete local stack: + +- The Agent Canvas web UI +- An OpenHands agent server +- The automation backend used for scheduled and event-driven workflows +- A local ingress endpoint that serves the UI and routes API traffic + +## Key Concepts + +| Concept | What It Means | +|---------|----------------| +| **Agent Canvas UI** | The browser interface for conversations, customization, settings, and automations | +| **Active Backend** | The backend Agent Canvas is currently using for conversations and synced settings | +| **Local Backend** | A backend running on your own machine or another machine you control | +| **Cloud Backend** | A backend backed by OpenHands Cloud services when available | +| **Customize** | The top-level area for `Skills` and `MCP Servers` | +| **Settings** | Backend-synced configuration for `Agent`, `LLM`, `Condenser`, `Verification`, `Application`, and `Secrets` | + +## How It Fits with Other OpenHands Products + +- **Agent Canvas** is the recommended local and self-hosted UI path. +- **Local GUI (Legacy)** remains documented for older Docker-based workflows. +- **OpenHands Cloud** is the hosted product. +- **OpenHands SDK** is the Python framework behind the agent system. + +## Where to Start + +- [Setup](/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..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/self-hosting.mdx b/openhands/usage/agent-canvas/self-hosting.mdx new file mode 100644 index 00000000..57c87d3c --- /dev/null +++ b/openhands/usage/agent-canvas/self-hosting.mdx @@ -0,0 +1,78 @@ +--- +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. + + +## Common Self-Hosted Patterns + +Teams usually self-host Agent Canvas in one of these ways: + +- on a dedicated developer workstation +- on a VM in a cloud provider +- on a machine inside a private network or VPN + +## Recommended Security Checklist + +Before you expose Agent Canvas to a broader network, make sure you: + +1. Restrict inbound network access. +2. Use TLS and an authenticated reverse proxy if the UI is reachable over the internet. +3. Treat the host as sensitive infrastructure because it stores secrets, conversations, and working copies. +4. Keep the machine patched and limit who can access it. + +## Basic VM Workflow + +1. Provision a Linux or macOS machine you control. +2. Install Node.js, npm, and `uv`. +3. Clone the repository and install dependencies: + +```bash +git clone https://github.com/OpenHands/agent-canvas.git +cd agent-canvas +npm install +``` + +4. Start the local stack: + +```bash +npm run dev +``` + +5. Put a reverse proxy such as nginx in front of the ingress endpoint if you need browser access beyond localhost. + +That stack keeps the ingress, frontend, agent server, and automation backend bound to `127.0.0.1`, so the network and reverse-proxy layers are what determine who can reach it. + +## Reverse Proxy and Auth + +If you publish Agent Canvas behind a domain: + +- terminate TLS at the reverse proxy +- require authentication before requests reach Agent Canvas +- keep the backing services off the public network whenever possible + +## Connecting from Another Machine + +You do not need to run the UI and the backend on the same computer. + +Two common patterns are: + +- Run the full Agent Canvas stack on a dedicated host or VM, then open that UI directly or through a secure reverse proxy. +- Keep Agent Canvas on your laptop, and add the remote backend through `Manage Backends`. + +## Detailed Hardening Reference + +For a longer VM hardening walkthrough, see the repository guide: + +- [SELF_HOSTING.md](https://github.com/OpenHands/agent-canvas/blob/main/SELF_HOSTING.md) + +## Related Guides + +- [Setup](/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..d1421248 --- /dev/null +++ b/openhands/usage/agent-canvas/setup.mdx @@ -0,0 +1,86 @@ +--- +title: Install +description: Install Agent Canvas from npm and run it from your terminal. +--- + +This page documents the published npm install path for Agent Canvas: install the package globally, then start it with the `agent-canvas` command. + +## Prerequisites + +Before you start, make sure the machine has: + +- Node.js 22.12 or later +- `npm` +- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) + + + 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. + + +## Install Agent Canvas + +```bash +npm install -g @openhands/agent-canvas +``` + +## Start Agent Canvas + +```bash +agent-canvas +``` + +By default, Agent Canvas starts on `http://localhost:8000`. + +## Change the Port + +Use the public `--port` flag when you need a different ingress port: + +```bash +agent-canvas --port 3000 +``` + +## CLI Flags + +The installed `agent-canvas` binary currently exposes the following public flags: + +| Flag | Description | +|------|-------------| +| `-p`, `--port ` | Set the ingress port for the local Agent Canvas stack | +| `-h`, `--help` | Show the built-in help output | + +## Runtime Environment Variables + +Agent Canvas keeps most day-to-day configuration in the UI, not in environment variables. The current runtime-level overrides are: + +| Variable | Purpose | +|----------|---------| +| `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | +| `OH_AGENT_SERVER_GIT_REF` | Advanced override for running the agent server from a specific git ref | +| `OH_AGENT_SERVER_VERSION` | Advanced override for pinning a specific agent server version | +| `OH_AGENT_SERVER_LOCAL_PATH` | Development-only override for using a local `software-agent-sdk` checkout | + + + 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. + +## Docker Image Placeholder + + + A published Agent Canvas Docker image is coming soon. This section is intentionally reserved so the docs can add a container-based install path without changing the overall navigation. + + +## 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/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