Krill

A tiny crustacean for a minimal OpenClaw clone — a local-first personal AI assistant with a web UI.

Web UI       <──HTTP RPC──>  FastAPI Gateway  ──>  Agent Loop  ──>  LLM API
(React)                                │          (krill/loop.py)
                            ┌──────────┼──────────┐
                       Session Mgr  Spaces   Harness
                                    Service  (approval, compaction, usage)

What it does

Krill is a personal AI assistant that runs entirely on your machine. You talk to it through a web UI; it talks to any OpenAI-compatible LLM backend (Anthropic, OpenAI, Ollama, etc.).

Core capabilities:

• Tools & Code Execution — 11 default tools including sandboxed Python code execution, hashline-based file editing, and identity management. LLM can generate multi-step Python code that calls capability objects (web, fs, shell) instead of round-tripping to the LLM for every operation (inspired by Cloudflare's "code mode").

• Skills & Agents — Claude Code-compatible SKILL.md prompt expansions and ephemeral sub-agents. Drop any Claude Code skill into ~/.krill/skills/ and it just works:

  • research agent — multi-step web research with source tracking (spawned automatically)
  • /summarize-day — structured summary of today's activity
  • /morning-briefing — priorities, due reminders, weather

• Memory — space-native persistent memory with trust-scored facts:

  • Facts extracted from conversations via LLM with a 10-turn context window (auto-resolves pronouns and coreferences)
  • Two-gate dedup: cosine similarity > 0.85 = reinforce existing fact; in [0.4, 0.85) = run LLM conflict check
  • Trust scoring: composite score = confidence × recency-decay × reinforcement-boost; context injection ranked by trust
  • High-trust old facts survive conflict with low-confidence new facts
  • Stored as immutable atoms in SurrealDB with embeddings and full audit trail — no separate vector DB
  • Auto-rewriting category summaries (identity, preferences, personal, work) injected into every context
  • Episodic memory synthesis: multi-turn sessions synthesized into narrative episodes (### Relevant Experiences)
  • Knowledge graph: entities and relations extracted from facts, sorted by trust in context injection
  • Maintenance CLI: krill memory stats (incl. trust distribution), krill memory maintain, krill memory rebuild

• Security-focused architecture — 3-layer defense-in-depth:

  • Application-level safety (tool gating, approval gates)
  • OS-level sandboxing (planned)
  • Container hardening (non-root user, read-only source, limited writable paths)

• Context compaction — for long conversations:

  • Tracks token usage, triggers compaction before hitting the context window
  • Automatic mid-turn trimming of large tool results
  • LLM-based summarization of old messages

• Sessions — persistent, switchable conversations stored as JSONL

• Image upload — attach images (JPEG, PNG, WebP, GIF) to any message in the Web UI. Images are forwarded to vision-capable LLMs (OpenAI, Anthropic); non-vision providers receive a text note instead.

• Extensible prompts — all system prompts (SOUL.md, SUMMARIZE.md, etc.) auto-copy to ~/.krill/prompts/ on first run. Edit them to customize behavior.

• Local-first — runs entirely on your machine, not as a hosted service. All data stored in ~/.krill/ (config, memory, sessions) and ~/krill/ (agent workspace). Works offline except for LLM API calls.

• Multiple clients — two-process architecture (gateway daemon + client) with simple HTTP long-poll RPC protocol. Includes a React web UI with agent dashboard. Easy to add Telegram, Discord, or custom clients.

• Multi-agent coordination via Spaces — SurrealDB-backed architecture where all agent state (messages, memory, tool results) lives as immutable, versioned atoms:

  • Space conventions (CHAT, CHANNEL, PERSONAL_MEMORY, SCRATCHPAD) trigger auto-injection and routing
  • Wake-signal coordination: gateway writes an atom → space subscription fires → AgentProcess drains coalesced notifications and runs a turn — no polling
  • Semantic search at the database level (MTREE vector index on 384-dim embeddings)
  • Ephemeral sub-agents (research, code, setup) configured via AGENT.md with per-agent tool sets and token budgets; Agent dashboard shows real-time status

• Named identities — multiple credentials per service with metadata (owner, trust level, permissions). Convention-based lookup: [identities.X] in secrets.toml. Agent-owned identities for autonomous credential management. Supports api_key, bearer, token, basic, and cookie auth schemes. Pass identity="name" to web_fetch or browser_open to authenticate requests using stored credentials:

  # ~/.krill/secrets.toml
  [identities.my-service]
  type = "cookie"
  label = "My Service session"
  cookies = '[{"name":"session","value":"abc","domain":".example.com"}]'
  auth_scheme = "bearer"   # optional override (bearer, token, x-api-key, basic)

• Service integrations — Gmail and GitHub tools with identity-aware access control. LangChain tool adapter (tool_from_langchain) wraps any LangChain BaseTool with automatic credential injection and output sanitization. Browser automation for ephemeral agents. See Optional dependencies for external requirements.

How it compares to OpenClaw

Krill started as a minimal clone of OpenClaw but diverged with different design priorities:

Security-focused architecture:

• 3-layer defense-in-depth: Application-level safety (tool gating, approval gates), OS-level sandboxing (planned), and container hardening
• Granular per-operation approvals: Per-command approval for shell (with allowlist/denylist), per-file approval for reads/writes (with sensitive path detection), per-URL approval for web fetch, separate gates for daily vs. long-term memory writes
• Code sandbox: LLM-generated Python code executes in AST-walking sandbox (smolagents) with blocked imports (os, subprocess, socket), blocked functions (eval, exec, open), and capability-based access that routes through the same approval gates
• Protected system prompts: Agent cannot modify its own prompts (SOUL.md, MEMORY.md) without explicit user approval, preventing persistent prompt injection attacks where attackers trick the agent into writing malicious instructions that survive restarts
• Default-deny approach: Only explicitly safe operations auto-execute; everything else requires user approval
• In contrast, OpenClaw has drawn security scrutiny for "broad permissions," being "primarily suited for advanced users who understand the security implications," and allowing agents to modify SOUL.md without user confirmation

Token efficiency:

• Code mode: Cloudflare-style code generation reduces token usage by 32-81% for multi-step operations by executing logic in a single request instead of round-tripping for each tool call
• No MCP overhead: Direct tool registration in the custom agent loop avoids MCP's token bloat from loading all tool definitions upfront and intermediate tool results consuming excessive tokens

Minimalist Python stack:

• Pure Python: Custom agent loop (krill/loop.py — multi-provider, no framework overhead), FastAPI vs. OpenClaw's Node.js gateway
• Minimal HTTP RPC protocol: Simple gateway-client communication for implementing new clients

OpenClaw offers broader chat platform integrations (Discord, Slack, iMessage, WhatsApp), 100+ pre-configured skills, and a larger ecosystem, trading breadth for Krill's focus on simplicity and security rigor.

Quick start

# Install
uv sync

# Configure provider (interactive wizard - recommended)
uv run krill setup

# The wizard creates ~/.krill/secrets.toml with your credentials
# For backward compatibility, .env files are still supported

# Terminal 1: Start the gateway
uv run krill serve

# Terminal 2: Start the web UI
cd krill_clients/web/frontend
npm install  # first time only
npm run dev

# Open http://localhost:5173

Setup wizard features:

• Interactive provider selection (Anthropic, OpenAI, OpenRouter, local Ollama, etc.)
• API key creation instructions with direct links
• API key validation before saving
• Model selection from provider's available models
• Per-agent model assignment (main, summarize, research, code)
• Multi-provider configuration (e.g., OpenRouter for main + local Ollama for research)

The browser connects directly to the gateway via HTTP RPC. See krill_clients/web/README.md for full web UI documentation.

Optional dependencies

Service integrations require external tools installed separately. None are needed for core Krill functionality.

Telegram bot client:

uv sync --extra telegram

1. Create a bot via @BotFather on Telegram (/newbot) and copy the token
2. Add the token to ~/.krill/secrets.toml:

   [telegram]
   bot_token = "123456:ABC-DEF..."

3. Start the gateway and bot:

   uv run krill serve       # Terminal 1
   uv run krill telegram    # Terminal 2

4. Open Telegram, find your bot, and send /start

Beeper Desktop tools (chat across WhatsApp, Telegram, Signal, etc.):

uv sync --extra beeper

Requires Beeper Desktop v4.1.169+ running (macOS, Windows, Linux). Configure an identity in ~/.krill/secrets.toml:

[identities.beeper]
provider = "beeper"
label = "Beeper Desktop"
value = ""  # access token if required, otherwise leave empty

LangChain tools (wikipedia, arxiv, reddit_search):

uv sync --extra langchain

For reddit_search, add a Reddit identity to ~/.krill/secrets.toml:

[identities.reddit]
type = "oauth2"
label = "Reddit API"
value = '{"client_id": "...", "client_secret": "...", "user_agent": "MyBot/1.0 (by u/yourusername)"}'

Get Reddit API credentials at reddit.com/prefs/apps. wikipedia and arxiv work without any credentials.

External CLIs (install separately):

Integration	Dependency	Install
GitHub tools	gh CLI	cli.github.com
Browser automation	agent-browser CLI	github.com/nicepkg/agent-browser
Gmail + Calendar tools	gws CLI	github.com/googleworkspace/cli

Gmail and Calendar setup (optional — only needed for Gmail/Calendar tools):

# Install gws CLI (see link above for platform-specific instructions)
# Then authenticate once:
gws auth login

The gws CLI stores OAuth tokens in ~/.config/gws/. Krill's subprocess environment passes HOME so the tokens remain accessible. No Google credentials need to be added to ~/.krill/secrets.toml.

Configuration

Settings live in ~/.krill/config.toml, secrets in ~/.krill/secrets.toml (or .env for backward compatibility).

[providers.anthropic]
base_url = "https://api.anthropic.com/v1/"

[agents.main]
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
context_window = 200000

[gateway]
host = "127.0.0.1"
port = 8741

[safety]
mode = "approve"   # "approve", "allowlist", or "docker"

[sessions]
storage = "jsonl"  # "jsonl" (default), "dual", or "surrealdb"

Environment variables use KRILL_ prefix with __ for nesting: KRILL_LLM__BASE_URL, KRILL_LLM__MODEL, etc.

Docker

docker build -t krill .
docker run -d --name krill \
  -p 8741:8741 \
  -e KRILL_API_KEY=sk-... \
  -v krill-state:/home/krill/.krill \
  -v krill-workspace:/workspace \
  krill

With Podman, use podman build --format docker to preserve the HEALTHCHECK directive.

The container runs as non-root (krill, UID 1000). Two named volumes persist state across restarts:

• krill-state — config, prompts, memory, skills (~/.krill/)
• krill-workspace — agent workspace files (/workspace)

If connecting from a Docker bridge IP (e.g. 172.17.0.1), add it to allowed_hosts:

-e KRILL_GATEWAY__ALLOWED_HOSTS='["172.17.0.1","127.0.0.1","::1"]'

Development

uv sync --extra dev        # install all deps including pytest, ruff, pyright

# Set up pre-commit hooks (one-time)
pip install pre-commit
bash scripts/setup-hooks.sh

# Run tests, linting, and type checking
uv run pytest              # run all tests
uv run pytest -x           # stop on first failure
uv run ruff check .        # lint
uv run ruff format .       # format
uv run pyright             # type check (krill/ only)

# Or run pre-commit checks manually
pre-commit run --all-files

Pre-commit hooks automatically run on each commit:

• Ruff linting and formatting
• PII detection (checks for hardcoded paths and personal emails)

Live integration tests

Tests that hit real external services (web search, page fetch) are skipped by default:

uv run pytest tests/test_tools_web_live.py -v --run-live

See CLAUDE.md for the full development guide, module boundaries, and git worktree workflow.

Architecture & Design

For detailed architecture documentation:

• Architecture Overview — Module boundaries, stack, two-process design
• Concurrent Architecture — RPC gateway, approval flow, space-backed coordination
• Architectural Decisions — Decided vs. open design questions with trade-off analysis
• Security Architecture — Layered security model (application, OS, container)
• Approval Enhancements — Approval system architecture and harness

License

MIT