Kairo — Autonomous ML Research OS

Kairo is a premium, local-first No-Code ML Studio and Autonomous ML Research OS. It manages the complete machine learning lifecycle on behalf of the user—from a natural-language goal input to generating code, installing hardware-optimized dependencies, running training loops, evaluating results, and outputting reports.

---

🏗️ System Architecture

Kairo utilizes a decoupled, dual-process supervisor-agent architecture to combine a high-performance native desktop GUI with flexible, data-science friendly Python execution.

graph TD
    UI[React + TS Frontend] <-->|Tauri IPC Commands / Events| Rust[Tauri Rust Supervisor]
    Rust <-->|JSON-lines over stdin/stdout| Daemon[Python Agent Daemon]
    Daemon -->|Manages| Env[Project-Specific venv]
    Daemon -->|Routes LLM calls| GW[LLMGateway]
    Daemon -->|Invokes Tools| Reg[ToolRegistry]

Loading

Key Subsystems

1. Tauri Rust Supervisor (src-tauri):

   • Manages lifecycle processes and environment creation.
   • Spawns the python agent daemon, reads stdout events line-by-line, and propagates them as async IPC events to the UI.
   • Manages project CRUD operations, secure API keyring storage, and system hardware profile detection.

2. Python Agent Daemon (agent/):

   • Spawns as a single persistent daemon (kairo_agent.py).
   • Communicates with the Rust supervisor using streaming JSON-line Events (e.g. thinking, artifact, action_gate, preference_question).

3. React TypeScript Frontend (src/):

   • Displays the Claude-style streaming chat interface, interactive Action Gates (for Human-in-the-Loop approvals), and dynamic training metric charts.
   • Leverages Zustand for project-level state management and Monaco Editor for real-time code viewing.

---

🛠️ Key Core Modules

• ProjectStore: The sole module responsible for workspace database files, project metadata serialization, and folder structure.
• EnvManager: Detects system hardware capabilities (CUDA / ROCm / Apple Silicon / CPU) and manages project-specific virtual environments (venv) and dependency installation.
• AgentRunner: The core state machine driving the agent lifecycle (Intake → Preference Grill → Code Gen → Install Gate → Execution Gate).
• ToolRegistry: Unified interface mapping built-in utilities, MCP servers, and skill packages into a single execution registry.
• LLMGateway: Abstract LLM provider router built on LiteLLM. It supports 11+ providers (Ollama, Claude, GPT, Gemini, Groq, etc.) while automatically resolving system provider prefixes.

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher) and npm
• Rust compiler & Cargo (v1.75 or higher)
• Python (v3.11 or newer)
• Ollama (Optional, for running offline models locally)

Quick Start (Development)

1. Clone the repository and navigate into the workspace.
2. Install frontend Node dependencies:

   npm install

3. Start the Tauri development environment (this automatically builds the Rust backend and launches the React Vite server):

   npm run tauri dev

Resetting & Re-running Setup

Kairo runs an onboarding setup wizard on its first launch to validate system Python and bootstrap its environment. If you want to clear your local state, database, environments, and logs to check the onboarding flow from scratch:

# Stop the running application, then run:
rm -rf ~/.local/share/com.kairo.app

---

🤖 LLM Provider & Ollama Setup

Kairo uses the LLMGateway powered by LiteLLM to support a wide range of LLMs.

Ollama Configuration

When utilizing a local Ollama instance:

1. Ensure Ollama is running (ollama serve).
2. Input your model name (e.g., qwen3:8b or llama3.1).
3. Set the Base URL to your Ollama endpoint (default: http://localhost:11434).
4. Kairo automatically formats and prepends the required provider prefix (ollama/) to the model string before dispatching it to LiteLLM.

---

🧪 Development & Verification

Before committing, ensure both frontend and backend tests pass:

# Check TypeScript compilation
npx tsc --noEmit

# Run Rust backend test suite
cargo test --manifest-path src-tauri/Cargo.toml

---

📂 Project Structure

├── agent/                  # Python Agent Daemon logic
│   ├── kairo_agent.py      # Entry point / operation dispatcher
│   ├── agent_runner.py     # Stage / phase manager state machine
│   ├── llm_gateway.py      # LiteLLM routing & model prefixing
│   ├── env_manager.py      # Hardware profile detection & venv management
│   ├── tool_registry.py    # Built-in, MCP, and Skill tool mapper
│   └── requirements.txt    # Python dependencies
├── docs/                   # Product & technical documentation
│   ├── CONTEXT.md          # Domain model & glossary (single source of truth)
│   └── walkthrough.md      # Gap analysis & status walkthroughs
├── src-tauri/              # Rust supervisor & native Tauri commands
│   ├── src/lib.rs          # IPC command orchestrator
│   └── Cargo.toml          # Rust dependencies
└── src/                    # React UI frontend
    ├── src/store/          # Zustand store (projectStore.ts)
    ├── src/pages/          # Main application page controllers
    └── src/styles/         # Modular CSS stylesheets