Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt

Use this file to discover all available pages before exploring further.

Use --backend-only to run the backend on a remote machine, then connect from your local frontend with --frontend-only.
The agent server can read and write the host filesystem, execute shell commands, and access the network. Lock down the machine before starting.

​
1. Provision and Secure the Machine

Any always-on Linux or macOS host:
  • Cloud VM — Ubuntu 24.04 LTS, 2 vCPU / 4 GB RAM is enough for a single user.
  • Dedicated hardware — Mac Mini, Intel NUC, spare laptop.
Lock down inbound traffic before starting the backend:
  • Port 22 (SSH) — your IP or VPN CIDR only.
  • Everything else — drop.

​
2. Install Prerequisites

On Ubuntu: 
apt-get update && apt-get install -y curl git

# Node.js 22.x (via nvm, asdf, or NodeSource)
# uv (for the agent server runtime):
curl -LsSf https://astral.sh/uv/install.sh | sh
On macOS, install Node and uv via Homebrew instead.

​
3. Start the Backend

LOCAL_BACKEND_API_KEY=<choose-a-strong-secret> npx @openhands/agent-canvas --backend-only --public
  • --backend-only starts only the backend (no frontend).
  • --public requires LOCAL_BACKEND_API_KEY — every API request must carry a matching X-Session-API-Key header.
To also serve the UI from the VM (e.g. to access it from a phone), drop --backend-only. With the full stack, --public requires users to enter the API key in the UI before interacting with the agent.

​
4. Connect from Your Local Machine

On your laptop, start the frontend: 
agent-canvas --frontend-only
Then add the VM as a backend:
  1. Click the backend switcher → Manage Backends → Add Backend.
  2. Fill in:
    • Name — e.g. my-vm
    • Host / Base URL — http://localhost:8000 (if using an SSH tunnel) or the VM’s URL if you’ve set up a reverse proxy
    • API Key — the LOCAL_BACKEND_API_KEY from step 3
  3. Save and select it as the active backend.

​
Using an SSH Tunnel

The simplest way to reach the backend without exposing ports: 
ssh -L 8000:127.0.0.1:8000 user@your-vm
Then use http://localhost:8000 as the backend URL.

​
5. (Optional) Add a Domain with nginx + TLS

If you want direct HTTPS access without an SSH tunnel, point a domain at the machine and front it with nginx + Let’s Encrypt.

​
Point a Domain at the Machine

Create an A record pointing to the machine’s public IP (e.g. canvas.example.com): 
dig +short canvas.example.com

​
Open Ports 80 and 443

Update your network firewall to additionally allow:
  • Port 80 (HTTP) — open to 0.0.0.0/0 (required for Let’s Encrypt HTTP-01 challenges). nginx redirects all HTTP to HTTPS.
  • Port 443 (HTTPS) — restrict to your IP if possible. If you need it world-open, LOCAL_BACKEND_API_KEY is your primary defense.

​
Install nginx and Certbot

apt-get install -y nginx certbot python3-certbot-nginx

​
Configure nginx

Save this at /etc/nginx/sites-available/canvas.example.com, replacing the domain: 
server {
    listen 80;
    listen [::]:80;
    server_name canvas.example.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        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 the site and issue a certificate: 
ln -sf /etc/nginx/sites-available/canvas.example.com \
       /etc/nginx/sites-enabled/canvas.example.com
nginx -t && systemctl reload nginx

certbot --nginx -d canvas.example.com \
    --non-interactive --agree-tos \
    --email you@example.com \
    --redirect

​
Verify

curl -I https://canvas.example.com/      # → 200
curl -I http://canvas.example.com/       # → 301 redirect to HTTPS
Use https://canvas.example.com as the Host / Base URL when adding the backend in Manage Backends.

​
Security Checklist

Before exposing the backend to a broader network:
  1. Restrict inbound network access — only open ports you need (SSH, 80/443 for the reverse proxy).
  2. Use --public mode with a strong LOCAL_BACKEND_API_KEY.
  3. Use TLS — put a reverse proxy in front with Let’s Encrypt if the backend is internet-reachable.
  4. Treat the host as sensitive infrastructure — it stores secrets, conversations, and working copies.