Customer portal
Website
← Knowledge Base

Deploy OpenClaw on a VPS: a private AI assistant for work

OpenClaw is an agent runtime: it connects a model to tools and conversations. Use a separate VPS to evaluate a work assistant without giving it your laptop’s files or company production credentials. This guide starts with a private, restricted assistant; email, browser and shell integrations are deliberate later steps, not enabled here.

Target: Ubuntu Server 24.04 LTS, x86-64, SSH and a sudo account. Documentation reviewed 15 November 2026. Commands have not been tested end to end on Ubuntu.

Before you start

Plan roughly 2 vCPUs, 4 GB RAM and 20 GB free disk for the prebuilt gateway using an external model API. Larger browser workloads need more. Local inference has separate model-memory requirements; API subscriptions and usage charges are separate from VPS hosting.

Resource figures are planning estimates for a small evaluation, not performance guarantees or plan specifications. A VPS/VDS does not imply a GPU. Check available memory, storage and resources before ordering.

On a fresh Ubuntu installation, use the packages below. If Docker is already installed from another repository, keep that installation and check compatibility first: do not mix Docker CE and docker.io packages. Use Compose v2; if the package is missing, check that Ubuntu Universe is enabled.

sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version

All examples publish ports only on the server’s 127.0.0.1. Access them from your computer through an SSH tunnel; a domain is unnecessary. Do not open these ports to the Internet. An internal container listener on 0.0.0.0 does not change the host’s loopback-only published port.

Each project below is a new installation. Do not rerun secret-generation steps against an existing deployment.

1. Create an isolated project

Keep the gateway token in this private environment file. Named volumes retain state and the separate authentication-profile secret directory; no host Docker socket or personal home directory is mounted. Save the following configuration as compose.yaml.

umask 077
mkdir -p ~/ai-openclaw
cd ~/ai-openclaw
printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env
services:
  gateway:
    image: ghcr.io/openclaw/openclaw:latest
    init: true
    restart: unless-stopped
    env_file: .env
    environment:
      HOME: /home/node
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - state:/home/node/.openclaw
      - auth:/home/node/.config/openclaw
    cap_drop: [NET_RAW, NET_ADMIN]
    security_opt: [no-new-privileges:true]
    command: ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]
volumes:
  state:
  auth:

2. Onboard before starting the gateway

Run the interactive wizard. Select an available provider/model, supply your own API credentials, keep token authentication and skip channels for now. Use the token from your private .env when asked for a gateway token. Do not install a host daemon inside the container. Then restrict tools and allow only the two local browser origins used by the SSH tunnel.

sudo docker compose pull
sudo docker compose run --rm --no-deps --entrypoint node gateway dist/index.js onboard --mode local --no-install-daemon
sudo docker compose run --rm --no-deps --entrypoint node gateway dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]},{"path":"tools.profile","value":"minimal"}]'
sudo docker compose up -d gateway
sudo docker compose exec gateway node dist/index.js security audit --deep

3. Connect and test a harmless task

On your own computer, replace YOUR_USER and YOUR_SERVER_IP and leave this SSH session open. Open http://127.0.0.1:18789, authenticate with the gateway token and approve only your own device if pairing is requested. Ask for a summary of nonconfidential sample text. A responding model verifies chat, not permission to run commands.

ssh -N -L 127.0.0.1:18789:127.0.0.1:18789 YOUR_USER@YOUR_SERVER_IP

4. Add work integrations deliberately

The minimal tool profile is intentionally limited; review the audit before granting a specific capability. Use separate credentials with narrow scope, require approval for consequential actions and keep untrusted content from deciding permissions. Containerization alone is not an agent sandbox. Never mount the Docker socket to make a task easier. Back up both named volumes and .env; losing either authentication state or its keys can break recovery.

Updates and recovery

Before upgrading, stop the application for a consistent backup, keep data and secrets off the VPS, and test recovery on a separate instance. Moving image tags in these examples are for initial evaluation; pin a reviewed release tag or digest before ongoing use. Record the current digest with sudo docker image inspect IMAGE_NAME --format '{{json .RepoDigests}}'. Avoid unattended upgrades without compatibility checks, and do not delete persistent volumes with down -v.

If startup fails, inspect sudo docker compose ps, recent logs, free disk and memory. Do not share logs containing keys, prompts or personal data. For directory-permission errors, check the expected UID/GID and ownership instead of granting 777. Set up HTTPS, authentication and request limits before sharing access.

Related deployments