CloudClaw Documentation

Introduction

CloudClaw is an enterprise-grade open source AI Agent platform built with Spring Boot 3.4 + Spring AI 1.1 + Vue 3.

Core design principles:

• Multi-tenant isolation — sessions, memories, configs isolated per user
• Stateless & scalable — all state in databases and caches, native horizontal scaling
• Security first — agents interact through MCP, database, or sandbox, never raw host access
• Pluggable architecture — memory engines, message queues, LLM providers, MCP servers are all replaceable

Current version: v1.0.4 | License: Apache 2.0

Installation

Requirements

Component	Requirement
Java	17+
Maven	3.9+ (build only)
PostgreSQL	16+ (cluster mode only)
Redis	7+ (cluster mode only)

Standalone Mode (Recommended for Getting Started)

Zero external dependencies. Uses SQLite + in-memory message queue. Ideal for development, evaluation, and personal use.

# 1. Clone the project
git clone https://github.com/cloudclaw-dev/cloudclaw.git
cd cloudclaw

# 2. Build
mvn clean package -DskipTests

# 3. Set secrets (required)
export JWT_SECRET="your-secret-key-at-least-32-bytes-long"
export CRYPTO_SECRET="your-crypto-key-at-least-32-bytes"

# 4. Start
java -jar cloudclaw-app/target/cloudclaw-app-1.0.3.jar

After starting, visit http://localhost:8080/. Default admin account: admin / admin123

Cluster Mode (Recommended for Production)

Uses PostgreSQL + Redis. Supports horizontal scaling.

# 1. Prepare database
createdb cloudclaw

# 2. Build and start
mvn clean package -DskipTests
export JWT_SECRET="your-secret"
export CRYPTO_SECRET="your-crypto"
java -jar cloudclaw-app/target/cloudclaw-app-1.0.3.jar \
  --spring.profiles.active=cluster

Configure database and Redis in application-cluster.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cloudclaw
    username: postgres
    password: your-password
  data:
    redis:
      host: localhost
      port: 6379

Quick Start

First-time usage flow after starting:

1. Login — Sign in with admin / admin123
2. Configure LLM — Go to "LLM Management" and add your API Key (supports DeepSeek, Qwen, GLM, Ollama, and any OpenAI-compatible API)
3. Create Agent — Go to "Agent Management", create a new Agent with system prompt and model
4. Start Chatting — Switch to the "Chat" page, select an Agent and start

Agent Management

Agent is the core entity in CloudClaw. Each Agent has independent configuration:

Field	Description
Name	Display name of the Agent
System Prompt	Defines the Agent's role and behavior
Model	LLM model to use (e.g. deepseek-chat, qwen-plus)
Temperature	Controls output randomness. 0 = deterministic, 1 = maximum randomness
Max Tokens	Maximum length of a single response
MCP Servers	Bound MCP tool servers
Skills	Bound Skill skills
Workflow	Multi-Agent orchestration mode (optional)

The Agent form is organized into 4 tabs: Basic / Model / Workflow / Tools

Chat

Chat Interface

• Session List — Left sidebar shows all sessions, supports search and time-based grouping (Today/Yesterday/Last 7 Days/Earlier)
• Pin Sessions — Important sessions can be pinned to top
• Streaming Output — SSE real-time streaming with typewriter effect
• Message Actions — Copy content, regenerate response, edit and resend messages
• Code Blocks — Syntax highlighting, line numbers, one-click copy, auto-collapse for 30+ lines
• Welcome Page — Suggested prompt cards for new conversations

Session Management

• Each session is bound to one Agent
• Supports session renaming
• SSE auto-reconnection on disconnect (up to 3 retries)

Multi-Agent Orchestration

CloudClaw provides 5 built-in orchestration modes for multi-agent collaboration:

Mode	Description	Use Case
Pipeline	Sequential execution, output feeds into next	Pipeline processing, multi-step tasks
Parallel	Multiple agents run simultaneously, results merged	Parallel analysis, multi-angle evaluation
Router	LLM intent classification routes to best sub-agent	Customer service routing, task dispatch
Supervisor	Planner/reviewer agent delegates tasks iteratively	Complex project management, quality control
Handoff	Conversation transfers between agents with context	Customer service transfer, multi-expert consultation

Each node supports independent configuration: model, system prompt, MCP servers, skills.

MCP Gateway

Built-in MCP (Model Context Protocol) gateway enables agents to call external tools through a standard protocol.

Features

• Connection pool management (default: 5 connections per server)
• Tool routing and permission control
• Idle connection auto-reclaim (default: 300 seconds)

Configure MCP Servers

Add servers in the admin "MCP Servers" page. Required fields:

• Server name
• Transport (SSE / Stdio)
• Connection URL or startup command

Memory Service

Provides persistent memory for agents, supporting cross-session context retention.

Supported Engines

Engine	Description	Use Case
jdbc	Database-backed memory with vector search	Recommended default, works out of the box
mem0	Integrates third-party Mem0 memory service	Advanced memory capabilities

Configuration: cloudclaw.memory.engine=jdbc

Skill System

Adopts the Claude Agent Skill standard with progressive loading:

• Metadata — Skill name, description, trigger conditions
• Instructions — Execution steps (SKILL.md)
• Files — Attached resources and tools

Auto-discovery via @Tool annotation.

Code Sandbox

Secure isolated code execution environment with multiple backends:

Backend	Description
LOCAL	Local process execution (default)
DOCKER	Docker container isolation (Testcontainers)
E2B	E2B cloud sandbox

Supported Languages

Python, JavaScript, Shell, Java

Execution Modes

• STATELESS — Stateless, each execution is independent (default)
• SESSION — Stateful, maintains context within a session

Security Limits

• Default timeout 30s, maximum 5 minutes
• Maximum 20 concurrent executions
• Network disabled by default in Docker mode

LLM Management

Multi-provider model management with a unified configuration entry.

Features

• Multi-provider credential management (API keys encrypted at rest)
• Model registration and routing
• Usage statistics and tracking
• Supports all OpenAI-compatible APIs

Supported Models

DeepSeek, Qwen, GLM, Ollama local models, and any OpenAI-compatible API. Configure API Key, then select the model in Agent settings.

Configuration Reference

All settings are in application.yml or application-cluster.yml. Environment variables override file values.

Property	Default	Description
server.port	8080	Server port
spring.profiles.active	standalone	Mode: standalone or cluster
cloudclaw.jwt.secret	Built-in default	JWT signing key (env: JWT_SECRET)
cloudclaw.jwt.access-token-ttl	2h	Access token TTL
cloudclaw.jwt.refresh-token-ttl	7d	Refresh token TTL
cloudclaw.crypto.secret	Built-in default	Encryption key (env: CRYPTO_SECRET)
cloudclaw.memory.engine	jdbc	Memory engine: jdbc or mem0
cloudclaw.mq.provider	inmemory	Message queue: inmemory or redis
cloudclaw.mcp.pool.max-connections-per-server	5	Max MCP connections per server
cloudclaw.cache.session-ttl	30m	Session cache TTL
cloudclaw.sandbox.default-backend	LOCAL	Sandbox backend
cloudclaw.sandbox.default-mode	STATELESS	Sandbox mode
cloudclaw.sandbox.default-timeout	30s	Default execution timeout
cloudclaw.sandbox.max-timeout	5m	Maximum execution timeout

Docker Deployment

Standalone Docker

docker compose -f docker-compose.standalone.yml up -d

Requires JWT_SECRET environment variable.

Cluster Docker (PostgreSQL + Redis)

# 1. Create .env file
cp .env.example .env
# Edit .env and fill in secrets

# 2. Start all services
docker compose up -d

Includes PostgreSQL (with pgvector), Redis, and CloudClaw containers.

Build Custom Image

# Full build (frontend + backend)
docker build -t cloudclaw .

# Or use pre-built JAR
docker build -f Dockerfile.simple -t cloudclaw .

Cluster Mode

Architecture Comparison

	Standalone	Cluster
Database	SQLite	PostgreSQL 16+
Cache	Caffeine (local)	Redis 7+
Message Queue	In-memory	Redis Streams
Scaling	Not supported	Supported
Use Case	Dev, evaluation, personal	Production, teams, enterprise

Database Migration

CloudClaw uses Flyway for automatic database migration:

• Standalone: classpath:db/sqlite/
• Cluster: classpath:db/migration/

All tables are created automatically on first start. Subsequent upgrades migrate automatically.

Users & Permissions

Roles

Role	Permission
ADMIN	Full admin access: user management, agent management, system monitoring, logs
USER	Chat interface, session management, personal memory

Authentication

• JWT (HS384) dual-token mechanism: Access Token + Refresh Token
• Login rate limiting (brute-force protection)

Admin Features

• Dashboard — System overview, recent conversations, Agent usage charts
• Agent Management — Create, edit, delete Agents
• LLM Management — Configure models and API Keys
• MCP Servers — Manage external tool connections
• Skill Management — Upload and manage skills
• Sandbox Management — View sandbox configuration
• User Management — Create, edit users, assign roles
• System Monitor — Real-time logs, Prompt logs