π OpenHands: AI-Driven Development
Add SELF_HOSTING.md: guide for hosting Agent Canvas on a VM (#273)
Robert Brennan6a54ff261b63
diff --git a/SELF_HOSTING.md b/SELF_HOSTING.mdnew file mode 100644index 0000000000..967e74c809--- /dev/null+++ b/SELF_HOSTING.md@@ -0,0 +1,434 @@+# Self-Hosting Agent Canvas on a Virtual Machine++This guide walks through running Agent Canvas on a virtual machine (VM) so you+(and only you) can reach it from anywhere via a browser.++> [!CAUTION]+> 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.++## 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:dangerously-dockerless`+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++## Details++The deployment model:++```mermaid+flowchart LR+ user(["π§ You"])+ subgraph vm["Your VM (single host)"]+ direction LR+ nginx["nginx :443<br/>(TLS + basic auth)"]+ ingress["Ingress proxy<br/>127.0.0.1:8000"]+ vite["Vite dev server<br/>:3001"]+ agent["Agent server<br/>:18000<br/>(SESSION_API_KEY)"]+ automation["Automation backend<br/>:18001"]+ nginx --> ingress+ ingress -- "/*" --> vite+ ingress -- "/api/*, /sockets" --> agent+ ingress -- "/api/automation/*" --> automation+ end+ user -- "HTTPS / 443" --> nginx+```++`npm run dev:dangerously-dockerless` spins up the Vite dev server, the agent+server, and the automation backend, and fronts them with 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.++The defenses layered on top of this:++1. **Cloud / network firewall (step 2)** β by default nothing inbound is+ reachable except SSH from your IP. If you do step 4, you additionally open+ 80 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.++## 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.++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.++## 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.++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.++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.):++- **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.++At this point your machine is reachable only over SSH. That's enough to run+the agent (step 3) and access the UI through an SSH tunnel. If you also want+to 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.++## 3. Run the server++Install the prerequisites on the machine. On Ubuntu:++```bash+apt-get update+apt-get install -y curl git+# Node.js 22.x (use nvm, asdf, or NodeSource β whatever you prefer)+# uv (for the agent-server uvx runtime):+curl -LsSf https://astral.sh/uv/install.sh | sh+```++On macOS (Mac Mini, etc.) install Node and `uv` via `brew` instead.++Clone this repo, install dependencies, and start the server:++```bash+git clone https://github.com/OpenHands/agent-canvas.git+cd agent-canvas+npm install+npm run dev:dangerously-dockerless+```++> [!WARNING]+> `dev:dangerously-dockerless` 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.++### `SESSION_API_KEY` is auto-generated++On first run, the dev scripts generate a random `SESSION_API_KEY` and persist+it to `~/.openhands/agent-canvas/session-api-key.txt`. The same value is wired+into both the agent server (which refuses any `/api/*` request without a+matching `X-Session-API-Key` header) and the frontend (which sends it on every+request), and it stays stable across restarts. You don't need to configure+anything.++To rotate the key, delete the file and restart the app. To pin a specific+value instead of the auto-generated one, export `SESSION_API_KEY` before+starting β it takes precedence over the persisted file.++> [!IMPORTANT]+> Treat the key file like an SSH private key. Anyone who learns its value can+> drive your agent. Keep it on the machine and don't copy it elsewhere.++### Access the UI over an SSH tunnel++With just steps 1β3 done, the simplest way to use the UI is to forward the+ingress port over SSH from your laptop:++```bash+ssh -L 8000:127.0.0.1:8000 your-vm+# then open http://localhost:8000 in your browser+```++No public ports, no nginx, no TLS to manage β the SSH connection is what+authenticates and encrypts you. This is a great starting point and a good+fallback for debugging.++### Keep it running across reboots++Wrap the command in a `systemd` unit, a `tmux`/`screen` session, or a process+manager like `pm2`. A minimal Linux `systemd` unit:++```ini+# /etc/systemd/system/agent-canvas.service+[Unit]+Description=Agent Canvas+After=network.target++[Service]+Type=simple+WorkingDirectory=/root/agent-canvas+ExecStart=/usr/bin/npm run dev:dangerously-dockerless+Restart=on-failure+User=root++[Install]+WantedBy=multi-user.target+```++```bash+systemctl daemon-reload+systemctl enable --now agent-canvas+journalctl -u agent-canvas -f+```++On macOS, use `launchd` (a `LaunchAgent`/`LaunchDaemon` plist) for the same+effect.++## 4. (Optional) Get a domain and put nginx + Let's Encrypt + basic auth in front++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++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:++```bash+dig +short canvas.example.com+```++### 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`. 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.++### Install nginx, certbot, and helpers++```bash+apt-get install -y nginx certbot python3-certbot-nginx apache2-utils acl+```++### Create a basic-auth user++```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>+```++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`:++```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+```++Re-apply these ACLs whenever the htpasswd file is recreated.++### nginx site config++Drop this at `/etc/nginx/sites-available/canvas.example.com`, replacing+`canvas.example.com` with your domain. Agent Canvas's default ingress port is+`8000`.++```nginx+server {+ listen 80;+ 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;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header X-Forwarded-Proto $scheme;++ # WebSocket / SSE support β required for live agent events.+ proxy_set_header Upgrade $http_upgrade;+ proxy_set_header Connection "upgrade";+ proxy_read_timeout 3600s;+ proxy_send_timeout 3600s;+ }+}+```++Enable and reload:++```bash+ln -sf /etc/nginx/sites-available/canvas.example.com \+ /etc/nginx/sites-enabled/canvas.example.com+nginx -t && systemctl reload nginx+```++### Issue a certificate++```bash+certbot --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.++### 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+```++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++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.++## 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+ ```++2. In your local Agent Canvas, open **Manage backends** and click+ **Add a backend**. Fill in:+ - **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.++## Operational tips++- **Rotate the basic-auth password and `SESSION_API_KEY` periodically**,+ especially after offboarding anyone who had access. `htpasswd` changes take+ effect on the next request β no nginx reload needed. To rotate the session+ key, delete `~/.openhands/agent-canvas/session-api-key.txt` and restart the+ app.+- **Keep the VM patched** (`unattended-upgrades` is fine for Ubuntu).+- **Back up `~/.openhands-dev/` (or wherever conversations are persisted)**+ if you care about conversation history. Treat the backup as sensitive β it+ contains transcripts, secrets, and possibly auth tokens.+- **Watch the logs.** `journalctl -u agent-canvas`,+ `/var/log/nginx/access.log`, and `/var/log/nginx/error.log` are your friends+ when something looks off. Repeated 401s in the access log are normal scanner+ noise; a successful 200 from an IP you don't recognize is not.+- **Do not expose the ingress (`:8000`) or backend ports (`:18000`, `:18001`,+ `:3001`) directly.** Only `:443` (via nginx) should be reachable from+ outside. If you need to debug, tunnel over SSH+ (`ssh -L 8000:127.0.0.1:8000 vm`) rather than opening a port in the firewall.++## Advanced: defense in depth++The cloud firewall (step 2) is your primary network perimeter. If you want an+extra backstop in case it is ever misconfigured β for example, a teammate+relaxes a rule, a Terraform diff lands wrong, or you migrate to a provider+whose firewall fails open during maintenance β also enable a host-level+firewall on the VM itself.++With `ufw` on Ubuntu:++```bash+ufw default deny incoming+ufw default allow outgoing+ufw allow 22/tcp+ufw allow 80/tcp+ufw allow 443/tcp+ufw enable+```++And confirm the ingress, agent server, automation backend, and Vite ports are+bound to `127.0.0.1` only, so even if a firewall rule slips, none of them are+reachable from outside the host:++```bash+ss -tlnp+# expect 127.0.0.1:8000 (ingress)+# 127.0.0.1:18000 (agent server)+# 127.0.0.1:18001 (automation backend)+# 127.0.0.1:3001 (Vite dev server)+# never 0.0.0.0:* or :::* for any of those+```++If you ever see one of those ports listening on `0.0.0.0` or `::`, stop the+app immediately and investigate before re-enabling it.