Skip to main content

Documentation Index

Fetch the complete documentation index at: https://allhandsai-docs-agent-canvas-docs.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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
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 before exposing it to a network you do not control.

​
Install Agent Canvas

npm install -g @openhands/agent-canvas

​
Start Agent Canvas

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: 
agent-canvas --port 3000

​
CLI Flags

The installed agent-canvas binary currently exposes the following public flags:
FlagDescription
-p, --port <port>Set the ingress port for the local Agent Canvas stack
-h, --helpShow 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:
VariablePurpose
OH_SECRET_KEYSecret used to protect stored settings and secrets
OH_AGENT_SERVER_GIT_REFAdvanced override for running the agent server from a specific git ref
OH_AGENT_SERVER_VERSIONAdvanced override for pinning a specific agent server version
OH_AGENT_SERVER_LOCAL_PATHDevelopment-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 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