First Time Setup

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 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. Your choice creates the initial active Agent Profile. You can change your active profile or create additional profiles later from Settings > Agent.

​

Step 2: Check Your Backend

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

​

Step 3: Set Up Your LLM

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 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. The default model is OpenAI GPT-5.6 Sol, and DeepSeek V4 Flash is the free OpenHands-routed model. When adding an OpenHands provider connection, the provider field is a searchable supported-provider selector rather than free text. For OpenHands Agent Profiles, this LLM setup becomes the model profile the agent uses. ACP agents such as Claude Code, Codex, and Gemini CLI use their own authentication and model configuration.

​

Step 4: Start From a Proven Workflow

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. 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 for the full list.

​

Getting Started Checklist

After completing the setup wizard, a Getting Started checklist appears in the sidebar. It guides you through the core first actions:

1. Set up your LLM — links to Settings > LLM
2. Connect MCP servers — links to Customize > MCP
3. Start a conversation — links to Conversations
4. Explore automations — links to Automate
5. Customize your agent — links to Customize
6. Review settings — links to Settings

Each item links directly to the relevant page. The checklist tracks your progress and minimizes to stay out of the way. When all items are complete, the checklist auto-hides.

​

Super Admin Setup Guide

On OpenHands Enterprise backends where the first Super Admin has the setup guide enabled, Agent Canvas shows the same setup guide as the OHE dashboard: a floating panel in the lower-right corner that collapses to a pill. It lists the same four steps in the same order, with the same n/4 progress, and links back to OHE for the steps that live there. The guide appears only for the first Super Admin, while the guide has an organization and is not dismissed. Everyone else, and local backends, see no guide. While the guide is loading or shown, the “Getting started” checklist is hidden; it stays for everyone else. Progress is re-read on each navigation, so an automation created from a template in Canvas ticks its step. When you complete a step in Canvas — creating an automation directly from a template, or adding an MCP server — the guide opens the next step. A step finished out of order, or one the server does not confirm, opens nothing. An assisted setup that only starts a conversation does not report the step. Closing the panel collapses it to the pill until the next page load. Dismissing the guide stays on the OHE guide page.

​

Customize your Agent Canvas

When you are ready to go beyond the default setup, choose the mechanism that fits the task:

• Add repository-wide guidance with AGENTS.md for each Workspace.
• Add reusable task instructions with Skills.
• Connect external tools through MCP.
• Add packaged capabilities with Plugins.
• Automate repeated work with Automations.

​

After Your First Session

Keep the terminal or Docker container that runs Agent Canvas active while you use the browser. When you are done, stop Agent Canvas. Start it again with the same command when you return. For routine maintenance, see update and uninstall. If the UI, backend, or model does not work as expected, start with Troubleshooting.