VPS Quickstart

Use the single installer to deploy ClawNex to a Linux VPS with systemd, Caddy, HTTPS, and localhost-only dashboard/LiteLLM backends.

Prerequisites

Ubuntu 22.04/24.04 LTS or Debian 12+
Sudo access
A domain A record pointing at the VPS public IP
Ports 80 and 443 reachable from the internet
OpenClaw installed on the VPS with ~/.openclaw/openclaw.json
Internet access for package, npm, pip, GitHub, and Let’s Encrypt operations

Deployment

Clone the repository on the VPS

git clone https://github.com/ClawNexAi/clawnex.git ~/clawnex
cd ~/clawnex

Run the installer

Interactive VPS install:

bash install.sh

Noninteractive VPS install:

bash install.sh --mode vps --domain qa.example.com --provider skip --clean --yes

Create the first admin

When the installer completes, it prints a one-time setup URL:

https://qa.example.com/setup?secret=...

Open that URL and create the first admin account.

Recover the setup secret later from the install checkout:

grep SETUP_SECRET ~/clawnex/.env.local

Verify

curl -fsS https://qa.example.com/api/health && echo
sudo systemctl is-active clawnex-dashboard
sudo systemctl is-active clawnex-litellm
sudo systemctl is-active caddy
curl -fsS http://127.0.0.1:4001/health/liveliness && echo

What the Installer Does

Step	Action
1	Confirms VPS mode and domain
2	Checks and installs host dependencies before continuing
3	Locates OpenClaw and validates `openclaw.json`
4	Performs clean-slate cleanup when requested, including ClawNex-owned port listeners
5	Installs npm dependencies and LiteLLM 1.83.0
6	Generates `.env` and `.env.local` with public-domain auth settings
7	Builds the Next.js standalone dashboard
8	Installs Caddy and writes the managed Caddyfile
9	Installs `clawnex-dashboard.service` and `clawnex-litellm.service`
10	Opens ports 80/443 through UFW when UFW is active
11	Starts services and triggers the first Let’s Encrypt certificate handshake
12	Runs dashboard, LiteLLM, setup-gate, and best-effort CVE verification

Services

sudo systemctl status clawnex-dashboard
sudo systemctl restart clawnex-dashboard
sudo journalctl -u clawnex-dashboard -f
 
sudo systemctl status clawnex-litellm
sudo systemctl restart clawnex-litellm
sudo journalctl -u clawnex-litellm -f
 
sudo systemctl status caddy
sudo journalctl -u caddy -f

The installer also writes a scoped sudoers rule so the dashboard can start, stop, and restart only the LiteLLM service.

Ports

Port	Service	Binding	Purpose
80	Caddy	public	HTTP to HTTPS redirect and ACME challenge
443	Caddy	public	HTTPS dashboard access
5001	Dashboard	`127.0.0.1`	Next.js backend behind Caddy
4001	LiteLLM	`127.0.0.1`	AI model proxy and shield path

⚠️

Do not expose ports 5001 or 4001 directly on a VPS. Public traffic should enter through Caddy on 443.

Upgrading or Reinstalling

Run the current repository installer again:

cd ~/clawnex
git pull
bash install.sh --mode vps --domain qa.example.com --clean

When existing artifacts are detected, the installer asks before removing them. If a database is present, it asks whether to archive it before cleanup unless you pass --archive-db yes or --archive-db no.

Uninstall

From the install checkout:

cd ~/clawnex
bash scripts/uninstall.sh

For a noninteractive teardown on a test VPS:

bash ~/clawnex/scripts/uninstall.sh --force-clean ~/clawnex

Skip the pre-uninstall database archive only when you are sure you do not need the local ClawNex database:

bash ~/clawnex/scripts/uninstall.sh --force-clean --no-archive ~/clawnex

The VPS uninstall path stops and removes clawnex-dashboard.service and clawnex-litellm.service, removes the scoped sudoers rule, removes ClawNex-managed Caddy config, removes runtime files, and restores OpenClaw routing from the first-touch backup when available. It does not delete OpenClaw or Caddy certificate storage.

Troubleshooting

Issue	Command
Dashboard will not start	`sudo journalctl -u clawnex-dashboard -f`
LiteLLM will not start	`sudo journalctl -u clawnex-litellm -f`
Caddy/TLS issue	`sudo journalctl -u caddy -f`
Check listeners	`sudo ss -ltnp`
LiteLLM liveliness	`curl -fsS http://127.0.0.1:4001/health/liveliness && echo`

Standalone Development Setup