Cratos - AI-Powered Personal Assistant

Cratos is a Rust-based AI assistant that understands natural language commands from Telegram/Slack, gathers information, executes tasks, and reports results.

One-Line Installation

macOS / Linux

curl -sSL https://raw.githubusercontent.com/first-fluke/cratos/main/scripts/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/first-fluke/cratos/main/scripts/install.ps1 | iex

The installer automatically:

• Downloads the appropriate binary for your platform
• Installs to your PATH
• Launches the setup wizard

Key Features

• Lightweight: Runs immediately with embedded SQLite (~/.cratos/cratos.db)
• Automatic Skill Generation: Learns usage patterns to automatically create workflow skills
• Multi-LLM Support: OpenAI, Anthropic, Gemini, DeepSeek, Groq, Fireworks, SiliconFlow, GLM, Qwen, Moonshot, Novita, OpenRouter, Ollama (13 providers, 6 free)
• Smart Routing: Automatic model selection by task type reduces costs by 70%
• Free Model Support: Free LLMs: Z.AI GLM-4.7-Flash (unlimited), Gemini Flash, Groq, Novita, SiliconFlow
• Replay Engine: All executions stored as events, timeline view and replay
• Tool System: 23 built-in tools (file ops, HTTP, Git/GitHub, shell exec, PTY bash, browser, web search, agent CLI, WoL, config, image generation, file transfer, native app automation) + MCP extensibility
• Channel Adapters: Telegram, Slack, Discord, Matrix, WhatsApp — with slash commands, DM policy, EventBus notifications
• Chrome Extension: Browser control via Chrome extension + WebSocket gateway protocol
• Graph RAG Memory: Cross-session conversation memory with entity graph + hybrid vector search
• TUI Chat: ratatui-based interactive terminal with markdown rendering, mouse scroll, input history, multi-provider quota display
• Voice Control: STT (Whisper API / local Whisper) + TTS (Edge TTS) + VAD (Silero), supports ko/en/ja/zh
• Web Search: Built-in DuckDuckGo search (no API key required)
• MCP Integration: Auto-discovery of MCP servers from .mcp.json, SSE/stdio support
• Proactive Scheduler: Cron, interval, one-time, file-watch, and system-event triggers
• Security: Auth middleware (HMAC/JWT/API Key), rate limiting, Docker sandbox, credential encryption, prompt injection defense
• Olympus OS: Mythology-based 3-layer agent organization (Pantheon/Decrees/Chronicles)
• ACP Bridge: IDE integration via stdin/stdout JSON-lines protocol
• Device Pairing: PIN-based mobile pairing for remote device management
• Remote Development: Issue → PR end-to-end automation (cratos develop)

System Requirements

¹ Minimum: With embeddings disabled (cargo build --no-default-features). Semantic search unavailable.

Note: No PostgreSQL or Docker required. Data is stored in ~/.cratos/cratos.db (SQLite).

Ollama Local LLM (Optional)

Note: No GPU required when using external LLM APIs (OpenAI, Anthropic, etc.)

Quick Start

Option 1: One-Line Install (Recommended)

# macOS / Linux
curl -sSL https://raw.githubusercontent.com/first-fluke/cratos/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/first-fluke/cratos/main/scripts/install.ps1 | iex

The setup wizard will guide you through:

1. Creating a Telegram bot
2. Choosing an AI provider (free options available)
3. Testing your configuration

Option 2: Manual Setup

# Clone the repository
git clone https://github.com/first-fluke/cratos.git
cd cratos

# Run the setup wizard
cargo run -- init

# With Korean language
cargo run -- init --lang ko

Option 3: Build from Source

# Create environment file
cp .env.example .env

# Edit .env file (add your API keys)
vim .env

# Build and run
cargo build --release
cargo run --release

# Health check
curl http://localhost:19527/health

Data is automatically stored in ~/.cratos/cratos.db.

Setup

Project Structure

cratos/
├── crates/
│   ├── cratos-core/      # Orchestration engine, security, credentials, shutdown
│   ├── cratos-channels/  # Channel adapters (Telegram, Slack, Discord, Matrix, WhatsApp)
│   ├── cratos-tools/     # Tool registry, sandbox, MCP client, browser relay
│   ├── cratos-llm/       # LLM providers, token counting, ONNX embeddings, quota tracking
│   ├── cratos-replay/    # Event logging and replay (SQLite)
│   ├── cratos-skills/    # Automatic skill generation system
│   ├── cratos-search/    # Vector search (usearch), semantic indexing
│   ├── cratos-memory/    # Graph RAG conversation memory (entity graph + hybrid search)
│   ├── cratos-crypto/    # Cryptographic utilities
│   ├── cratos-audio/     # Voice control (STT/TTS, optional)
│   └── cratos-canvas/    # Live Canvas (future)
├── config/
│   ├── default.toml      # Default configuration
│   ├── pantheon/         # Persona TOML files (14 personas: 5 core + 9 extended)
│   └── decrees/          # Laws, ranks, development rules
├── src/
│   ├── main.rs           # Application entry point
│   ├── cli/              # CLI commands (init, doctor, quota, tui, skill, data, acp, browser-ext, ...)
│   ├── api/              # REST API (config, tools, executions, scheduler, quota, sessions, browser)
│   ├── websocket/        # WebSocket handlers (chat, events, gateway)
│   └── server.rs         # Server initialization

~/.cratos/                # Data directory (auto-created)
├── cratos.db             # SQLite main DB (events, execution history)
├── skills.db             # SQLite skills DB (skills, patterns)
├── memory.db             # SQLite Graph RAG memory DB
├── vectors/              # HNSW vector index (usearch)
│   └── memory/           # Memory embedding vectors
└── chronicles/           # Achievement records per persona

Configuration

Environment Variables

Note: DATABASE_URL is no longer needed. Uses embedded SQLite.

Configuration Files

Default settings are in config/default.toml. Create config/local.toml to customize for your local environment.

LLM Providers

Paid Providers

Free/Low-Cost Providers

Model Routing

Automatic model selection based on task type:

Olympus OS (Agent Organization)

Cratos features a mythology-based 3-layer agent organization system:

Core Personas

Extended Personas

@mention Routing

Route tasks to specific personas using @mentions:

@athena Plan this sprint          # PM - Strategy
@sindri Implement the API         # DEV - Development
@heimdall Review security         # QA - Quality
@mimir Research this technology   # RESEARCHER - Analysis
@cratos Summarize the situation   # Orchestrator

Response format: [Persona LvN] Per Laws Article N...

CLI Commands

# Setup
cratos init                       # Interactive setup wizard (auto-detects language)
cratos init --lang ko             # Setup wizard in Korean

# System
cratos serve                      # Start the server
cratos doctor                     # Run diagnostics
cratos quota                      # Show provider quota/cost status
cratos quota --watch              # Live-refresh mode (every 2s)
cratos quota --json               # JSON output for scripting
cratos tui                        # Launch interactive TUI chat
cratos tui --persona sindri       # TUI with specific persona
cratos acp                        # Start ACP bridge (IDE integration)

# Voice
cratos voice                      # Start voice assistant (default: ko)
cratos voice --lang en            # Voice assistant in English

# Remote Development
cratos develop --repo user/repo   # Issue → PR automation
cratos develop --dry-run          # Preview without changes

# Device Pairing
cratos pair start                 # Start PIN-based pairing
cratos pair devices               # List paired devices
cratos pair unpair <device>       # Unpair a device

# Browser
cratos browser tabs               # List open browser tabs
cratos browser open <url>         # Open a URL
cratos browser screenshot         # Capture screenshot
cratos browser extension install  # Install Chrome extension

# Security
cratos security audit             # Run security audit

# Skills
cratos skill list                 # List all skills
cratos skill show <name>          # Show skill details
cratos skill enable <name>        # Enable a skill
cratos skill disable <name>       # Disable a skill
cratos skill export <name>        # Export a skill to file
cratos skill import <file>        # Import a skill from file
cratos skill bundle               # Bundle skills for sharing
cratos skill search <query>       # Search remote skill registry
cratos skill install <name>       # Install from registry
cratos skill publish <name>       # Publish to registry

# Data Management
cratos data stats                 # Show database statistics
cratos data clear sessions        # Clear session data
cratos data clear memory          # Clear Graph RAG memory
cratos data clear history         # Clear execution history
cratos data clear chronicles      # Clear achievement records
cratos data clear vectors         # Clear vector indices
cratos data clear skills          # Clear learned skills

# Pantheon (Personas)
cratos pantheon list              # List personas
cratos pantheon show sindri       # Show persona details
cratos pantheon summon sindri     # Summon (activate) a persona
cratos pantheon dismiss           # Dismiss active persona

# Pantheon Skill Management
cratos pantheon skill list <persona>       # List skills bound to persona
cratos pantheon skill show <persona> <skill>   # Show binding details
cratos pantheon skill claim <persona> <skill>  # Manually assign skill
cratos pantheon skill release <persona> <skill> # Release skill
cratos pantheon skill leaderboard <skill>  # Skill leaderboard
cratos pantheon skill summary <persona>    # Persona skill summary
cratos pantheon skill sync <persona>       # Sync proficiency to chronicle

# Decrees (Rules)
cratos decrees show laws          # Show laws
cratos decrees show ranks         # Show rank system
cratos decrees show warfare       # Show development rules
cratos decrees show alliance      # Show collaboration rules
cratos decrees show tribute       # Show reward/cost rules
cratos decrees show judgment      # Show evaluation framework
cratos decrees show culture       # Show culture/values
cratos decrees show operations    # Show operational procedures
cratos decrees validate           # Validate rule compliance

# Chronicles (Achievement Records)
cratos chronicle list             # List achievement records
cratos chronicle show sindri      # Show individual record
cratos chronicle log "message"    # Add log entry
cratos chronicle promote sindri   # Request promotion
cratos chronicle clean            # Clean up stale records

Security Features

Security-first by design — Built from the ground up with security as a core principle, not an afterthought.

• Memory-safe foundation: Written in Rust with #![forbid(unsafe_code)] — no buffer overflows, no use-after-free
• Zero plaintext secrets: All credentials encrypted via OS keychain (Keychain, Secret Service, Credential Manager)
• Default isolation: Sandbox enabled by default with network blocked, not opt-in
• Built-in threat detection: 20+ prompt injection patterns detected and blocked automatically
• Tool risk classification: Every tool has explicit risk levels with appropriate safeguards
• Input/output validation: All user inputs and LLM outputs are validated before execution

Docker Sandbox

Dangerous tools run in isolated Docker containers:

[security.sandbox]
default_network = "none"  # Block network
max_memory_mb = 512       # Memory limit
max_cpu_percent = 50      # CPU limit

Credential Encryption

API keys are securely stored in OS keychain:

• macOS: Keychain
• Linux: Secret Service (GNOME Keyring)
• Windows: Credential Manager

Prompt Injection Defense

Automatically detects and blocks malicious prompts:

• 20+ danger pattern detection
• Input/output validation
• Prevents sensitive information exposure

Supported Tools

Built-in Tools

MCP Extension Tools

Additional tools can be auto-registered from .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-playwright"]
    }
  }
}

MCP tools are discovered at startup and integrated into the tool registry with a 10-second connection timeout.

REST API & WebSocket

REST Endpoints (/api/v1/*)

WebSocket Endpoints

Security Middleware

All API endpoints are protected with configurable security layers:

• Authentication: HMAC signature, JWT token, or API key
• Rate Limiting: Per-IP and per-user request throttling
• Approval Nonce: One-time tokens for high-risk operations

Chrome Extension (Browser Control)

Control your Chrome browser remotely via a lightweight extension that connects through the WebSocket gateway:

Chrome Extension ←→ /ws/gateway ←→ Cratos Server ←→ BrowserRelay ←→ Tools

Features:

• Tab management (list, open, close, activate)
• Page navigation and content extraction
• DOM interaction (click, type, screenshot)
• Bidirectional JSON-RPC communication

The browser tool automatically detects whether a Chrome extension is connected and falls back to MCP-based browser automation if not.

Graph RAG Memory

Cross-session conversation memory powered by entity graph and hybrid vector search:

• Turn Decomposition: Breaks conversations into semantic units
• Entity Extraction: Rule-based named entity recognition
• Graph Construction: Entities linked by co-occurrence and relationships
• Hybrid Search: embedding_similarity * 0.5 + proximity * 0.3 + entity_overlap * 0.2

Data stored in ~/.cratos/memory.db (SQLite) and ~/.cratos/vectors/memory (HNSW index).

TUI Chat

Interactive terminal-based chat interface:

cratos tui                    # Launch TUI
cratos tui --persona athena   # Start with specific persona

Voice Control

Built-in voice assistant with Speech-to-Text, Text-to-Speech, and Voice Activity Detection:

cratos voice                  # Start voice assistant (Korean)
cratos voice --lang en        # English
cratos voice --lang ja        # Japanese
cratos voice --lang zh        # Chinese

Local Whisper STT: cargo build --features local-stt (downloads model on first run)

Device Pairing

PIN-based device pairing for secure remote management:

cratos pair start             # Generate pairing PIN
cratos pair devices           # List paired devices
cratos pair unpair <device>   # Remove a paired device

Paired devices can control Cratos via REST API or WebSocket with device-level authentication.

Proactive Scheduler

Schedule automated tasks:

Task actions: NaturalLanguage, ToolCall, Notification, Shell, Webhook.

Manage via REST API (/api/v1/scheduler/tasks) or natural language.

Testing

# Run all tests
cargo test --workspace

# Run integration tests only
cargo test --test integration_test

# Test specific crate
cargo test -p cratos-llm
cargo test -p cratos-tools
cargo test -p cratos-core

Documentation

• Setup Guide | 한국어
• User Guide | 한국어
• Developer Test Guide | 한국어
• User Test Guide | 한국어

Detailed Guides

License

MIT

Contributing

Issues and PRs welcome.

---

Languages: English | 한국어