--- title: Configuration Architecture | CodeWeaver Docs description: CodeWeaver is a code search engine for AI agents, designed to provide precise results that give agents exactly what they need for their tasks -- no more, no less. url: "https://docs.knitli.com/guides/configuration" type: static generatedAt: "2026-04-17T17:21:09.950Z" --- # Configuration Architecture [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[View in Markdown](/codeweaver/guides/configuration.md) [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F)[Share on X](https://x.com/intent/tweet?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F&text=Configuration%20Architecture)[Share on Threads](https://threads.net/intent/post?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F&text=Configuration%20Architecture)[Share on Bluesky](https://bsky.app/intent/compose?text=Configuration%20Architecture%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F)[Share on Reddit](https://reddit.com/submit?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F&title=Configuration%20Architecture)[Share on Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F&t=Configuration%20Architecture)[Share on Email](mailto:?subject=Configuration%20Architecture&body=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F)[Share on WhatsApp](https://wa.me/?text=Configuration%20Architecture%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F)[Share on Telegram](https://t.me/share/url?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fguides%2Fconfiguration%2F&text=Configuration%20Architecture) # Configuration Architecture [Section titled “Configuration Architecture”](#configuration-architecture) > **TL;DR:** CodeWeaver features a completely overhauled configuration system powered by Pydantic. Use it to define your providers, server settings, and performance limits. It catches setup errors at boot-time, ensuring your agent always has a reliable foundation. The configuration system is hierarchical, predictable, and strictly validated. Whether you use environment variables, a `.env` file, or a `codeweaver.toml`, the system ensures your settings are consistent before the application starts. --- ## The Configuration Hierarchy [Section titled “The Configuration Hierarchy”](#the-configuration-hierarchy) CodeWeaver uses a nested structure to organize settings. The top-level `CodeWeaverSettings` model contains several logical sections: ### 1. Core Settings [Section titled “1. Core Settings”](#1-core-settings) Shared across all installations (Core, Provider, Engine, and Server). - `logging`: Log levels and formats. - `telemetry`: Privacy-preserving usage reporting. - `project_path`: The root of your codebase. ### 2. Provider Settings (`[provider]`) [Section titled “2. Provider Settings ([provider])”](#2-provider-settings-provider) This is where you define the “brains” of CodeWeaver. - `embedding`: Primary and query embedding models. - `sparse_embedding`: Models for hybrid search. - `reranking`: The final “judge” that ranks the most relevant snippets. - `vector_store`: Where your embeddings are stored (e.g., Qdrant). - `agent`: Configuration for the Context Agent (e.g., Anthropic Claude). ### 3. Server Settings [Section titled “3. Server Settings”](#3-server-settings) Specific to the CodeWeaver daemon and MCP integration. - `mcp_server`: HTTP and Stdio transport settings. - `management_port`: Port for health checks and metrics (default: 9329). - `uvicorn`: Web server tuning. --- ## Validation & Reliability [Section titled “Validation & Reliability”](#validation--reliability) CodeWeaver uses **Pydantic V2** to enforce strict validation. This means: 1. **Boot-time Failure:** If you provide an invalid URL or a missing API key, CodeWeaver will fail immediately with a clear error message instead of crashing later during a search. 1. **Type Safety:** Numbers, booleans, and nested objects are automatically converted and validated. 1. **Discriminator Support:** The system automatically picks the correct configuration schema based on your `provider` name (e.g., if you set `provider = "voyage"`, it expects Voyage-specific options). --- ## Profiles: The Fast Track [Section titled “Profiles: The Fast Track”](#profiles-the-fast-track) Instead of configuring every provider manually, you can use a **Profile**. Profiles are pre-configured bundles that balance cost, quality, and performance. | Profile | Best For | Requirement | | --- | --- | --- | | **`recommended`** | Production use, high precision. | Voyage AI API Key. | | **`quickstart`** | Local development, testing. | No API keys (FastEmbed/Local Qdrant). | | **`testing`** | CI/CD, unit tests. | In-memory storage. | You can activate a profile during initialization: *Terminal window* ``` cw init --profile recommended ``` --- ## Precedence Order [Section titled “Precedence Order”](#precedence-order) When the same setting is defined in multiple places, CodeWeaver follows this priority: 1. **Environment Variables** (e.g., `CODEWEAVER_LOGGING__LEVEL=DEBUG`) 1. **Explicit `init` arguments** 1. **Local `.env` files** 1. **Project-level `codeweaver.toml`** 1. **User-level config** (e.g., `~/.config/codeweaver/config.toml`) 1. **Defaults**