--- title: Install Agent Canvas description: Install, run, update, or uninstall Agent Canvas. icon: rocket --- ## Quick Start Install Agent Canvas with npm and start the full local stack: ```bash npm install -g @openhands/agent-canvas agent-canvas ``` Agent Canvas starts on `http://localhost:8000`; open that URL manually if your browser does not. Then follow [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) to configure a model and open a workspace. If installation or startup fails, see [Verify Prerequisites](#verify-prerequisites). If you would rather not install npm packages, prefer an installer with bundled Node.js and `uv`, or want a sandboxed setup, see [More Install Options](#more-install-options) below. Treat agents and ACP processes as untrusted: they can run shell commands and read or write files with your user account's permissions. Agent Canvas is the client and does not isolate them — use a container, sandbox, or VM for a tighter boundary, and review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) before exposing backend services to a network you do not control. ## More Install Options The `agent-canvas` launcher runs the Canvas client with Agent Server, Automation Server, and ingress as an all-in-one local stack. Use npm or npx for direct local execution, or Docker for a containerized stack with explicit project mounts. You can also run the client separately and connect it to an existing backend. | Method | Use It When | What The Agent Can Access | |--------|-------------|---------------------------| | **[Desktop app (preview)](#desktop-app-preview-build)** | You want an installer with bundled Node.js and `uv`. Go to [macOS](#macos), [Windows](#windows), or [Linux](#linux) instructions. | The default local backend runs directly on your machine and can work in local workspaces you open. | | **[npm local install](#install-npm)** | You want the quickest local browser setup. | Runs directly on your machine and can work in local workspaces you open. | | **[Docker](#install-docker)** | You want a local sandbox with clearer file boundaries. | Runs inside a container and can access mounted project directories. | | **[npx](#install-npx)** | You want to try Agent Canvas without installing the package globally. | Runs directly on your machine and can work in local workspaces you open. | | **[VM / self-hosted](/openhands/usage/agent-canvas/backend-setup/vm)** | You want an always-on backend, stronger hardware, or a team-accessible server. | Runs on the VM or dedicated host you configure. | | **[From source](#install-from-source)** | You are contributing to Agent Canvas or changing the frontend/backend stack. | Runs your local development checkout. | For an installer, choose the desktop preview below. For a browser setup, use `npx` for a quick first run or npm for a reusable `agent-canvas` command. Use Docker when you specifically want sandboxing. ## Desktop App (Preview Build) The desktop app is an early preview for user testing. It bundles Node.js and `uv`, starts its local backend automatically, and does not require you to install npm packages, clone the source, or keep a terminal open. Skip the command-line prerequisites and installation sections below. Preview builds may have rough edges. The macOS app is not yet signed with an Apple Developer ID or notarized, so Gatekeeper may block it; see [desktop troubleshooting](#troubleshooting-and-lifecycle). Windows may show a SmartScreen prompt. Current installers support Apple silicon and Intel Macs, and x64 Windows and Linux. Download the file for your operating system from the **Assets** list on the [latest OpenHands release](https://github.com/OpenHands/OpenHands/releases/latest). Replace `` in the filenames below with the release version. Older builds are on the [releases page](https://github.com/OpenHands/OpenHands/releases). ### macOS 1. Download `OpenHands-Agent-Canvas--universal.dmg` from the [latest release assets](https://github.com/OpenHands/OpenHands/releases/latest). 2. Open the disk image and drag **OpenHands Agent Canvas** to **Applications**. 3. Launch **OpenHands Agent Canvas** from Applications. The universal disk image includes Node.js and `uv` for both Apple silicon and Intel Macs. ### Windows 1. Download `OpenHands-Agent-Canvas-Setup-.exe` from the [latest release assets](https://github.com/OpenHands/OpenHands/releases/latest). 2. Run the installer. If Windows SmartScreen prompts you, confirm that the installer came from the official OpenHands release before continuing. 3. Launch **OpenHands Agent Canvas** from the Start menu. ### Linux Choose a package from the [latest release assets](https://github.com/OpenHands/OpenHands/releases/latest): - **AppImage:** Download `OpenHands.Agent.Canvas-.AppImage`, make it executable in your file manager's permissions or with `chmod +x`, then run the file. - **Debian / Ubuntu:** Download `agent-canvas__amd64.deb`, install it with your package manager (for example, `sudo apt install ./agent-canvas__amd64.deb`), then launch **OpenHands Agent Canvas** from your applications menu. ### First Launch During startup, select **Show details** to view and copy the live startup log if startup takes longer than expected or fails. Once the app opens, follow [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) to configure a model and open a workspace. The desktop app can also run conversations in DigitalOcean sandboxes. See [DigitalOcean Managed Agents](/openhands/usage/agent-canvas/backend-setup/digitalocean). ### Troubleshooting and Lifecycle If macOS reports that the app is damaged or cannot be opened, first confirm that you downloaded it from the official OpenHands release. After moving it to Applications, clear its quarantine attribute in Terminal, then launch it again: ```bash xattr -dr com.apple.quarantine "/Applications/OpenHands Agent Canvas.app" ``` To stop the app, quit **OpenHands Agent Canvas** from its application menu. To run it again, launch the installed app. To update it, download and install the latest desktop release; `Settings > Application` also shows the installed version and can check for updates. To uninstall, quit the app and move it to the Trash on macOS, uninstall it from **Installed apps** on Windows, or remove the AppImage or Debian package on Linux. Please [join the OpenHands Slack community](https://openhands.dev/joinslack) to share preview feedback and [open an issue](https://github.com/OpenHands/OpenHands/issues) for problems you find. ## Verify Prerequisites These prerequisites apply to the npm, npx, and Docker methods. Desktop installer users can go directly to [First Time Setup](/openhands/usage/agent-canvas/first-time-setup). Install [Node.js](https://nodejs.org/en/download) 24 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify both tools are available: ```bash node --version npm --version uv --version ``` If `uv` or `uvx` is missing, install `uv` before starting Agent Canvas. The local agent server runtime uses it. Install [Docker](https://docs.docker.com/get-docker/) and make sure the Docker daemon is running: ```bash docker --version docker ps ``` On macOS and Windows, open Docker Desktop before running the container. Install [Node.js](https://nodejs.org/en/download) 24 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify the tools are available: ```bash node --version npm --version uv --version ``` If `uv` or `uvx` is missing, install `uv` before starting Agent Canvas. The local agent server runtime uses it. Termux and other mobile Linux environments are not a primary supported target. For the most reliable local setup, use macOS, Linux, Windows with PowerShell, or Windows with WSL2. ## Install And Run Install the published package globally: ```bash npm install -g @openhands/agent-canvas ``` Start the full local stack: ```bash agent-canvas ``` Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually. Use a named Docker volume for persistent settings and a host directory for project files, then start the container. **macOS / Linux:** ```bash mkdir -p ~/projects docker run -it --rm \ -p 127.0.0.1:8000:8000 \ -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \ -v openhands-data:/home/openhands/.openhands \ -v ~/projects:/projects \ ghcr.io/openhands/agent-canvas:latest ``` **Windows (PowerShell):** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\projects" | Out-Null docker run -it --rm ` -p 127.0.0.1:8000:8000 ` -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true ` -v openhands-data:/home/openhands/.openhands ` -v "$($env:USERPROFILE)\projects:/projects" ` ghcr.io/openhands/agent-canvas:latest ``` The Docker image serves Agent Canvas at `http://localhost:8000/canvas`. The agent can access project files under the mounted `/projects` directory. The `127.0.0.1:` prefix publishes the port on your machine only, so other devices on your network cannot reach the agent server. Docker listens on all interfaces inside the container so port publishing works. By default, that prevents Agent Canvas from embedding its session API key in the page, and the browser asks you to enter the key. The commands above explicitly opt in with `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true` while keeping the published host port on localhost. On first connection, the UI receives the key automatically; you do not need a model-provider key to connect to the backend. Anyone who can reach the frontend can obtain an embedded session key and access the backend. Keep this opt-in paired with `-p 127.0.0.1:8000:8000`. If you publish on a LAN or public interface, or expose the UI through a proxy or tunnel, omit `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY` and enter the backend key manually. For internet-facing deployments, follow [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). Docker creates `openhands-data` on first use and keeps it after the container exits, including with `--rm`. Reuse the same volume on subsequent runs. The image places new default conversation workspaces under `/home/openhands/.openhands/agent-canvas/workspaces` in this volume, so they survive container recreation with the same volume. The `/projects` bind mount remains separate; the volume does not copy older workspaces or host project directories into it. The example uses `--rm`, which does not enable automatic recovery. If you need Docker to restart the container when Agent Server stops responding, run it with a restart policy such as `--restart unless-stopped` instead of `--rm`. Agent Canvas exits with a failure status when Agent Server stops responding, allowing that policy to restart it. On Linux, binding `~/.openhands` can cause `unable to open database file`: the container user defaults to UID `10001`, while the host directory is usually owned by your own user, such as UID `1000`. A named volume avoids this ownership mismatch. Switching to a new volume does not copy existing settings from `~/.openhands`. If startup reports an unwritable state directory or bind mount, check that the container user (UID `10001` by default) can write to the mounted paths. On SELinux hosts, check the bind mount's labeling as well. An intentionally read-only workspace is allowed with a warning. To move existing settings from `~/.openhands` into the volume, run this once before starting Agent Canvas: ```bash docker run --rm -u 0 --entrypoint sh \ -v ~/.openhands:/from:ro \ -v openhands-data:/to \ ghcr.io/openhands/agent-canvas:latest \ -c 'cp -a /from/. /to/ && chown -R 10001:10001 /to' ``` To use DigitalOcean sandboxes, follow the [DigitalOcean Docker setup](/openhands/usage/agent-canvas/backend-setup/digitalocean#use-it-from-the-web-build) to enable the integration and configure authentication. PowerShell uses backticks (`` ` ``) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again. Run the latest published package without installing it globally: ```bash npx @openhands/agent-canvas ``` Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually. Use `npx` when you want to try Agent Canvas once, avoid global package installs, or work around a shell `PATH` issue with the global `agent-canvas` command. Use the source workflow only when you want to modify Agent Canvas itself: ```bash git clone https://github.com/OpenHands/OpenHands.git cd OpenHands npm install npm run dev ``` For development-specific environment variables and commands, see [Contribute / Development](/openhands/usage/agent-canvas/development). ## Confirm It Started After startup: 1. Open `http://localhost:8000`. 2. Confirm the default local backend shows as connected. 3. Open `Settings > LLM` and configure a model. 4. Choose `Open Workspace` before starting a conversation if you want the agent to work in a specific folder. 5. Return to the home screen and start a conversation. If the page does not load, check the terminal where Agent Canvas is running. Common causes are a missing prerequisite, a busy port, or Docker not running. ## Run Agent Canvas Again After you close the terminal or restart your computer, start Agent Canvas with the same command you used to install it. Keep that terminal or Docker container running while you use the browser UI. ```bash agent-canvas ``` ```bash npx @openhands/agent-canvas ``` Run the same `docker run` command from [Install and Run](#install-and-run). The browser connects to the host port you map, while the backend and model configuration run where the Agent Canvas process or container is running. If the UI opens but the backend is disconnected or a model cannot respond, use [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) to identify the affected part of the stack. ## Common Startup Options | Option | Description | |--------|-------------| | `-p`, `--port ` | Set the ingress port. The default is `8000`. | | `--backend-only` | Start only the backend behind ingress. Use this for a headless backend on a local machine, VM, or server. | | `--frontend-only` | Start only the static frontend behind ingress. Use this when connecting a local UI to a remote backend. | | `--public` | Enable public mode. Requires `LOCAL_BACKEND_API_KEY` and is intended for deployments reachable beyond localhost. | | `--verbose` | Run the backends with `DEBUG` logging. Without it, they start at `WARNING`. | | `-v`, `--version` | Show the version number. | | `--info` | Show version and stack configuration details. | | `-h`, `--help` | Show built-in help. | If port `8000` is already in use, start Agent Canvas on another port: ```bash agent-canvas --port 3000 ``` ## Environment Variables | Variable | Purpose | |----------|---------| | `LOCAL_BACKEND_API_KEY` | API key for the server. Required in `--public` mode; optional for local use because Agent Canvas can auto-generate and persist one. | | `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY` | Docker quickstart opt-in to embed the session key in the frontend. Use `true` only with the host port restricted to localhost; omit it for LAN/public access. | | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. | | `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version, such as `0.1.0`. | | `AUTOMATION_KV_SECRET` | Secret used to protect automation key-value storage. When it is not set, the launcher pins the first session key to `automation-kv-secret.txt` and reuses it, so rotating `SESSION_API_KEY` does not make existing automation KV data unreadable. The pin file must be a regular file with private permissions; otherwise the launcher fails closed. | | `LOG_LEVEL` | Log level for the agent server. Overrides the `WARNING` default; Uvicorn's `--log-level` follows it. | | `AUTOMATION_LOG_LEVEL` | Log level for the automation service. Overrides the `WARNING` default. | | `PORT` | Ingress port inside the Docker container. Map it with `-p :`. | ## Session Keys And The API-Key Prompt Agent Canvas uses different credentials for connecting to a backend and accessing a model: | Key | What It Does | Where To Configure It | |-----|--------------|-----------------------| | Session/backend API key | Authenticates the browser to your Agent Canvas backend. It is generated locally or supplied by the backend operator. | Enter it at the initial API-key prompt or in the backend connection settings. | | Model-provider API key | Authenticates model requests to your chosen provider, such as Anthropic, OpenAI, or OpenHands Cloud. | Configure it during [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) or in `Settings > LLM`. | A model-provider key will not unlock a local backend. `OH_SECRET_KEY` is a separate encryption secret for stored settings; do not enter it at the API-key prompt. ### Recover When Docker Asks For A Key The prompt is expected when automatic session-key delivery is disabled. You can authenticate without recreating your settings volume: 1. In another terminal, run `docker ps` and find the Agent Canvas container's ID or name. 2. If you started it with `LOCAL_BACKEND_API_KEY`, use that value. Otherwise, retrieve the generated key with the following command, replacing `CONTAINER` with the ID or name. This works in macOS/Linux shells and PowerShell for the default Docker configuration: ```bash docker exec CONTAINER cat /home/openhands/.openhands/agent-canvas/api-key.txt ``` Keep the printed key private. The generated key lives in the `openhands-data` volume and is reused when you restart with that volume. If you customized the state directory, use the `api-key.txt` path that the container logs when it first generates the key. 3. Open `http://localhost:8000/canvas`, enter the backend key, and confirm the backend connects. Then configure your model separately in `Settings > LLM`. For automatic connection on your own machine, stop the container and rerun the localhost-only Docker command above with the opt-in and the same volume. If the browser retained an old key after you changed the backend key or switched volumes, update the key in the backend connection settings, or open a private browser window and enter the current key. ### Configure Your Own Docker Backend Key To supply a key instead of using the generated one, set `LOCAL_BACKEND_API_KEY` in your host environment to a strong, unique secret, then add `-e LOCAL_BACKEND_API_KEY` to `docker run`. Docker passes the environment value into the container. Supply the same value on subsequent runs; an explicitly configured key takes precedence over the generated key file and does not replace that file. When automatic key delivery is disabled, users must enter this value in the UI. Do not enable automatic delivery to bypass authentication on a shared or public deployment. ## Stop Agent Canvas Return to the terminal running Agent Canvas and press `Ctrl+C`. Return to the terminal running Agent Canvas and press `Ctrl+C`. Return to the terminal running the container and press `Ctrl+C`. If the container is running in the background, stop it with: ```bash docker ps docker stop ``` ## Update Agent Canvas Stop Agent Canvas, then reinstall the latest package: ```bash npm install -g @openhands/agent-canvas@latest agent-canvas --version ``` Stop Agent Canvas, then run the latest package: ```bash npx @openhands/agent-canvas@latest ``` Stop the running container, pull the latest image, then run the container again: ```bash docker pull ghcr.io/openhands/agent-canvas:latest ``` Your settings and conversation data are stored outside the package or image: in `~/.openhands` for npm and npx, and in the `openhands-data` volume for Docker. Pulling a new image does not change the volume. **Recover or reset:** Use [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting) when the browser is blank, a port is busy, the backend is unreachable, a model or API key fails, or an update or uninstall is stuck. It also explains clean removal and reinstall. ## Uninstall Agent Canvas Stop any running Agent Canvas process, then uninstall the package: ```bash npm uninstall -g @openhands/agent-canvas ``` If Windows reports that `uv.exe` or another file is in use, close terminals running Agent Canvas, stop related processes, and run the uninstall command again. There is no Agent Canvas package to uninstall when you use `npx`. Stop the running process with `Ctrl+C`. If you want to clear downloaded package cache entries, use npm's cache commands: ```bash npm cache verify ``` Stop any running container, then remove the image if you no longer need it: ```bash docker ps docker stop docker rmi ghcr.io/openhands/agent-canvas:latest ``` To also delete settings, secrets, and conversation history, remove the settings volume: ```bash docker volume rm openhands-data ``` Uninstalling the package or image does not automatically remove your persisted data. To delete local settings, secrets, and conversation history, remove `~/.openhands` for npm and npx, or the `openhands-data` volume for Docker. If you bound `~/.openhands` in an older Docker setup, remove that directory too. ## Next Steps Choose your agent, connect a backend, and add a model. Add, switch, and remove the backends Canvas connects to. Save model configurations and switch between them in conversations. Fix install, startup, backend, and model issues.