Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 24 additions & 5 deletions openhands/usage/agent-canvas/backend-setup/vm.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Agent Canvas supports two VM runtime modes and several ways to reach them:
| Setup | Start Command | How You Use It |
|-------|---------------|----------------|
| **Backend only** | `agent-canvas --backend-only --public` | Run only the agent server on the VM. Start `agent-canvas --frontend-only` on your laptop and add the VM URL in **Manage Backends**. |
| **Backend only + ngrok** | `agent-canvas --backend-only --public` and `ngrok http 8000` | Use an ngrok URL as the backend URL. Do not add ngrok OAuth for this mode; rely on `LOCAL_BACKEND_API_KEY` plus a private or temporary URL. |
| **Backend only + ngrok** | `agent-canvas --backend-only --public` and `ngrok http 8000` | Use your ngrok domain as the backend URL. Do not add ngrok OAuth for this mode; rely on `LOCAL_BACKEND_API_KEY`. |
| **Full Canvas** | `agent-canvas --public` | Serve both the Agent Canvas UI and the backend from the VM. Open the VM, reverse proxy, or ngrok URL in a browser. |
| **Full Canvas + ngrok OAuth** | `agent-canvas --public` and `ngrok http 8000 --traffic-policy-file ~/policy.yml` | Protect the full Canvas URL with an ngrok login policy before users reach Agent Canvas. |

Expand All @@ -41,7 +41,7 @@ Agent Canvas requires:
- [Node.js](https://nodejs.org/en/download) 22.12 or later, including `npm`.
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for the agent server runtime.
- `git` and `curl`.
- Optional: [`ngrok`](https://ngrok.com/download) for a temporary public URL.
- Optional: [`ngrok`](https://ngrok.com/download) for a public URL on a free ngrok domain or your own custom domain.
- Optional: `tmux` to keep Agent Canvas and ngrok running after disconnecting from SSH.

### Ubuntu 22.04 / 24.04
Expand Down Expand Up @@ -135,7 +135,7 @@ Use a high-entropy secret. You will enter this key in Agent Canvas when connecti
3. Enter a name, such as `my-vm`.
4. Enter the **Host / Base URL**:
- `http://localhost:8000` if you use an SSH tunnel.
- The `https://...ngrok-free.app` URL if you use ngrok.
- Your ngrok domain (for example `https://your-domain.ngrok-free.app`) if you use ngrok.
- Your reverse proxy URL if you use nginx or another proxy.
5. Enter the `LOCAL_BACKEND_API_KEY` from the VM.
6. Save and select the backend.
Expand Down Expand Up @@ -191,19 +191,34 @@ Then use `http://localhost:8000` as the backend URL in **Manage Backends**.

### Option B: ngrok Without OAuth

Use ngrok without OAuth only for temporary testing or personal access. Keep `--public` enabled and use a strong `LOCAL_BACKEND_API_KEY`.
Use ngrok without OAuth for personal access or a small, trusted backend. Keep `--public` enabled and use a strong `LOCAL_BACKEND_API_KEY`.

Every ngrok account—including the free plan—comes with a free static domain that looks like `your-domain.ngrok-free.app`. It stays the same across restarts, so `ngrok http 8000` starts on it by default and you can save the URL once and keep reusing it. You can view your domain on the [**Domains**](https://dashboard.ngrok.com/domains) page of the ngrok dashboard.

On the VM, in a second terminal or tmux pane:

```bash
ngrok http 8000
```

Use the `https://...ngrok-free.app` forwarding URL:
Use the forwarding URL:

- Backend-only mode: enter it as the **Host / Base URL** in **Manage Backends**.
- Full Canvas mode: open it directly in your browser.

#### Use Your Own Domain

To run on a domain you choose instead of the default, pass it with `--url`:

```bash
ngrok http 8000 --url https://your-canvas.ngrok.app
```

What you can use depends on your ngrok plan:

- **Hobbyist plan:** an ngrok-branded domain such as `your-canvas.ngrok.app`.
- **Pay-as-you-go plan:** your own custom domain such as `canvas.acme.com`.

### Option C: ngrok With Google OAuth

Use ngrok OAuth with **full Canvas** deployments when the ngrok URL may be reachable by a team or a broader audience. OAuth is an additional gate in front of Agent Canvas; it does not replace `LOCAL_BACKEND_API_KEY`.
Expand Down Expand Up @@ -235,6 +250,10 @@ Start ngrok with the traffic policy:
ngrok http 8000 --traffic-policy-file ~/policy.yml
```

<Note>
To run OAuth on a domain you choose, add `--url` as shown in [Use Your Own Domain](#use-your-own-domain).
</Note>

To run full Canvas and ngrok side by side in tmux:

```bash
Expand Down
Loading