> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Install, run, update, and uninstall Agent Canvas.

Agent Canvas can run directly on your machine or inside Docker. Start with the simplest setup that matches the trust boundary you want.

<Warning>
  Agent Canvas starts an agent server that can run shell commands, read files, write files, and use connected tools. Treat the machine or container where the backend runs as trusted infrastructure. Before exposing Agent Canvas to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm).
</Warning>

## Choose An Install Method

| Method                | Use It When                                                                    | What The Agent Can Access                                                |
| --------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **npm local install** | You want the quickest local browser setup.                                     | Runs directly on your machine and can work in local workspaces you open. |
| **Docker**            | You want a local sandbox with clearer file boundaries.                         | Runs inside a container and can access mounted project directories.      |
| **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**  | You want an always-on backend, stronger hardware, or a team-accessible server. | Runs on the VM or dedicated host you configure.                          |
| **From source**       | You are contributing to Agent Canvas or changing the frontend/backend stack.   | Runs your local development checkout.                                    |

<Note>
  If you are new to Agent Canvas, use `npx` for a quick first run or npm local install if you want a reusable `agent-canvas` command. Use Docker when you specifically want sandboxing.
</Note>

## Verify Prerequisites

<Tabs>
  <Tab title="npm">
    Install [Node.js](https://nodejs.org/en/download) 22.12 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify both tools are available:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Docker">
    Install [Docker](https://docs.docker.com/get-docker/) and make sure the Docker daemon is running:

    ```bash theme={null}
    docker --version
    docker ps
    ```

    On macOS and Windows, open Docker Desktop before running the container.
  </Tab>

  <Tab title="npx">
    Install [Node.js](https://nodejs.org/en/download) 22.12 or later and [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then verify the tools are available:

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

<Note>
  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.
</Note>

## Install And Run

<Tabs>
  <Tab title="npm">
    Install the published package globally:

    ```bash theme={null}
    npm install -g @openhands/agent-canvas
    ```

    Start the full local stack:

    ```bash theme={null}
    agent-canvas
    ```

    Agent Canvas starts on `http://localhost:8000` by default. If your browser does not open automatically, open that URL manually.
  </Tab>

  <Tab title="Docker">
    Create host directories for persistent settings and project files, then start the container.

    **macOS / Linux:**

    ```bash theme={null}
    mkdir -p ~/projects ~/.openhands

    docker run -it --rm \
      -p 8000:8000 \
      -v ~/.openhands:/home/openhands/.openhands \
      -v ~/projects:/projects \
      ghcr.io/openhands/agent-canvas:latest
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openhands", "$env:USERPROFILE\projects" | Out-Null

    docker run -it --rm `
      -p 8000:8000 `
      -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
      -v "$($env:USERPROFILE)\projects:/projects" `
      ghcr.io/openhands/agent-canvas:latest
    ```

    Agent Canvas starts on `http://localhost:8000`. The agent can access project files under the mounted `/projects` directory.

    <Note>
      PowerShell uses backticks (`` ` ``) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again.
    </Note>
  </Tab>

  <Tab title="npx">
    Run the latest published package without installing it globally:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="From Source">
    Use the source workflow only when you want to modify Agent Canvas itself:

    ```bash theme={null}
    git clone https://github.com/OpenHands/agent-canvas.git
    cd agent-canvas
    npm install
    npm run dev
    ```

    For development-specific environment variables and commands, see [Contribute / Development](/openhands/usage/agent-canvas/development).
  </Tab>
</Tabs>

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

## Common Startup Options

| Option                | Description                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `-p`, `--port <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. |
| `-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 theme={null}
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. |
| `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`.                                                                               |
| `PORT`                    | Ingress port inside the Docker container. Map it with `-p <host>:<PORT>`.                                                           |

## Stop Agent Canvas

<Tabs>
  <Tab title="npx">
    Return to the terminal running Agent Canvas and press `Ctrl+C`.
  </Tab>

  <Tab title="npm">
    Return to the terminal running Agent Canvas and press `Ctrl+C`.
  </Tab>

  <Tab title="Docker">
    Return to the terminal running the container and press `Ctrl+C`.

    If the container is running in the background, stop it with:

    ```bash theme={null}
    docker ps
    docker stop <container-id-or-name>
    ```
  </Tab>
</Tabs>

## Update Agent Canvas

<Tabs>
  <Tab title="npx">
    Stop Agent Canvas, then run the latest package:

    ```bash theme={null}
    npx @openhands/agent-canvas@latest
    ```
  </Tab>

  <Tab title="npm">
    Stop Agent Canvas, then reinstall the latest package:

    ```bash theme={null}
    npm install -g @openhands/agent-canvas@latest
    agent-canvas --version
    ```
  </Tab>

  <Tab title="Docker">
    Stop the running container, pull the latest image, then run the container again:

    ```bash theme={null}
    docker pull ghcr.io/openhands/agent-canvas:latest
    ```
  </Tab>
</Tabs>

Your settings and conversation data are stored outside the package or image when you use the documented `~/.openhands` mount.

## Uninstall Agent Canvas

<Tabs>
  <Tab title="npx">
    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 theme={null}
    npm cache verify
    ```
  </Tab>

  <Tab title="npm">
    Stop any running Agent Canvas process, then uninstall the package:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Docker">
    Stop any running container, then remove the image if you no longer need it:

    ```bash theme={null}
    docker ps
    docker stop <container-id-or-name>
    docker rmi ghcr.io/openhands/agent-canvas:latest
    ```
  </Tab>
</Tabs>

Uninstalling the package or image does not automatically remove your persisted data. If you want to delete local settings, secrets, and conversation history, remove the persistence directory you mounted or used, such as `~/.openhands`.

## Next Steps

* [First Time Setup](/openhands/usage/agent-canvas/first-time-setup)
* [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
* [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles)
* [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker)
* [Troubleshooting](/openhands/usage/agent-canvas/troubleshooting)