johnson7788/MultiUserClaw

MultiUserClaw – Multi‑tenant AI SaaS platform built on Hermes Agent

What it is

• A complete web‑based SaaS framework that lets you run many isolated AI assistants (Agents) for different customers on the same server.
• Each user gets their own Docker container that runs a Hermes‑based AI agent runtime. The containers are created on‑demand, paused when idle and can be archived after weeks of inactivity.
• The platform provides a ready‑made front‑end, a FastAPI gateway, a PostgreSQL store, and a set of ready‑to‑use features (knowledge‑base, skill store, cron jobs, multi‑channel bots, API tokens, etc.).

Key components

Component	Role
Frontend (Vite + React)	SPA that users interact with – login, chat, skill store, admin pages.
Platform Gateway (FastAPI)	Auth (JWT), Docker‑container management, LLM proxy (injects API keys), quota tracking, API compatibility layer for the older OpenClaw API.
Hermes Agent container (Python)	Runs the actual AI agent. Exposes an HTTP + SSE API (port 18080) that handles sessions, tool calls, skills, file workspace, etc.
PostgreSQL	Stores user accounts, container metadata, usage logs, quotas.
Docker Compose	Orchestrates the services and spins up a separate container per user.

How a message flows

1. User types in the browser → Frontend sends a WebSocket request to /api/....
2. Gateway authenticates the JWT, finds/starts the user’s container, and proxies the WebSocket to the Hermes API inside that container.
3. Hermes processes the message, may call a tool or a skill, and when it needs a language model it calls the gateway’s /llm/v1/chat/completions endpoint.
4. The gateway checks the user’s token quota, selects the appropriate provider (OpenAI, Anthropic, DashScope, etc.) based on the model name, injects the provider’s API key (kept only in the gateway env), forwards the request, records token usage, and streams the response back to Hermes → Frontend.

Main features

• Multi‑tenant isolation – each user runs in its own Docker container (2 GB RAM, 4 CPU) with a private volume for files and chat history.
• Agent management – create, rename, set emoji/icon, view details, delete.
• Real‑time chat – WebSocket, markdown rendering, code highlighting, voice input, file/image upload.
• Cron jobs – schedule recurring or one‑off tasks, enable/disable, immediate run, optional notification.
• Knowledge base – per‑agent file store (text, PDF, JSON, code) with preview, download and delete.
• Skill store – install skills from skills.sh, enable/disable, plus user‑uploaded custom skills.
• Multi‑channel bots – built‑in adapters for Telegram, Discord, Email, WhatsApp Web, Signal, Slack, iMessage, etc.
• API access – generate tokens, call agents from CLI or other services, reuse sessions.
• Multiple model providers – supports dozens of LLMs (OpenAI, Anthropic, DashScope, DeepSeek, AiHubMix, Evolink, OpenRouter, etc.) with a simple model‑name selector.
• Dashboard – quick stats on agents, sessions, skills, and overall system health.
• Security – API keys never enter user containers; JWT → container‑token chain; resource limits; audit logs.

Running the platform

1. Install Docker & Docker‑Compose.
2. Create a .env file at the repo root and add at least one LLM provider key (e.g., OPENAI_API_KEY=sk‑…).
3. Build the base images: python prepare.py && bash build_base_image.sh.
4. Deploy with Docker Compose: python deploy_docker.py --rebuild hermes,gateway,frontend (or simply docker compose up -d).
5. Access the UI at http://localhost:3080, register, and start chatting – the gateway will automatically spin up a dedicated Hermes container for you.

Typical use‑cases

• SaaS companies that want to offer a custom AI assistant to each client without building the infra from scratch.
• Internal tools where each team needs its own isolated agent with private knowledge bases and scheduled jobs.
• Developers who need a plug‑and‑play platform to experiment with multi‑model LLMs, tool‑calling, and skill extensions.

Limitations / things to be aware of

• The platform relies on Docker; it needs a host with enough CPU/RAM to run a container per active user.
• All LLM calls are proxied through the gateway, so provider API‑key limits and latency affect every user.
• The default resource caps (2 GB RAM, 4 CPU) may need tuning for heavy workloads.
• While the README provides many deployment scripts, production‑grade hardening (TLS termination, secret management, monitoring) is left to the operator.

Where to find more

• Detailed docs are linked in the README (e.g., channel‑config wiki).
• Screenshots of the UI and logs are in the doc/ folder.
• The deploy_copy/ directory contains example pre‑configured agents (HR, researcher, programmer) that are copied into a new container on first start.

---

All information above is taken directly from the repository’s README; no external assumptions have been added.