feat(platform): add multi-tenant orchestrator (zcplatform)

Introduces zcplatform — a Rust/Axum backend + React/TypeScript SPA that
provisions, isolates, and manages multiple ZeroClaw agent instances as
Docker containers with per-tenant config, channels, and monitoring.

Backend (Rust/Axum):
- OTP + JWT auth with RBAC (Viewer/Contributor/Manager/Owner + super-admin)
- XChaCha20-Poly1305 vault encryption for secrets at rest
- Docker container lifecycle with security hardening (cap-drop ALL, read-only rootfs, resource limits)
- Caddy reverse proxy integration (wildcard subdomains, auto-HTTPS)
- Background tasks: health checker (30s), usage collector (5min), resource collector (60s)
- SQLite with WAL mode, single writer + N readers pool
- Tenant provisioning pipeline: slug/port/UID allocation → filesystem → config render → container → health check
- Full audit logging

Frontend (React/TypeScript/Vite):
- Dark-themed admin SPA with Tailwind CSS v4
- Setup wizard: 4-step tenant creation (name → provider → channels → deploy)
- Tenant detail: Overview, Config, Channels, Usage, Members tabs
- Schema-driven forms for 13 channel types and 14 AI providers
- React Query for server state management

Documentation (12 files):
- Vision, architecture, user flows, backend/frontend internals
- Security model, deployment guide, configuration reference
- Scaling & operations, service provider guide, API reference

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: pluginmd

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "crates/robot-kit"]
+members = [".", "crates/robot-kit", "multi_tenants"]
 resolver = "2"
 
 [package]

multi_tenants/.gitignore

@@ -0,0 +1,15 @@
+# Local config (may contain secrets)
+platform.toml
+
+# Runtime data
+data/
+
+# Build artifacts (regenerated by `npm run build`)
+static/
+
+# Planning docs (internal)
+docs/PLAN.md
+docs/assets/
+
+# Rust build artifacts
+target/

multi_tenants/Cargo.toml

@@ -0,0 +1,62 @@
+[package]
+name = "zcplatform"
+version = "0.1.0"
+edition = "2021"
+description = "ZeroClaw Multi-Tenant Platform"
+
+[[bin]]
+name = "zcplatform"
+path = "src/main.rs"
+
+[dependencies]
+# Web framework
+axum = { version = "0.8", features = ["macros"] }
+tower = "0.5"
+tower-http = { version = "0.6", features = ["cors", "trace", "fs"] }
+
+# Async runtime
+tokio = { version = "1.42", features = ["rt-multi-thread", "macros", "signal", "time", "process", "fs", "sync"] }
+
+# CLI
+clap = { version = "4.5", features = ["derive"] }
+
+# Database (must match workspace root rusqlite version to avoid sqlite3 link conflict)
+rusqlite = { version = "0.37", features = ["bundled", "backup"] }
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+toml = "1.0"
+
+# Encryption
+chacha20poly1305 = "0.10"
+rand = "0.10"
+
+# Auth
+jsonwebtoken = "9"
+sha2 = "0.10"
+subtle = "2.6"
+hex = "0.4"
+
+# Template engine (config rendering)
+tera = "1.20"
+
+# Error handling
+anyhow = "1.0"
+thiserror = "2.0"
+
+# UUID
+uuid = { version = "1.11", features = ["v4"] }
+
+# Time
+chrono = { version = "0.4", features = ["serde"] }
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["fmt", "ansi", "env-filter"] }
+
+# HTTP client (for health checks, Caddy API)
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+
+# Email (SMTP)
+lettre = { version = "0.11", default-features = false, features = ["smtp-transport", "tokio1-rustls-tls", "builder", "hostname"] }

multi_tenants/deploy/caddy.env

@@ -0,0 +1,5 @@
+# Caddy environment variables
+# Place at /etc/caddy/caddy.env and restart Caddy
+
+# Required for wildcard TLS via Cloudflare DNS challenge
+CLOUDFLARE_API_TOKEN=your-cloudflare-api-token-here

multi_tenants/deploy/platform.toml.example

@@ -0,0 +1,59 @@
+# ZeroClaw Multi-Tenant Platform Configuration
+# Copy to /opt/zcplatform/platform.toml and customize.
+
+# Platform API server
+host = "127.0.0.1"
+port = 8080
+
+# Database (SQLite, WAL mode)
+database_path = "/opt/zcplatform/data/platform.db"
+
+# Encryption key file
+master_key_path = "/opt/zcplatform/data/master.key"
+
+# Tenant data directory
+data_dir = "/opt/zcplatform/data/tenants"
+
+# Docker
+docker_image = "zeroclaw-tenant:latest"
+docker_network = "zcplatform-internal"
+port_range = [10001, 10999]
+uid_range = [10001, 10999]
+
+# Domain (enables Caddy subdomain routing)
+# domain = "example.com"
+
+# Caddy admin API
+caddy_api_url = "http://localhost:2019"
+
+# JWT secret (auto-generated during bootstrap if omitted)
+# jwt_secret = "..."
+
+# Plan definitions
+[plans.free]
+max_messages_per_day = 100
+max_channels = 2
+max_members = 3
+memory_mb = 256
+cpu_limit = 0.5
+
+[plans.starter]
+max_messages_per_day = 1000
+max_channels = 5
+max_members = 10
+memory_mb = 384
+cpu_limit = 0.75
+
+[plans.pro]
+max_messages_per_day = 10000
+max_channels = 10
+max_members = 20
+memory_mb = 512
+cpu_limit = 1.0
+
+[plans.enterprise]
+max_messages_per_day = 100000
+max_channels = 50
+max_members = 100
+memory_mb = 1024
+cpu_limit = 2.0

multi_tenants/deploy/zcplatform.service

@@ -0,0 +1,32 @@
+[Unit]
+Description=ZeroClaw Multi-Tenant Platform
+Documentation=https://github.com/zeroclaw-labs/zeroclaw
+After=network.target docker.service
+Requires=docker.service
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/zcplatform
+ExecStart=/opt/zcplatform/zcplatform-bin serve --config /opt/zcplatform/platform.toml
+ExecReload=/bin/kill -HUP $MAINPID
+Restart=on-failure
+RestartSec=5
+
+# Security hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/opt/zcplatform/data
+ProtectHome=true
+PrivateTmp=true
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=zcplatform
+
+# Environment
+Environment=RUST_LOG=zcplatform=info
+
+[Install]
+WantedBy=multi-user.target

multi_tenants/docker/Dockerfile.egress

@@ -0,0 +1,12 @@
+FROM alpine:3.21
+
+RUN apk add --no-cache tinyproxy
+
+COPY tinyproxy.conf /etc/tinyproxy/tinyproxy.conf
+COPY egress-entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+USER nobody
+EXPOSE 8888
+
+ENTRYPOINT ["/entrypoint.sh"]

multi_tenants/docker/Dockerfile.tenant

@@ -0,0 +1,19 @@
+# Minimal tenant container based on ZeroClaw release image.
+# The ZeroClaw binary must be copied into the build context before building.
+
+FROM gcr.io/distroless/cc-debian13:nonroot
+
+COPY zeroclaw /usr/local/bin/zeroclaw
+
+ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
+ENV HOME=/zeroclaw-data
+ENV ZEROCLAW_ALLOW_PUBLIC_BIND=true
+
+WORKDIR /zeroclaw-data
+USER 65534:65534
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD ["/usr/local/bin/zeroclaw", "status"]
+
+ENTRYPOINT ["zeroclaw"]
+CMD ["gateway"]

multi_tenants/docker/egress-entrypoint.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+set -e
+
+CONFIG="/etc/tinyproxy/tinyproxy.conf"
+RUNTIME_CONFIG="/tmp/tinyproxy.conf"
+
+# Copy base config
+cp "$CONFIG" "$RUNTIME_CONFIG"
+
+# Add allowed CONNECT domains from env
+if [ -n "$ALLOWED_CONNECT" ]; then
+    echo "$ALLOWED_CONNECT" | tr ',' '\n' | while read -r line; do
+        port=$(echo "$line" | cut -d: -f2)
+        echo "ConnectPort $port" >> "$RUNTIME_CONFIG"
+    done
+fi
+
+exec tinyproxy -d -c "$RUNTIME_CONFIG"

multi_tenants/docker/tinyproxy.conf

@@ -0,0 +1,6 @@
+Port 8888
+Listen 0.0.0.0
+Timeout 30
+MaxClients 100
+Allow 172.30.0.0/16
+# ConnectPort lines added dynamically by entrypoint