---

What is ClotoCore?

ClotoCore is a platform for building advanced AI agents — not chatbots, not assistants, but AI partners with personality, capabilities, and memory.

Inspired by projects like Neuro-Sama, ClotoCore lets anyone construct sophisticated AI systems through a plugin architecture and GUI dashboard, without writing a single line of code.

AI Container = Plugin Set + Personality Definition + Capability Set

Example: "VTuber AI" Container          Example: "Research Assistant" Container
├── reasoning: DeepSeek                  ├── reasoning: Claude / GPT-4o
├── vision: Screen capture plugin        ├── tools: File search, Web search
├── personality: Character definition    ├── personality: Academic, precise
├── voice: TTS/STT plugin               └── memory: Long-term memory plugin
└── avatar: Live2D/VRM plugin

Why ClotoCore?

	ClotoCore	Chat-based AI frameworks
Language	Rust — memory safe, fast, low resource	TypeScript / Python
Security	Sandboxed plugins, permission isolation, host whitelisting, DNS rebinding protection	Broad local permissions
Interface	GUI dashboard + Tauri desktop app	Chat / CLI only
Design	Plugin-composed AI containers	Monolithic agents
Extension	MCP server plugins (any language)	Single language

Architecture

graph TB
    Client[Dashboard / HTTP Client] --> Router[Axum Router]
    Router --> Auth[API Key Auth + Rate Limit]
    Auth --> Handlers[Handlers]

    Handlers --> DB[(SQLite)]
    Handlers --> EventBus[Event Bus]

    EventBus --> Processor[Event Processor]
    Processor --> Manager[Plugin Manager]

    Manager --> MCP1[MCP Server]
    Manager --> MCPN[MCP Server N]

    MCP1 --> Cascade[Cascade Events]
    Cascade --> EventBus

    MCP1 -.->|JSON-RPC stdio| Process1[Server Process]

    SSE[SSE Stream] --> Client

    style DB fill:#f0e6ff,stroke:#333,color:#333
    style Processor fill:#e6f0ff,stroke:#333,color:#333
    style Manager fill:#e6ffe6,stroke:#333,color:#333
    style Process1 fill:#fff4e6,stroke:#333,color:#333

Key design principles:

• Core Minimalism — The kernel is a stage, not an actor. All intelligence lives in plugins.
• Event-First — Plugins communicate through an async event bus, never directly.
• Capability Injection — Plugins cannot instantiate network clients. The kernel injects pre-authorized, sandboxed capabilities.
• Human-in-the-Loop — Sensitive operations require explicit admin approval at runtime.

Quick Start

git clone https://github.com/Cloto-dev/ClotoCore.git
cd ClotoCore
# build dashboard first
npm --prefix dashboard ci && npm --prefix dashboard run build
cargo build --release
cargo run --package cloto_core

The dashboard opens at http://localhost:8081.

For the desktop app (Tauri), use cd dashboard && npx tauri dev instead.

Installer (Experimental)

Pre-built installers are available on GitHub Releases. The installer includes a setup wizard that downloads MCP servers and configures Python on first launch.

Note: The installer has been tested on the developer's environment. Due to differences in Python versions, PATH configuration, and system permissions, you may encounter issues. If the installer fails, building from source (see Quick Start above) is recommended. Please report any issues at GitHub Issues.

Requirements: Python 3.10+ must be installed and available in PATH.

Uninstalling: The uninstaller removes the application but preserves user data (database, MCP servers, attachments). To fully remove all data, delete the data/ folder in the installation directory after uninstalling.

MCP Servers

All plugin functionality is delivered via MCP (Model Context Protocol) servers:

Server	Type	Description
mind.deepseek	Reasoning	Advanced reasoning via DeepSeek API
mind.cerebras	Reasoning	Ultra-high-speed reasoning via Cerebras API
mind.claude	Reasoning	Anthropic Claude API (native Messages API)
mind.ollama	Reasoning	Local model inference via Ollama
memory.cpersona	Memory	CPersona — persistent memory with RRF hybrid search (vector + FTS5 + keyword), confidence scoring, episodic/profile memory, 16 tools (MIT)
tool.terminal	Tool	Sandboxed shell command execution
tool.agent_utils	Tool	Deterministic utilities (time, math, UUID, hash, etc.)
tool.cron	Tool	Stateless CRON job management via kernel REST API
tool.embedding	Tool	Vector embedding generation (ONNX: Jina-v5-nano / MiniLM)
tool.websearch	Tool	Web search via Tavily or SearXNG
tool.research	Tool	Multi-engine research synthesis pipeline
tool.imagegen	Tool	Image generation via Stable Diffusion API
vision.gaze_webcam	Vision	Eye gaze tracking via MediaPipe
vision.capture	Vision	Screen/image analysis via Ollama (hybrid OCR)
voice.stt	Voice	Speech-to-text via Whisper
output.avatar	Output	VRM expression, idle behavior, and VOICEVOX TTS (Rust)
io.discord	I/O	Bidirectional Discord communication via MGP events (Rust)

MCP servers live in the cloto-mcp-servers repository and are configured via mcp.toml. See MCP Plugin Architecture for details.

Build your own server: Quickstart Guide — create a working MCP/MGP server in 5 minutes.

Project Structure

crates/core/        Kernel — event bus, MCP manager, HTTP API, rate limiter
crates/shared/      Shared types — trait definitions, LLM utilities
dashboard/          React/TypeScript web UI (Tauri desktop app)
scripts/            Build tools, verification scripts
qa/                 Issue registry and quality assurance data
docs/               Architecture, vision, specs, design documents

Configuration

Copy .env.example to .env to customize. All settings have sensible defaults.

Variable	Default	Description
PORT	8081	HTTP server port
CLOTO_API_KEY	(none)	Admin API key (required in release builds)
DEEPSEEK_API_KEY	(none)	DeepSeek API key
CEREBRAS_API_KEY	(none)	Cerebras API key
EMBEDDING_API_KEY	(none)	Embedding API key (OpenAI-compatible)
BIND_ADDRESS	127.0.0.1	Server bind address
ALLOWED_HOSTS	(none)	Network whitelist for plugin HTTP access
MAX_EVENT_DEPTH	10	Maximum event cascading depth
RUST_LOG	info	Log level filter

All configuration variables

Variable	Default	Description
PORT	8081	HTTP server port
DATABASE_URL	sqlite:{exe_dir}/data/cloto_memories.db	SQLite database path ({exe_dir} = directory of the executable)
CLOTO_API_KEY	(none)	Admin API key (required in release builds)
DEEPSEEK_API_KEY	(none)	DeepSeek API key
CEREBRAS_API_KEY	(none)	Cerebras API key
CONSENSUS_ENGINES	mind.deepseek,mind.cerebras	Engine IDs for consensus mode
DEFAULT_AGENT_ID	agent.cloto_default	Default agent for /api/chat
EMBEDDING_API_KEY	(none)	Embedding API key (OpenAI-compatible)
CLOTO_SKIP_ICON_EMBED	(none)	Set to 1 to skip icon embedding during dev builds
RUST_LOG	info	Log level filter
MAX_EVENT_DEPTH	10	Maximum event cascading depth
PLUGIN_EVENT_TIMEOUT_SECS	120	Plugin event handler timeout (1-300)
CORS_ORIGINS	localhost:5173	Allowed CORS origins (comma-separated)
ALLOWED_HOSTS	(none)	Network whitelist for plugin access
BIND_ADDRESS	127.0.0.1	Server bind address (0.0.0.0 for network access)
MEMORY_CONTEXT_LIMIT	10	Maximum memory entries returned per recall
EVENT_HISTORY_SIZE	1000	Maximum events kept in memory
EVENT_RETENTION_HOURS	24	Hours to retain events before cleanup (1-720)
CLOTO_MAX_AGENTIC_ITERATIONS	16	Maximum tool-use loop iterations (1-64)
CLOTO_MCP_CONFIG	(none)	Path to mcp.toml configuration file
CLOTO_TOOL_TIMEOUT_SECS	30	Tool execution timeout in seconds (1-300)
HEARTBEAT_INTERVAL_SECS	30	Agent heartbeat ping interval
CLOTO_SDK_SECRET	(none)	MCP SDK authentication secret
CLOTO_YOLO	false	Skip permission confirmations (dev/testing)
CLOTO_YOLO_EXCEPTIONS	filesystem.write,network.outbound	Permissions requiring approval even in YOLO mode
CLOTO_CRON_ENABLED	true	Enable cron job scheduler
CLOTO_CRON_INTERVAL	60	Cron check interval in seconds
CLOTO_LLM_PROXY_PORT	8082	LLM API proxy port
CONSENSUS_SYNTHESIZER	(none)	Consensus synthesis engine ID
CONSENSUS_MIN_PROPOSALS	2	Minimum proposals before synthesis
CONSENSUS_SESSION_TIMEOUT_SECS	60	Consensus session timeout
CLOTO_EVENT_CONCURRENCY	50	Event processing concurrency limit (1-500)
CLOTO_MAX_EVENT_HISTORY	10000	Maximum event history buffer (100-1000000)
CLOTO_DB_TIMEOUT_SECS	10	Database operation timeout (1-120)
CLOTO_MEMORY_TIMEOUT_SECS	5	Memory retrieval timeout (1-60)
CLOTO_HEARTBEAT_THRESHOLD_MS	90000	Agent heartbeat threshold (10000-600000)
CLOTO_MCP_REQUEST_TIMEOUT_SECS	120	MCP request timeout (10-600)
CLOTO_LLM_PROXY_TIMEOUT_SECS	180	LLM proxy HTTP timeout (30-600)
CLOTO_RATE_LIMIT_PER_SEC	10	Rate limit requests/sec (1-1000)
CLOTO_RATE_LIMIT_BURST	50	Rate limit burst size (1-10000)
CLOTO_HAL_RATE_LIMIT_PER_SEC	10	HAL action rate limit per requester (1-1000)
CLOTO_HAL_RATE_LIMIT_BURST	20	HAL action burst size per requester (1-10000)
CLOTO_MAX_CHAT_QUERY_LIMIT	200	Max chat messages per query (10-10000)
CLOTO_ATTACHMENT_INLINE_THRESHOLD	65536	Attachment inline threshold in bytes (0-10485760)
CLOTO_UPDATE_REPO	Cloto-dev/ClotoCore	GitHub repo for update checks
CLOTO_MAX_CRON_GENERATION	(none)	Maximum cron recursion depth
CLOTO_CRON_DEFAULT_MAX_ITERATIONS	8	Default max iterations for cron jobs (1-64)
TAVILY_API_KEY	(none)	Tavily search API key
OLLAMA_MODEL	(none)	Ollama model name
OLLAMA_ENABLE_THINKING	(none)	Enable Ollama thinking mode

API

Public endpoints

Method	Path	Description
GET	/api/system/version	Current version info
GET	/api/system/health	Lightweight health check
GET	/api/events	SSE event stream
GET	/api/history	Event history
GET	/api/metrics	System metrics
GET	/api/memories	Memory entries
DELETE	/api/memories/:id	Delete memory entry
GET	/api/episodes	Episode archive entries
DELETE	/api/episodes/:id	Delete episode entry
GET	/api/plugins	Plugin list with manifests
GET	/api/plugins/:id/config	Plugin configuration
GET	/api/agents	Agent configurations
GET	/api/permissions/pending	Pending permission requests
GET	/api/mcp/access/by-agent/:agent_id	Agent MCP tool access

Admin endpoints (requires X-API-Key header)

Method	Path	Description
POST	/api/system/shutdown	Graceful shutdown
POST	/api/system/invalidate-key	Revoke API key
POST	/api/plugins/apply	Bulk enable/disable plugins
POST	/api/plugins/:id/config	Update plugin config
GET	/api/plugins/:id/permissions	Query plugin permissions
POST	/api/plugins/:id/permissions/grant	Grant permission to plugin
DELETE	/api/plugins/:id/permissions	Revoke plugin permission
POST	/api/agents	Create agent
POST	/api/agents/:id	Update agent
DELETE	/api/agents/:id	Delete agent
POST	/api/agents/:id/power	Toggle agent power state
GET/POST/DELETE	/api/agents/:id/avatar	Agent avatar management
POST	/api/commands/:id/approve|trust|deny	Command approval decisions
POST	/api/events/publish	Publish event to bus
POST	/api/permissions/:id/approve	Approve a request
POST	/api/permissions/:id/deny	Deny a request
POST	/api/chat	Send message to agent
GET/POST/DELETE	/api/chat/:agent_id/messages	Chat message persistence
GET	/api/chat/attachments/:attachment_id	Retrieve chat attachment
GET/POST	/api/cron/jobs	List/create cron jobs
DELETE	/api/cron/jobs/:id	Delete cron job
POST	/api/cron/jobs/:id/toggle	Enable/disable cron job
POST	/api/cron/jobs/:id/run	Manually trigger cron job
GET	/api/llm/providers	List LLM providers
POST	/api/llm/providers/:id/key	Set LLM provider API key
DELETE	/api/llm/providers/:id/key	Remove LLM provider API key
GET/POST	/api/mcp/servers	List/create MCP servers
DELETE	/api/mcp/servers/:name	Delete MCP server
GET/PUT	/api/mcp/servers/:name/settings	Server settings
GET/PUT	/api/mcp/servers/:name/access	Access control
POST	/api/mcp/servers/:name/start|stop|restart	Server lifecycle
POST	/api/mcp/call	Call MCP tool directly
POST	/api/chat/:agent_id/messages/:message_id/retry	Retry agent response
GET/PUT	/api/settings/yolo	YOLO mode (skip permission prompts)
GET/PUT	/api/settings/max-cron-generation	Max cron recursion depth

Testing

234 Rust tests. MCP server tests (117 Python) are in cloto-mcp-servers.

cargo test                              # all Rust tests
cargo test --package cloto_core          # kernel only
cargo test --test '*'                   # integration tests only

Security

• API key authentication with per-IP rate limiting (10 req/s, burst 20)
• Append-only audit log in SQLite for all permission decisions
• Minimal default permissions — elevated permissions require human approval
• Network host whitelisting with DNS rebinding protection
• MCP access control with 3-level RBAC (capability → server → tool)
• Kernel tool RBAC — mgp.*/gui.* tools checked via per-agent access control
• Merkle chain audit log — tamper-detectable hash chain on all audit entries
• Destructive tool gate — tools with destructiveHint require HITL approval

See Architecture for the full security model.

Documentation

• MCP/MGP Server Quickstart — Build your first server in 5 minutes
• Architecture — Design principles, event flow, security model
• Project Vision — Strategic direction and roadmap
• Development — Coding standards, guardrails, PR process
• MGP Spec — Multi-Agent Gateway Protocol specification
• MGP Guide — MGP usage guide
• MGP Security — MGP security model
• MGP Isolation — MGP isolation design
• MGP Communication — MGP communication protocol
• MGP Discovery — MGP service discovery
• MCP Architecture — MCP server communication protocol
• CPersona Memory — Memory system design
• Database Schema — SQLite schema reference
• Changelog — Development history

License

Business Source License 1.1 — converts to MIT on 2028-02-14.

You can freely use ClotoCore for plugin development, internal tools, consulting, education, and small-scale commercial projects. Large-scale commercial deployment (>$100k revenue, >1,000 users, >50 employees, or SaaS) requires prior approval. See LICENSE for the full terms.

Community

• GitHub Issues
• GitHub Discussions
• X (Twitter)

Credits

• VOICEVOX — Text-to-speech engine used for avatar voice synthesis. Default speaker: VOICEVOX:ナースロボ＿タイプＴ
  • VOICEVOX — Terms of Use
  • Individual character terms may apply depending on the selected speaker.

Note

Built by a solo developer from Japan. Most of the code and documentation in this project was written with the assistance of AI. If you find any issues, please open an issue.