kestrel-sovereign

Prerequisites

• Python 3.11-3.14
• uv (for package management)
• Ollama (optional - for local LLM inference without API keys)

Install uv

If you don't have uv installed:

```bash

Installation

```bash

1. Clone and setup

git clone https://github.com/KestrelSovereignAI/kestrel-sovereign.git cd kestrel-sovereign uv sync # Creates .venv and installs all dependencies

3. Run the setup wizard. Interactive by default; --quickstart

Install from PyPI (no source clone)

The Quick Start above clones the repo so you have demos, examples, and the kestrel.toml.example next to your agent. If you only want to run an agent and don't need the source tree, install from PyPI:

```bash

1. Install the CLI (uv tool install is preferred — `kestrel`

lands on PATH in an isolated venv. Plain `pip install

Pip-installed users invoke the in-package module (the wheel only ships

Clean Install Verification

Kestrel supports multiple installation configurations. Use the verification script to test that clean installs work correctly across all supported scenarios:

```bash

Run all 5 install scenarios (creates isolated venvs)

uv run kestrel verify-install

🚢 Deployment

Kestrel supports multiple deployment targets. See KESTREL_FEATURES.md for the full catalog.

Build and push to GCR (both single-agent and multi_agent images)

uv run kestrel deploy build

Deploy to dev (multi-agent host, always warm) or prod (single-agent, auto-scales)

uv run kestrel deploy dev uv run kestrel deploy prod ```

Profiles live in deploy_config.toml. See docs/deployment/README.md for the full runbook (status, logs, teardown, health).

Auto-deploys on version tags via GitHub Actions.

Docker (Local)

```bash

🚀 Quick Start

accepts every default non-interactively. --quickstart auto-detects

Or hand-edit: cp kestrel.toml.example kestrel.toml

5. (Optional) Create an additional agent. `--quickstart` already

After --quickstart with no step 5, the autostart agent is "Kestrel".

uv run kestrel start # starts every agent with autostart=true uv run kestrel start Kestrel # if you only ran --quickstart uv run kestrel start MyAgent # if you ran step 5 (works regardless of autostart) ```

If you're upgrading from a pre-2026-05 setup that used a standalone llm_config.toml, run uv run kestrel migrate-llm-config to fold it into kestrel.toml [llm]. The legacy file is no longer read.

Your agent is now running. Two ports to know about, depending on which start form you used:

Port conflict? Edit the agent's entry in multi_agent.toml to change its port, or recreate the agent with a chosen port (kestrel create MyAgent --port 8899). Edit multi_agent.toml's [host] section to change the host port (default 8888). kestrel start itself doesn't take a --port flag — runtime ports are read from multi_agent.toml.

Test it: Visit the URL the CLI printed on start (http://localhost:8888 for the multi-agent host, or whatever per-agent port kestrel start <name> reported). The Sovereign Console is the default page; append /health for a JSON readiness probe.

Windows users: the CLI prints emoji. If you see UnicodeEncodeError: 'charmap' codec can't encode character ..., run chcp 65001 once in your PowerShell session to switch the console to UTF-8. (As of v0.1.9 the CLI auto-reconfigures stdout, so a fresh install should not hit this.)

💡 Example Applications

Kestrel is a foundation for AI agents that need to outlive any single vendor, deployment, or owner. Concrete deployments and good-fit use cases:

• Healthcare RPM agents — Constitutional governance over an LLM, persistent patient-owned memory, audit trail for every clinically-relevant action.
• Long-running personal research agents — Memory accumulates across months without dependency on a single provider's chat history.
• Custodial agents for sensitive document workflows — Privacy-mode tiers (EPHEMERAL → PUBLIC) let one agent handle both an off-the-record consult and a fully-anchored long-term contract.
• Multi-agent A2A networks — JSON-RPC 2.0 agent-to-agent protocol lets sovereign agents collaborate without surrendering their identity to a central broker.

2. (Optional) Start Ollama for local models - skip if using cloud APIs

ollama serve ollama pull llama3.2:3b

GOOGLE_API_KEY) in your shell env, probes Ollama at

kestrel-sovereign` works too, into whichever venv is active.)

uv tool install kestrel-sovereign

3. Same wizard as above. Writes .env, kestrel.toml, multi_agent.toml,

Per-Agent Configuration

Each agent can have a kestrel.toml config file in its directory:

```toml

🔧 Configuration

LLM Configuration (`kestrel.toml` `[llm]`)

LLM config lives under the [llm] section of kestrel.toml. The setup wizard (kestrel setup llm) will write it for you; you can also hand-edit kestrel.toml after copying from kestrel.toml.example.

Kestrel uses a vendor/route/model schema. A vendor is who makes the weights; a route is how to reach them (adapter + base URL + auth). API keys belong in .env and are referenced by api_key_env. See kestrel.toml.example and docs/architecture/LLM_SERVICE_ARCHITECTURE.md for the canonical spec.

[llm]
route_priority = ["openai:api", "ollama:local"]

[llm.vendors.openai]
is_cloud = true

[llm.vendors.openai.routes.api]
adapter        = "OpenAIAdapter"
api_key_env    = "OPENAI_API_KEY"
model          = "auto"
selection_hints = ["gpt-5", "mini"]

[llm.vendors.ollama]
is_cloud = false

[llm.vendors.ollama.routes.local]
adapter        = "OllamaAdapter"
host           = "http://localhost:11434"
model          = "auto"
selection_hints = ["llama3.2", "qwen"]

Pre-2026-05 setups used a standalone llm_config.toml at the repo root. That path was removed (epic #938). Run kestrel migrate-llm-config to fold a legacy file into kestrel.toml [llm]; the source is renamed to .bak, your prior kestrel.toml is timestamp-backed-up, and the operation is idempotent.

Environment Variables

See .env.example for a complete list. Key variables:

LLM Providers: - OPENROUTER_API_KEY: OpenRouter API key (recommended - access to multiple providers) - OPENAI_API_KEY: OpenAI API key for cloud models - ANTHROPIC_API_KEY: Anthropic API key for Claude models

Storage: - KESTREL_DB_PATH: Directory where the agent database is stored (default: ./agent_data). This is a directory path -- the database file kestrel_prime.db is created inside it. - KESTREL_DATA_KEY: Fernet encryption key for data at rest

GitHub Integration: - GITHUB_TOKEN: Personal access token for GitHub features - GITHUB_SELF_REPO: Agent's source repository (default: KestrelSovereignAI/kestrel-sovereign)

One-time: set up GCP secrets from .env

uv run kestrel deploy secrets sync

Optional: Full-DB Encryption (SQLCipher)

• If you install pysqlcipher3 and set KESTREL_DB_KEY, the SQLite connection will use SQLCipher and encrypt the entire DB:

export KESTREL_DB_KEY="your-db-passphrase"
uv run python -m kestrel_sovereign.server

• Without pysqlcipher3, the system falls back to normal SQLite. File blobs and conversations still encrypt with KESTREL_DATA_KEY if set.

available LLM providers — checks for cloud API keys

(OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY,

CLI Commands (Cross-Platform)

All commands work on Windows, macOS, and Linux. Pass the agent directory as an argument:

uv run kestrel health                       # Check prerequisites
uv run kestrel create MyAgent               # Create a new agent
uv run kestrel start MyAgent                # Start an agent
uv run kestrel stop MyAgent                 # Stop an agent
uv run kestrel status                       # Show all running agents
uv run kestrel list                         # List available agents
uv run kestrel shell MyAgent                # CLI chat interface
uv run kestrel config ./agent_data/MyAgent  # Show agent config

CLI chat (no server needed)

uv run python -m kestrel_sovereign.main ./agent_data/myagent

The Kestrel SDK lives in its own repo + PyPI package:

kestrel-sovereign-sdk (https://github.com/KestrelSovereignAI/kestrel-sovereign-sdk)

from kestrel_sdk.features.base import Feature, tool

from kestrel_sdk.tools.base import ToolCategory, ToolResult

from kestrel_sdk.hooks.base import Hook, HookEvent

```

Standalone with Ollama (no API keys needed)

docker build -f docker/Dockerfile.standalone -t kestrel-standalone . docker run -p 8888:8888 kestrel-standalone

🧩 OpenAI-Compatible API

The server exposes OpenAI-compatible endpoints for use with third-party clients:

• GET /v1/models
• POST /v1/chat/completions

For most users, the built-in Sovereign Console at the printed URL (http://localhost:8888 for the multi-agent host, or the agent's own port for a single-agent start) is the easiest way to interact with your agent (see the Web UI section above). If you prefer an external client, point any OpenAI-compatible tool (e.g., Open WebUI) at your server's /v1/chat/completions endpoint. Use the model name from /v1/models.

Auth: every request to /v1/... requires the X-API-Key header (or Authorization: Bearer <key>). The key was written to .env as KESTREL_API_KEY by kestrel setup (or --quickstart). Most OpenAI-compatible clients let you set the key via their OPENAI_API_KEY env var or settings UI; point that at your KESTREL_API_KEY value.

📚 Key Files Reference

Alternative: Direct Commands

```bash