Runtime Architecture

ClawNex installs as a local application with a dashboard, a LiteLLM proxy, local storage, and a service layer appropriate for the host operating system.

This page explains how ClawNex runs on macOS, Linux VPS hosts, and source-based local installs.

Runtime Components

Component	Default Port	Binding	Purpose
ClawNex Dashboard	5001	`127.0.0.1`	Web UI, internal API, public API, auth, audit, reports
LiteLLM Proxy	4001	`127.0.0.1`	OpenAI-compatible model proxy and shield path
OpenClaw Gateway	18789	Local gateway	Agent inventory and routing integration
Caddy	80/443	Public in server modes	HTTPS reverse proxy
SQLite	File-backed	Local filesystem	Operational database

Public traffic should enter through Caddy on 443. Backend ports should remain local.

Install Modes

The repository installer detects the host and asks the operator to confirm the deployment approach.

Mode	Service Manager	Public HTTPS	RBAC
macOS local	launchd	No	Operator chooses on/off
macOS server	launchd	Yes, Caddy	On
Linux VPS	systemd	Yes, Caddy	On
Development	npm/dev server	No	Environment controlled

Public-facing modes always use RBAC.

Linux VPS Runtime

A Linux VPS install creates:

clawnex-dashboard.service
clawnex-litellm.service
managed Caddy reverse proxy config
local LiteLLM virtual environment
generated .env and .env.local
local SQLite database
scoped sudoers rule for LiteLLM service restart from the dashboard

The dashboard and LiteLLM run as local services. Caddy terminates TLS and proxies the dashboard.

macOS Runtime

A macOS local install uses launchd to keep ClawNex services running. Local mode is intended for a single machine and does not require a public domain.

A macOS server install uses launchd plus Caddy for public HTTPS, similar to VPS mode, but with macOS service management.

Dependency Checks

The installer checks dependencies before continuing. It should either install or guide the operator through required updates, then abort cleanly when a hard dependency cannot be satisfied.

Key dependencies:

Dependency	Purpose
Node.js 22.x	Dashboard build and runtime
npm	JavaScript dependencies
Python 3.10+	LiteLLM runtime
Git	Repository checkout and updates
Caddy	HTTPS reverse proxy in server modes
systemd or launchd	Service management

Service Lifecycle

After installation, operators can manage services through the dashboard or CLI.

Common operations:

clawnex status
clawnex start
clawnex stop
clawnex restart
clawnex logs

On Linux VPS hosts, systemd remains the source of truth for service state.

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

Provider Routing

ClawNex uses LiteLLM as the provider-routing layer. Operators can configure cloud providers such as OpenRouter, OpenAI, Anthropic, and NVIDIA NIM during install or later from the dashboard.

Local model runtimes such as LM Studio and Ollama are optional dashboard-configured endpoints. They are not the default assumption for VPS installs.

Data Storage

The local database stores:

config providers and models
traffic summaries
shield scan records
audit events
alerts and incidents
RBAC operators and sessions
trust audit results
security posture results
report metadata

Database archives are optional during clean reinstall or uninstall flows. Operators should choose whether they want to preserve the local database before destructive cleanup.

Uninstall and Cleanup

The supported uninstall path is the repository uninstaller, not deleting the folder manually.

bash scripts/uninstall.sh

For test hosts:

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

To skip database archive creation:

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

The uninstaller stops services, removes managed service definitions, removes managed Caddy config, restores OpenClaw routing when a first-touch backup exists, and removes runtime artifacts. Deleting the directory by hand can leave services running.

Health Checks

Expected checks after install:

curl -fsS https://your-domain.example/api/health
curl -fsS http://127.0.0.1:4001/health/liveliness

The LiteLLM /health endpoint may require authentication. Use /health/liveliness for a simple local process check.