VM / Self-Hosted Backend

Run Agent Canvas on a VM or dedicated machine and connect to it remotely.

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 [e-mail] \
    --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.

Related Guides

• Connect and Manage Backends
• Local Backend
• Docker Backend
• Cloud Backend