Configuration

OpenKyrozen has separate provider connection settings and workspace behavior settings. Provider credentials come from their provider-specific environment variable, ambient cloud identity, or the encrypted user configuration flow. agent.yaml never stores provider secrets. The strict YAML loader rejects duplicate and unknown keys.

Agent configuration files and precedence

The application starts with packaged defaults, overlays the active workspace's agent.yaml, overlays the file selected by KYROZEN_AGENT_CONFIG (or by an explicit loader argument), then applies recognized environment overrides. Later layers take precedence for values they set. Relative workspace configuration stays inside the workspace; an explicitly selected file must exist.

The version 1 YAML object accepts:

Unknown keys, duplicate YAML mapping keys, invalid types, and out-of-range values fail configuration loading. A minimal example is agent.yaml. For agent role text, treat examples and project instructions as untrusted inputs; they cannot expand effective runtime capabilities.

Environment variables

The variable list is the supported, documented configuration surface at the v2.0.6 release snapshot. Variables marked as helper or test controls can change as implementations evolve; inspect the relevant entry point before building long-lived deployment tooling around them.

Provider selection

export KYROZEN_PROVIDER=deepseek
export DEEPSEEK_API_KEY=your-key
kyrozen

Other supported provider families include OpenAI, Anthropic, Google, Ollama, Z.AI, Moonshot/Kimi, OpenRouter, Groq, Mistral, xAI, Together, Fireworks, Cohere, Azure OpenAI, Perplexity, Bedrock, and Vertex.

Switch interactively with /provider. Ollama can run without a hosted API key:

export KYROZEN_PROVIDER=ollama
export KYROZEN_BASE_URL=http://127.0.0.1:11434/v1

Model selection

OpenKyrozen has separate defaults for simple and complex work:

export KYROZEN_MODEL_SIMPLE=deepseek-flash
export KYROZEN_MODEL_COMPLEX=deepseek-v4-pro

Set KYROZEN_MODEL_MAIN or use /model <name> to pin every main-agent request to one model. Use /model auto to return to the simple/complex choices. Sub-agent model assignments remain independent. Ollama requires an explicit installed model tag; /model shows discovered tags as suggestions and accepts a manually entered tag.

These names are the repository's DeepSeek registry defaults at the v2.0.6 documentation snapshot. They are not a promise that a provider account enables a particular model. The provider guide lists every current selectable family and its repository default; choose a model your account can access.

The model-visible context window can be set explicitly when a custom model is not recognized:

export KYROZEN_CONTEXT_WINDOW_TOKENS=128000

Sub-agent providers and concurrency

agent.yaml accepts subagents.concurrency (default 4, integer 1–64) and subagents.roles.<profile>.provider/model, with custom_profile for named custom endpoints. Additional assignments queue; there is no total-agent limit. Assignment overrides take precedence over role defaults, then the main provider/model. A reviewer uses the reviewer role default.

subagents:
  concurrency: 4
  roles:
    researcher:
      provider: openai
      model: your-openai-model
    reviewer:
      provider: anthropic
      model: your-claude-model
    local-reviewer:
      provider: custom
      custom_profile: office-gateway
      model: reviewer-model-id

Configure OPENAI_API_KEY and ANTHROPIC_API_KEY securely in the launching environment. Alternate providers never receive the main provider's generic KYROZEN_API_KEY, endpoint or model settings. Missing credentials block the run; there is no implicit cross-provider fallback. See sub-agents.

Custom OpenAI-compatible providers

Use /custom-provider create to save a named endpoint, optional API key, simple and complex model IDs, and optional context limit. /custom-provider edit <name>, list, use <name>, and remove <name> manage profiles. The TUI provider picker starts the same masked setup flow. Profile API keys are encrypted in ~/.kyrozen_config.json. Set provider: custom and custom_profile: <name> in a sub-agent role to use a different profile; a model value can override the profile's complex model for that role.

Web server

kyrozen-web --host 127.0.0.1 --port 8000
KYROZEN_SERVER_TOKEN=change-me kyrozen-web --host 0.0.0.0 --port 8000

Use a token whenever the server is reachable beyond localhost. The Docker image uses /app as its project root; mount persistent state separately when deploying it.

Learning provider

Learning starts in setup_required. Choose Local or Remote from /self-learning or the web API. Local uses an explicitly approved local Ollama model; Remote reuses the configured chat provider and labels usage as surface=learning. Deterministic indexing, retrieval, scoring, and outcome recording do not require an LLM.

State locations

Keep venv/, chroma_memory/, build output, and generated package metadata out of commits. See the security notes in README.md and the project guidelines in AGENTS.md.