> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-vertex-agent-server-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Install and run Agent Canvas via npm or Docker.

<Warning>
  Agent Canvas starts an agent server on the machine where you run it. Treat that machine as trusted infrastructure and review the guidance in [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) before exposing it to a network you do not control.
</Warning>

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

    **Install:**

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

    **Run:**

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

    By default, Agent Canvas starts on `http://localhost:8000`.

    ### CLI Flags

    | Flag                  | Description                                                                                                                                                                                                                                                                        |
    | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `-p`, `--port <port>` | Set the ingress port (default `8000`)                                                                                                                                                                                                                                              |
    | `--public`            | Enable public mode — requires `LOCAL_BACKEND_API_KEY`. The key is **not** injected into the frontend; users must enter it when the UI loads. Use this for any deployment reachable by others. See [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). |
    | `--backend-only`      | Start only the backend behind ingress (no frontend). Use this to run a headless backend on a VM or server.                                                                                                                                                                         |
    | `--frontend-only`     | Start only the static frontend behind ingress (no agent server or automation). Use this to point a local UI at a remote backend.                                                                                                                                                   |
    | `-v`, `--version`     | Show the version number                                                                                                                                                                                                                                                            |
    | `--info`              | Show the version and default stack configuration (agent server version, ports, etc.)                                                                                                                                                                                               |
    | `-h`, `--help`        | Show the built-in help output                                                                                                                                                                                                                                                      |

    ### Environment Variables

    | Variable                  | Purpose                                                                                                                 |
    | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
    | `LOCAL_BACKEND_API_KEY`   | API key for the server. Required in `--public` mode; optional otherwise (auto-generated and persisted across restarts). |
    | `OH_SECRET_KEY`           | Secret used to protect stored settings and secrets                                                                      |
    | `OH_AGENT_SERVER_VERSION` | Pin a specific agent server version (e.g. `0.1.0`)                                                                      |
  </Tab>

  <Tab title="Docker">
    **Prerequisites:** [Docker](https://docs.docker.com/get-docker/) (Docker Desktop on macOS/Windows, or Docker Engine on Linux).

    A Docker image is available that sandboxes the entire Agent Canvas stack. Mount your project files and a persistence directory for settings, secrets, and conversation history.

    Create a host directory for your projects (the agent can access any folder under this path) and run 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
    ```

    <Note>
      On Windows, Docker Desktop must be installed and running. PowerShell uses backticks (`` ` ``) for line continuation instead of backslashes.
    </Note>

    ### Environment Variables

    Configuration is passed via `-e` flags on `docker run`:

    | Variable                | Purpose                                                                             |
    | ----------------------- | ----------------------------------------------------------------------------------- |
    | `PORT`                  | Ingress port inside the container (default `8000`). Map it with `-p <host>:<PORT>`. |
    | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set.                    |
    | `OH_SECRET_KEY`         | Secret used to protect stored settings and secrets                                  |
  </Tab>
</Tabs>

<Note>
  If you want to clone the repository, run custom dev modes, or configure Vite-specific environment variables, use the [Contribute / Development guide](/openhands/usage/agent-canvas/development) instead.
</Note>

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

## Next Steps

* [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
* [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles)
* [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)