Skip to content

πŸ™Œ 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.md
new file mode 100644
index 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.