diff --git a/openhands/usage/agent-canvas/backend-setup/vm.mdx b/openhands/usage/agent-canvas/backend-setup/vm.mdx index b71781f0..ff22fae2 100644 --- a/openhands/usage/agent-canvas/backend-setup/vm.mdx +++ b/openhands/usage/agent-canvas/backend-setup/vm.mdx @@ -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. | @@ -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 @@ -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. @@ -191,7 +191,9 @@ 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: @@ -199,11 +201,24 @@ On the VM, in a second terminal or tmux pane: 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`. @@ -235,6 +250,10 @@ Start ngrok with the traffic policy: ngrok http 8000 --traffic-policy-file ~/policy.yml ``` + + To run OAuth on a domain you choose, add `--url` as shown in [Use Your Own Domain](#use-your-own-domain). + + To run full Canvas and ngrok side by side in tmux: ```bash