ClawCloud

Admin-only hosting platform for OpenClaw AI agents with per-user Docker isolation, messaging channels, and subdomain routing.

Live at clawcloud.dev -- a fully deployed, one-click hosted instance if you don't want to self-host.

Overview

ClawCloud deploys personal AI agents on per-user Docker containers. A single admin provisions agents through a web dashboard -- there are no user signups or self-service accounts. Each agent gets its own subdomain, connects to WhatsApp, Telegram, Discord, and Slack, and routes all LLM traffic through OpenRouter.

Architecture

Admin Browser --> Express (port 9000) + Admin UI
                      |
             Docker containers (1 per agent)
                      |
             Caddy reverse proxy (auto-TLS)

For a comprehensive breakdown of every component, see ARCHITECTURE.md.

Features

• Per-user Docker containers -- each agent runs in full isolation with its own subdomain
• Admin dashboard -- provision, monitor, and manage agents from a single web UI
• Local JSON persistence -- agent state and configuration stored as JSON files on the VPS
• Messaging channels -- WhatsApp, Telegram, Discord, and Slack support
• Caddy auto-TLS -- automatic Let's Encrypt certificates for all subdomains
• Idle cleanup -- inactive containers deprovisioned after 60 minutes of inactivity
• Gateway auth -- HMAC-signed cookie authentication for agent web UIs

Prerequisites

Requirement	Version / Notes
Node.js	18+
Docker	24+
Ubuntu VPS	8GB+ RAM, 150GB+ disk recommended
Domain with DNS control	Wildcard DNS required (*.yourdomain.com)
OpenRouter API key	Required for LLM access
Caddy	Installed on VPS for reverse proxy + auto-TLS

Quick Start

1. Clone and Install

git clone https://github.com/your-org/ClawCloud.git
cd ClawCloud/infrastructure/dashboard
npm install

2. Configure

cd infrastructure
cp defaults.json.example defaults.json
# Edit defaults.json with your domain, API key, and admin password

3. VPS Setup

On your Ubuntu VPS:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

# Configure wildcard DNS
# Point *.yourdomain.com and yourdomain.com to your VPS IP in your DNS provider

4. Deploy

Set the VPS host and run the deploy script from your local machine:

export VPS_HOST=root@your-vps-ip
export VPS_SHARED_SECRET=$(openssl rand -hex 32)
bash infrastructure/deploy.sh

This syncs infrastructure files, pulls the Docker image, installs dependencies, and creates a systemd service for the Express dashboard server.

5. Access the Admin Dashboard

Open https://admin.yourdomain.com in your browser and log in with the adminPassword from defaults.json. Provision agents directly from the admin UI.

Configuration

infrastructure/defaults.json

Key	Description
domain	Root domain, e.g. yourdomain.com
model	Default LLM model for new agents
openrouterKey	OpenRouter API key (injected into agent auth config)
maxConcurrent	Max concurrent LLM requests per agent (default: 4)
subagentMaxConcurrent	Max concurrent sub-agent requests (default: 8)
dockerImage	Docker image for new containers (default: ghcr.io/openclaw/openclaw:latest)
adminPassword	Admin dashboard password

Project Structure

ClawCloud/
├── infrastructure/
│   ├── dashboard/              Express.js server + admin UI
│   │   ├── server.js           Entry point
│   │   ├── routes/             API routes (provision, gateway, admin)
│   │   ├── lib/                Auth, cache, Docker, Caddy
│   │   └── public/             Admin dashboard frontend
│   ├── templates/              Agent config templates
│   ├── deploy.sh               VPS deployment script
│   └── defaults.json.example   VPS configuration template
├── ARCHITECTURE.md             Comprehensive architecture documentation
├── CONTRIBUTING.md             Contribution guidelines
└── LICENSE                     MIT License

Security

Threat Model

ClawCloud is designed as a single-admin, self-hosted platform. The threat model assumes:

• The admin is trusted. All provisioning, configuration, and container management is admin-only. There are no user signups or self-service accounts.
• The VPS is a trust boundary. All sensitive files (API keys, tokens, profiles) live on the VPS filesystem. Access to the VPS implies full control.
• Caddy is the network boundary. All external traffic flows through Caddy with auto-TLS. The Express server on port 9000 should not be directly accessible from the internet.

File Permissions

The following files contain sensitive data and must have restricted permissions on the VPS:

File	Contains	Required Permissions
/data/clawcloud/defaults.json	Admin password, API keys, domain config	chmod 600 (owner-only)
/data/clawcloud/profiles.json	All user gateway tokens	chmod 600 (owner-only)
/data/clawcloud/.env	VPS_SHARED_SECRET for HMAC gateway cookies	chmod 600 (owner-only)

Set these permissions after initial setup:

chmod 600 /data/clawcloud/defaults.json /data/clawcloud/profiles.json /data/clawcloud/.env

Firewall

The Express dashboard binds to 0.0.0.0:9000. Configure your VPS firewall to block external access to this port — all traffic should flow through Caddy:

# Allow only SSH, HTTP, HTTPS from the internet
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw deny 9000/tcp
ufw enable

License

MIT