Skip to main content
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 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 first-time setup — Check your backend screen showing a connected local backend at 127.0.0.1:8000 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.

​
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 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. 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 first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest 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.
Toggle the checklist from Settings > Application using the Show getting started checklist switch. The setting persists across sessions.

​
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.