π OpenHands: AI-Driven Development
docs: rewrite self-hosting guide for --public mode (#1038)
Rohit Malhotra53ed7757cb2b
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.mdindex 0e9e8c6ac7..7b8cc1281a 100644--- a/docs/SELF_HOSTING.md+++ b/docs/SELF_HOSTING.md@@ -1,22 +1,22 @@# Self-Hosting Agent Canvas on a Virtual MachineThis guide walks through running Agent Canvas on a virtual machine (VM) so you-(and only you) can reach it from anywhere via a browser.+can reach it from anywhere via a browser.> [!WARNING]> Agent Canvas drives an agent that can read and write the filesystem of the> machine it runs on, execute shell commands, and reach the network. Anyone who> can talk to the agent server can do the same. **Treat the VM as you would any> machine that holds production credentials**, and lock it down before exposing-> it to the public internet. The defenses below are layered on purpose β do not-> skip any of them.+> it to the public internet.## Quickstart-1. **Provision a machine**: this could be a VM on AWS or DigitalOcean, or hardware like a dedicated Mac Mini-2. **Secure the machine**: make sure it's not exposed to the public internet-3. **Run the server**: clone this repo and run `npm run dev`-4. **Get a domain**: (Optional) point a domain at your machine and set up nginx+letsencrypt-5. **Connect locally**: (Optional) point your local Agent Canvas to the VM by adding a backend++1. **Provision a machine** β a cloud VM or dedicated hardware (Mac Mini, NUC, etc.)+2. **Secure the machine** β lock down the network firewall+3. **Run Agent Canvas** β generate a key with `openssl rand -base64 32`, then `export LOCAL_BACKEND_API_KEY=<key>` and `npx @openhands/agent-canvas --public`+4. **(Optional) Get a domain** β point a domain at the machine with nginx + Let's Encrypt for TLS+5. **(Optional) Connect locally** β add the remote as a backend in your local Agent Canvas## Details@@ -27,90 +27,72 @@ flowchart LRuser(["π§ You"])subgraph vm["Your VM (single host)"]direction LR- nginx["nginx :443<br/>(TLS + basic auth)"]+ nginx["nginx :443<br/>(TLS)"]ingress["Ingress proxy<br/>127.0.0.1:8000"]- vite["Vite dev server<br/>:3001"]- agent["Agent server<br/>:18000<br/>(SESSION_API_KEY)"]+ static["Static server<br/>:3001"]+ agent["Agent server<br/>:18000<br/>(LOCAL_BACKEND_API_KEY)"]automation["Automation backend<br/>:18001"]nginx --> ingress- ingress -- "/*" --> vite+ ingress -- "/*" --> staticingress -- "/api/*, /sockets" --> agentingress -- "/api/automation/*" --> automationenduser -- "HTTPS / 443" --> nginx```-`npm run dev` spins up the Vite dev server, the agent-server, and the automation backend, and fronts them with an ingress proxy on+`npx @openhands/agent-canvas --public` spins up the static frontend server,+the agent server, and the automation backend, fronted by an ingress proxy on`127.0.0.1:8000` that routes by path. nginx only needs to know about that-single ingress port β it doesn't talk to the three upstreams directly.+single ingress port.++The `--public` flag enables **public mode**: the API key is _not_ baked into+the frontend. Instead, users see an API key entry screen when they first load+the UI and must paste the `LOCAL_BACKEND_API_KEY` to proceed.The defenses layered on top of this:1. **Cloud / network firewall (step 2)** β by default nothing inbound isreachable except SSH from your IP. If you do step 4, you additionally open80 and 443 (ideally still restricted to your IP allow-list on 443).-2. **`SESSION_API_KEY` on the agent server (step 3, auto-generated)** β- every `/api/*` call must carry a matching `X-Session-API-Key` header.- This guards against any misconfiguration that lets a request bypass the- firewall (e.g. a stray bind to `0.0.0.0`).-3. **nginx HTTP basic auth (step 4, optional)** β if you expose the UI on a- public domain, every request must additionally present a username and- password before it ever reaches the application.+2. **`LOCAL_BACKEND_API_KEY` + public mode (step 3)** β every `/api/*` call+ must carry a matching `X-Session-API-Key` header, and the UI requires+ users to enter the key before they can interact with the agent.## 1. Provision a machine-Any always-on Linux (or macOS) host with a stable network connection will do.-Pick whichever fits your situation:--- **A cloud VM** from any provider β DigitalOcean, AWS EC2, GCP Compute Engine,- Hetzner, Linode, etc. Ubuntu 24.04 LTS is a good default. 2 vCPU / 4 GB RAM- is plenty for a single user; bump it up if you plan to keep many- long-running conversations.-- **Dedicated hardware on your network** β a Mac Mini, an Intel NUC, a spare- laptop. The same setup applies; just keep in mind that anything reachable- from your LAN is also part of the threat model.+Any always-on Linux (or macOS) host with a stable network connection will do:-Whichever you pick, treat the machine as the single source of truth for the-agent β it will hold your conversation history, secrets, and any credentials-the agent needs.+- **A cloud VM** β DigitalOcean, AWS EC2, GCP, Hetzner, Linode, etc.+ Ubuntu 24.04 LTS is a good default. 2 vCPU / 4 GB RAM is plenty for a+ single user.+- **Dedicated hardware** β a Mac Mini, an Intel NUC, a spare laptop.+ Keep in mind that anything reachable from your LAN is part of the threat+ model.## 2. Secure the machine> [!IMPORTANT]-> Do this **before** you start the agent server for the first time. The whole-> point is that nothing on the public internet should be able to reach the-> agent until you have explicitly chosen how to expose it.+> Do this **before** you start the agent server for the first time.The default posture should be: **nothing inbound is reachable from the public-internet** except SSH (and only from your own IP). The agent server, the-automation backend, the Vite dev server, and the ingress proxy will all bind-to `127.0.0.1` on their own (see step 3), but the network firewall is what-guarantees no one else can reach them even if something binds wrong.+internet** except SSH (and only from your own IP). All services bind to+`127.0.0.1` (see step 3), but the network firewall is what guarantees no one+else can reach them even if something binds wrong.Restrict inbound traffic at the cloud-provider / network level (DigitalOcean-Cloud Firewall, AWS Security Group, GCP firewall rule, Hetzner firewall, your-home router's port-forwarding rules, etc.):+Cloud Firewall, AWS Security Group, GCP firewall rule, etc.):-- **Inbound 22 (SSH)** β restrict to your own IP / VPN CIDR. Never leave it- open to `0.0.0.0/0` long-term.-- **Everything else** β drop. In particular, the ingress port (`:8000`), the- agent server (`:18000`), the automation backend (`:18001`), and the Vite- dev server (`:3001`) must not be reachable from outside the host.--If you are running inside Kubernetes, use a `NetworkPolicy` to the same effect:-deny all ingress by default and only allow what you explicitly need.+- **Inbound 22 (SSH)** β restrict to your own IP / VPN CIDR.+- **Everything else** β drop. The ingress port (`:8000`), agent server+ (`:18000`), automation backend (`:18001`), and static server (`:3001`)+ must not be reachable from outside the host.At this point your machine is reachable only over SSH. That's enough to runthe agent (step 3) and access the UI through an SSH tunnel. If you also wantto reach it from a browser without tunneling, you'll open ports 80 and 443-in the optional domain + nginx step (step 4).--For an extra host-level backstop, see-[Advanced: defense in depth](#advanced-defense-in-depth) at the end of this-document.+in step 4.-## 3. Run the server+## 3. Run Agent CanvasInstall the prerequisites on the machine. On Ubuntu:@@ -124,87 +106,104 @@ curl -LsSf https://astral.sh/uv/install.sh | shOn macOS (Mac Mini, etc.) install Node and `uv` via `brew` instead.-Clone this repo, install dependencies, and start the server:+Start Agent Canvas in public mode:```bash-git clone https://github.com/OpenHands/agent-canvas.git-cd agent-canvas-npm install-npm run dev+export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32) # generate once; store securely+npx @openhands/agent-canvas --public```-> [!WARNING]-> `npm run dev` runs the agent server **directly on the host**.-> The agent has full access to the machine's filesystem, environment, and-> network. That is exactly why the firewall (step 2) and the-> `SESSION_API_KEY` below are non-negotiable: they are what stop a stranger-> from walking in and getting that same access.--The ingress proxy binds to `127.0.0.1:8000`, and the underlying agent server,-automation backend, and Vite dev server all bind to `127.0.0.1` as well β so-they're only reachable from the machine itself.+Using `export` keeps the key out of the process list (`ps aux`). The+`openssl rand -base64 32` command generates a cryptographically random+256-bit key β copy the printed value somewhere safe before proceeding.-## 4. (Optional) Get a domain and put nginx + Let's Encrypt + basic auth in front+This single command downloads the latest release, starts the agent server,+the automation backend, and the static frontend, and fronts them with an+ingress proxy on `127.0.0.1:8000`.-If you want to reach the UI from a browser without an SSH tunnel β for-example, to use it from a phone or a machine you can't easily forward ports-from β point a domain at the host and front it with nginx + TLS + HTTP basic-auth. nginx terminates TLS, requires basic auth, and forwards to the ingress-on `127.0.0.1:8000`.--### Point a domain at the machine+To keep the service running after your SSH session ends, use a process manager.-Register a domain (or use one you already own) and create an `A` record-pointing to the machine's public IPv4 β for example `canvas.example.com`.-Verify DNS has propagated:+**Option A β tmux (quick):**```bash-dig +short canvas.example.com+export LOCAL_BACKEND_API_KEY=<your-saved-key>+tmux new-session -d -s canvas 'npx @openhands/agent-canvas --public'+# Reconnect later with: tmux attach -t canvas```-### Open ports 80 and 443+**Option B β systemd (recommended for long-term deployments):**-Go back to your network firewall and additionally allow inbound:+Create `/etc/systemd/system/agent-canvas.service`:-- **Inbound 80 (HTTP)** β open to `0.0.0.0/0`. Let's Encrypt's HTTP-01- challenge verifies from many IPs worldwide, so this must be world-open- during issuance and renewal. nginx will redirect it to HTTPS.-- **Inbound 443 (HTTPS)** β this is what you'll actually use. Restrict to- your own IP / VPN CIDR if you can. If you need it world-open (e.g. you- roam often), basic auth + `SESSION_API_KEY` become your primary defense.+```ini+[Unit]+Description=Agent Canvas+After=network.target-### Install nginx, certbot, and helpers+[Service]+Environment=LOCAL_BACKEND_API_KEY=<your-key>+ExecStart=npx @openhands/agent-canvas --public+Restart=on-failure+RestartSec=5-```bash-apt-get install -y nginx certbot python3-certbot-nginx apache2-utils acl+[Install]+WantedBy=multi-user.target```-### Create a basic-auth user+Then enable and start the unit:```bash-mkdir -p /root/.openhands-htpasswd -c /root/.openhands/.htpasswd <username> # first user only; -c overwrites-# Add more users without -c:-# htpasswd /root/.openhands/.htpasswd <another-user>+sudo systemctl daemon-reload+sudo systemctl enable --now agent-canvas```-If you keep the password file under `/root` (mode `0700`), nginx workers run-as `www-data` and cannot traverse into it. Grant just enough access with-POSIX ACLs instead of loosening `/root`:+> [!WARNING]+> The agent server runs **directly on the host** with full access to the+> machine's filesystem, environment, and network. The firewall (step 2) and+> the `LOCAL_BACKEND_API_KEY` are what stop a stranger from getting that+> same access.++The `--public` flag means anyone who opens the UI must enter the API key+before they can use it. Without `--public`, the key is auto-injected into+the frontend (convenient for local-only use, but unsafe for a+publicly-reachable deployment).++## 4. (Optional) Get a domain and put nginx + Let's Encrypt in front++If you want to reach the UI from a browser without an SSH tunnel β for+example, from a phone or a machine you can't easily forward ports from β+point a domain at the host and front it with nginx + TLS. nginx terminates+TLS and forwards to the ingress on `127.0.0.1:8000`.++### Point a domain at the machine++Create an `A` record pointing to the machine's public IPv4 β for example+`canvas.example.com`. Verify DNS has propagated:```bash-setfacl -m u:www-data:--x /root-setfacl -m u:www-data:r-- /root/.openhands/.htpasswd-sudo -u www-data cat /root/.openhands/.htpasswd >/dev/null && echo OK+dig +short canvas.example.com```-Re-apply these ACLs whenever the htpasswd file is recreated.+### Open ports 80 and 443++Go back to your network firewall and additionally allow inbound:++- **Inbound 80 (HTTP)** β open to `0.0.0.0/0` (required for Let's Encrypt+ HTTP-01 challenges). nginx will redirect all traffic to HTTPS.+- **Inbound 443 (HTTPS)** β restrict to your own IP / VPN CIDR if you can.+ If you need it world-open (e.g. you roam often), `LOCAL_BACKEND_API_KEY`+ is your primary defense.++### Install nginx and certbot++```bash+apt-get install -y nginx certbot python3-certbot-nginx+```### nginx site configDrop this at `/etc/nginx/sites-available/canvas.example.com`, replacing-`canvas.example.com` with your domain. Agent Canvas's default ingress port is-`8000`.+`canvas.example.com` with your domain:```nginxserver {@@ -212,16 +211,11 @@ server {listen [::]:80;server_name canvas.example.com;- # Allow ACME HTTP-01 challenges through without auth.location /.well-known/acme-challenge/ {- auth_basic off;root /var/www/html;}location / {- auth_basic "Restricted";- auth_basic_user_file /root/.openhands/.htpasswd;-proxy_pass http://127.0.0.1:8000;proxy_http_version 1.1;proxy_set_header Host $host;@@ -238,80 +232,44 @@ server {}```-Enable and reload:+Enable, test, and issue a certificate:```bashln -sf /etc/nginx/sites-available/canvas.example.com \/etc/nginx/sites-enabled/canvas.example.comnginx -t && systemctl reload nginx-```-### Issue a certificate--```bashcertbot --nginx -d canvas.example.com \--non-interactive --agree-tos \--email [email protected] \--redirect```-`certbot` rewrites the file to add a `listen 443 ssl` block and a 301 from-HTTP to HTTPS. The basic-auth `location /` and the-`/.well-known/acme-challenge/` exception are preserved.--`certbot` installs a systemd timer (`certbot.timer`) that auto-renews twice a-day; nginx is reloaded automatically on success.+`certbot` adds the `listen 443 ssl` block, a 301 redirect from HTTP to+HTTPS, and installs a systemd timer for auto-renewal.### Verify```bash-curl -I https://canvas.example.com/ # β 401 Unauthorized-curl -I -u <user>:<pass> https://canvas.example.com/ # β 200-curl -I http://canvas.example.com/ # β 301 to https+curl -I https://canvas.example.com/ # β 200 (shows API key entry screen)+curl -I http://canvas.example.com/ # β 301 to https```If you see `502 Bad Gateway`, the app on `127.0.0.1:8000` is down β check-`journalctl -u agent-canvas -f`.--### Smoke-test from your laptop+whether the `npx` process is still running.-Open `https://canvas.example.com/`, enter your basic-auth credentials, and-confirm that you land in Agent Canvas. Conversations, settings, and the LLM-provider picker all hit `/api/*` routes that are guarded by both basic auth-(at nginx) and `X-Session-API-Key` (at the agent server). If the API calls-return `401`, the persisted session key and the one baked into the frontend-have drifted apart β delete `~/.openhands/agent-canvas/session-api-key.txt`-and restart the app so both sides regenerate from the same value.+Open `https://canvas.example.com/` in a browser, enter your+`LOCAL_BACKEND_API_KEY`, and confirm that you land in Agent Canvas.## 5. (Optional) Connect your local Agent Canvas to the remote machine-If you already run Agent Canvas locally (e.g. via `npm run dev` on your-laptop), you can register the remote machine as an additional backend and-flip between local and remote from the UI β no need to keep a browser tab-open against the remote domain.--1. On the remote machine, read the auto-generated session key:-- ```bash- cat ~/.openhands/agent-canvas/session-api-key.txt- ```+If you already run Agent Canvas locally, you can register the remote machine+as an additional backend and switch between local and remote from the UI.-2. In your local Agent Canvas, open **Manage backends** and click- **Add a backend**. Fill in:+1. In your local Agent Canvas, open **Manage backends** β **Add a backend**:- **Host Name** β anything memorable, e.g. `my-vm`.- - **Host** β the URL you exposed in step 4, e.g. `https://canvas.example.com`.- If you skipped step 4 and are using an SSH tunnel, use the forwarded- local URL (e.g. `http://localhost:8000`) while the tunnel is open.- - **Session API key** β the value from `session-api-key.txt`.-3. Save. The new backend should show up as "Connected" with the remote- server's version. Pick it from the backend switcher in the menu and the- UI will start talking to the remote machine.--> [!NOTE]-> If you put nginx basic auth in front of the remote (step 4), the browser-> needs the basic-auth credentials too. The easiest way is to visit-> `https://canvas.example.com/` in the same browser first and authenticate-> β the browser will cache the credentials and reuse them for the-> cross-origin `/api/*` calls made by your local Agent Canvas. Alternatively,-> skip basic auth and rely on the cloud firewall + `SESSION_API_KEY` for-> protection.+ - **Host** β the URL from step 4, e.g. `https://canvas.example.com`.+ If using an SSH tunnel instead, use `http://localhost:8000`.+ - **Session API key** β the `LOCAL_BACKEND_API_KEY` you chose in step 3.+2. Save. The new backend should show as "Connected". Pick it from the+ backend switcher to talk to the remote machine.