Configuration¶

All configuration is managed through environment variables in .env (or exported in your shell). Copy .env.example to get started:

cp .env.example .env

The .env.example file is intentionally minimal — it only contains variables you need to set. Everything else has sensible defaults in code and can be overridden in .env when needed.

Required Settings¶

LLM Provider¶

KOURAI_PROVIDER=anthropic          # anthropic | google | local
KOURAI_MODEL_TIER=cheap            # cheap | standard | smart

API Keys¶

Set the key matching your provider:

Optional Integrations¶

These are all optional. The system works without them — features that need a missing key are skipped gracefully.

GitHub¶

Used by Mneme (PR generation), Techne (code search), Metis, and Hephaestus.

GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxxx...

Create a token at github.com/settings/tokens with scopes: repo, read:org, gist.

Brave Search¶

Used by Aletheia for web search and claim verification.

BRAVE_API_KEY=YOUR_BRAVE_API_KEY

Sign up at brave.com/search/api.

HuggingFace (Artifact Storage)¶

Enables agent artifact sync and automated backups to HF Storage Buckets. Without this, artifacts save to local Docker volumes only.

HF_TOKEN=hf_xxx...

Create a write-scope token at huggingface.co/settings/tokens. The bucket ID is auto-derived as <your-username>/kourai-artifacts via the HF API. Override with KOURAI_BUCKET_ID if needed.

Player Project Database¶

Used by Techne and Dokimasia for database schema introspection. Only needed for database-backed player projects.

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/mydb

Docker Hub¶

For pushing built images and build cache.

DOCKER_HUB_USERNAME=your-username

Setup: create an account at hub.docker.com, create a PAT under Security settings, then docker login.

OpenAI (Fallback)¶

Optional fallback provider via LiteLLM.

OPENAI_API_KEY=sk-proj-...

Defaults & Overrides¶

These variables have sensible defaults in code. You only need to set them if you want to change the default behavior.

Agent Behavior¶

Infrastructure & Observability¶

Local LLM (Ollama)¶

When KOURAI_PROVIDER=local, make setup will check Ollama connectivity and auto-pull required models.

Artifact & Backup Settings¶

LLM Models¶

Agents are assigned models in shared/src/kourai_common/config.py based on KOURAI_PROVIDER and KOURAI_MODEL_TIER. Switch providers by changing one line in .env — LiteLLM handles the rest.

# Claude (your default)
KOURAI_PROVIDER=anthropic

# Gemini (e.g., Google AI Pro subscriber)
KOURAI_PROVIDER=google

# Ollama (free, local GPU)
KOURAI_PROVIDER=local

Agent Ports¶

Each agent runs on a fixed port:

Timeouts¶

Per-agent timeouts are defined in shared/src/kourai_common/config.py:

Docker Networking¶

Agents resolve each other via Docker service names on the kourai bridge network (e.g., http://techne:10002/). This is handled automatically by Docker Compose — no user configuration needed.

Text-to-Speech Configuration¶

The Pygame GUI includes a full text-to-speech system with neural voices and real-time audio control. Configure it in ~/.kourai_khryseai/settings.json or through the settings overlay.

TTS Settings¶

Voice Pacing Modes¶

See GUI Reference for voice profiles and audio customization.

Makefile Commands¶