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

# Local Backend

> Run one or more local backends and connect to them from the Agent Canvas UI.

Use `--backend-only` to start a local backend. Each backend runs behind an ingress proxy on its own port.

## Start a Backend

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

This starts the backend on `127.0.0.1:8000`. No frontend is served.

## Running Multiple Backends

You can run several backends at the same time on different ports — for example, one per project or toolchain:

```bash theme={null}
agent-canvas --backend-only --port 8001
agent-canvas --backend-only --port 8002
agent-canvas --backend-only --port 8003
```

Each instance gets its own backend and ingress proxy.

## Connect the Frontend

Start the frontend separately:

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

Then add your backends through **Manage Backends**:

1. Click the backend switcher → **Manage Backends** → **Add Backend**.
2. Fill in the **Host / Base URL** (e.g. `http://localhost:8001`) and **API Key**.
3. Repeat for each backend you started.

Switch between them from the backend selector depending on what you're working on.

<Tip>
  If you just want a quick single-machine setup, running `agent-canvas` without any flags starts the full stack (frontend + backend) on one port. The split approach above is useful when you want multiple backends or want to keep the frontend and backends on separate processes.
</Tip>

## Related Guides

* [Connect and Manage Backends](/openhands/usage/agent-canvas/backends)
* [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm) — backend-only or full Canvas on a remote machine
* [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker) — run in a container