HiClaw Platform

Multi-tenant SaaS orchestration layer for HiClaw — deploy isolated AI agent teams for every user with a single docker compose up.

中文文档

What is this?

HiClaw Platform manages the lifecycle of HiClaw tenants. Each tenant gets a fully isolated container with its own Matrix server (Tuwunel), AI gateway (Higress), file storage (MinIO), web chat (Element Web), and agent runtime (OpenClaw). The platform handles user registration, tenant provisioning, LLM configuration, and system monitoring through a web dashboard and REST API.

Architecture

                         ┌─────────────────────────┐
                         │      Nginx (18080)       │
                         │     Reverse Proxy        │
                         └────────┬────────────────-┘
                                  │
                    ┌─────────────┴──────────────┐
                    │                            │
             ┌──────┴──────┐           ┌─────────┴─────────┐
             │  Platform   │           │  Shared Infra     │
             │  (FastAPI)  │           │  (Tuwunel+Higress │
             │  Auth, API  │           │   +MinIO+Element) │
             │  Dashboard  │           └───────────────────┘
             └──────┬──────┘
                    │ Docker API
      ┌─────────────┼─────────────┐
      │             │             │
┌─────┴─────┐┌─────┴─────┐┌─────┴─────┐
│ Tenant 1  ││ Tenant 2  ││ Tenant N  │
│ Manager   ││ Manager   ││ Manager   │
│ + Workers ││ + Workers ││ + Workers │
│ (19010+)  ││ (19020+)  ││ (19N0+)   │
└───────────┘└───────────┘└───────────┘

Quick Start

Prerequisites: Docker 24+, Docker Compose v2, 8GB+ RAM

# 1. Clone
git clone https://github.com/davidfrz/hiclawPlatform.git
cd hiclaw-platform

# 2. Configure
cp .env.example .env
# Edit .env — set PLATFORM_EXTERNAL_HOST to your server's IP or domain

# 3. Generate secrets
bash scripts/init.sh

# 4. Start
docker compose up -d

# 5. Open
# Dashboard: http://your-server-ip:18080
# Login with the admin credentials printed by init.sh

Features

• Multi-tenant isolation — Each tenant runs in its own Docker container with a dedicated network
• Self-service provisioning — Users register, configure their LLM API key, and get a running HiClaw instance
• Admin dashboard — Real-time system monitoring (CPU, memory, disk), tenant management, batch operations
• LLM BYOK — Tenants bring their own API keys; supports OpenAI-compatible providers
• Zero-downtime upgrades — Rolling upgrade of tenant containers via API
• Secret management — Auto-generated secrets, encrypted API key storage

Configuration

All configuration is done through .env. See .env.example for all available options.

Variable	Required	Description
PLATFORM_EXTERNAL_HOST	Yes	Server's public IP or domain
PLATFORM_ADMIN_PASSWORD	Auto	Platform admin login password
PLATFORM_JWT_SECRET	Auto	JWT signing secret
HICLAW_ADMIN_PASSWORD	Auto	HiClaw internal admin password
HICLAW_REGISTRATION_TOKEN	Auto	Matrix registration token
HICLAW_MINIO_PASSWORD	Auto	MinIO admin password

Variables marked "Auto" are generated by scripts/init.sh.

Admin API

Method	Endpoint	Description
GET	/api/admin/tenants	List all tenants with resource usage
GET	/api/admin/system	Server resource overview
GET	/api/admin/containers	List all HiClaw containers
GET	/api/admin/metrics/history	Historical metrics
POST	/api/admin/tenants/{id}/start	Start a tenant
POST	/api/admin/tenants/{id}/stop	Stop a tenant
POST	/api/admin/tenants/{id}/upgrade	Upgrade tenant to latest image
POST	/api/admin/tenants/upgrade-all	Batch upgrade all running tenants
DELETE	/api/admin/tenants/{id}	Delete tenant (container + data)

Full API docs available at /api/docs (Swagger UI) when the platform is running.

Upgrading Tenants

# Pull latest images
docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/hiclaw-manager:latest

# Upgrade all running tenants via API
curl -X POST http://localhost:18080/api/admin/tenants/upgrade-all \
  -H "Authorization: Bearer <admin-token>"

Roadmap

• HTTPS / Let's Encrypt — Built-in TLS termination with auto-renewing certificates
• OAuth login — GitHub / Google / Feishu SSO for tenant users
• Tenant resource quotas — Configurable CPU / memory / disk limits per tenant
• Usage metering & billing — Track LLM token usage, storage, compute hours per tenant
• Kubernetes / Helm deployment — Scale beyond single-node Docker Compose
• Tenant backup & restore — One-click export / import of tenant data (Matrix history, files, config)
• Plugin marketplace — Install and manage OpenClaw skills from a shared catalog
• Multi-node clustering — Distribute tenants across multiple servers with a scheduler
• Audit log — Record all admin and tenant operations for compliance
• Webhook / event notifications — Push tenant lifecycle events to Slack, Feishu, or custom endpoints
• Frontend i18n — Full internationalization for the dashboard (currently Chinese-only UI)
• Health checks & auto-recovery — Detect and restart unhealthy tenant containers automatically

Contributing

Contributions are welcome! Please open an issue first to discuss what you would like to change.

License

Apache License 2.0