Skip to content
Crucible

Windows Setup

This guide covers Windows-specific configuration and troubleshooting for Crucible.

Configuration File Locations

Crucible uses a cross-platform configuration system that works consistently across Linux, macOS, and Windows.

Main Configuration File

The primary configuration file location follows platform conventions:

  • Linux: ~/.config/crucible/config.toml (XDG Base Directory)
  • macOS: ~/Library/Application Support/crucible/config.toml
  • Windows: %APPDATA%\crucible\config.toml (e.g., C:\Users\YourName\AppData\Roaming\crucible\config.toml)

Note: On Windows, Crucible uses %APPDATA% (Roaming AppData) which is the standard Windows location for user configuration files that should roam with the user profile.

Kiln-Specific Configuration

Each kiln (knowledge base) can have its own configuration:

  • Kiln metadata: KILN_ROOT\.crucible\kiln.toml
  • SQLite database: KILN_ROOT\.crucible\crucible-sqlite.db (notes, links, text index, embeddings)
  • Agent cards: KILN_ROOT\.crucible\agents\

Discovery Paths

Agent cards are collected from every directory below; a card found later shadows a card of the same name found earlier, so the workspace wins and the user-wide directory loses:

  1. %APPDATA%\crucible\agents\
  2. KILN_ROOT\.crucible\agents\, then KILN_ROOT\agents\, then KILN_ROOT\Agents\
  3. WORKSPACE\.crucible\agents\ (when the workspace is not the kiln)

Creating Your Configuration File

To create your configuration file on Windows:

Terminal window
# Create the config directory
New-Item -ItemType Directory -Force -Path "$env:APPDATA\crucible"


# Create a basic config file
@"
default_kiln = "notes"


[kilns]
notes = 'C:\Users\YourName\Documents\my-kiln'


[enrichment.provider]
type = "fastembed"
model = "BAAI/bge-small-en-v1.5"
batch_size = 16
"@ | Out-File -FilePath "$env:APPDATA\crucible\config.toml" -Encoding utf8

Or manually create the file at: C:\Users\YourName\AppData\Roaming\crucible\config.toml

Environment Variables

The CRUCIBLE_* variables are the same on every platform — see Configuration for the full list. Only the default paths are spelled with backslashes: CRUCIBLE_HOME defaults to %USERPROFILE%\.crucible, CRUCIBLE_LOG_FILE to %USERPROFILE%\.crucible\<command>.log, and CRUCIBLE_CONFIG_DIR overrides %APPDATA%\crucible.

Building on Windows

Prerequisites

  1. Rust toolchain: Install from rustup.rs

    • Select “x86_64-pc-windows-msvc” (default)
    • Or “x86_64-pc-windows-gnu” if you prefer MinGW

  2. Visual Studio Build Tools (for MSVC toolchain):

    • Install “Desktop development with C++” workload
    • Or install Visual Studio Community with C++ support

  3. Git: For cloning the repository

Build Commands

Terminal window
# Build all crates (debug)
cargo build


# Build release
cargo build --release


# Run tests
cargo test


# Run specific test
cargo test -p crucible-daemon --test llm_backend_comparison

C Runtime Library Configuration

On Windows, Rust uses the MSVC toolchain which requires consistent C runtime library linkage across all dependencies. You may encounter linker errors if dependencies are compiled with different runtime settings:

error LNK2038: mismatch detected for 'RuntimeLibrary':
value 'MT_StaticRelease' doesn't match value 'MD_DynamicRelease'

Solution

The project includes a .cargo/config.toml file that ensures consistent dynamic runtime linkage (the default on Windows). This matches most dependencies including:

  • ONNX Runtime (ort_sys) - used by FastEmbed
  • Most Rust crates on Windows

Troubleshooting Runtime Mismatch

If you see LNK2038 errors:

  1. Clean and rebuild (most common fix):

    Terminal window
    cargo clean
    cargo build

  2. Verify .cargo/config.toml exists and uses dynamic runtime (default)

  3. Rebuild dependencies from source if needed:

    Terminal window
    cargo clean
    cargo build --verbose

  4. If the issue persists, consider:

    • Using a different embedding provider (e.g., Ollama instead of FastEmbed)
    • Checking for updated dependency versions

ONNX Runtime (FastEmbed) Issues

FastEmbed uses ONNX Runtime for local embedding generation. On Windows, this can cause C runtime library mismatches.

Diagnostic Steps

  1. Run the diagnostic test:

    Terminal window
    cargo test -p crucible-daemon --features fastembed --test llm_onnx_windows_diagnostics -- --nocapture

  2. Verify build configuration: Ensure .cargo/config.toml contains:

    [target.'cfg(windows)']
    rustflags = ["-C", "target-feature=-crt-static"]

  3. Verify Visual C++ Redistributable: Check for msvcp140.dll and vcruntime140.dll in C:\Windows\System32\

    If missing, install from: https://aka.ms/vs/17/release/vc_redist.x64.exe

Alternative Providers

If ONNX Runtime issues persist, use alternative embedding providers:

  • Ollama: Local or remote, requires Ollama server
  • llama.cpp: GGUF models, excellent Windows support
  • OpenAI/Anthropic: Cloud-based APIs

All providers work on Windows and can be configured in config.toml.

Common Issues

Missing DLLs

If you get “missing DLL” errors at runtime:

  1. Install Visual C++ Redistributable
  2. Ensure all dependencies are in your PATH
  3. For ONNX Runtime, ensure onnxruntime.dll is accessible

Long Path Issues

If you encounter path length errors:

  1. Enable long path support in Windows (requires admin):
    Terminal window
    New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
      -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
  2. Or use shorter paths for your kiln directory

Path Handling

Windows paths are handled automatically:

  • Forward slashes (/) are converted to backslashes (\) where needed
  • UNC paths (\\server\share) are supported
  • Long paths (260+ characters) require Windows 10+ with long path support enabled

Testing on Windows

Tests are designed to work cross-platform:

  • Path separators are normalized automatically
  • Line endings (CRLF vs LF) are handled transparently
  • File watching may have different timing on Windows
Terminal window
# All tests
cargo test


# Specific crate
cargo test -p crucible-daemon


# With output
cargo test -- --nocapture


# ONNX Runtime diagnostic test
cargo test -p crucible-daemon --features fastembed --test llm_onnx_windows_diagnostics -- --nocapture

Performance Considerations

  • File watching: Windows file system events may have different latency than Linux
  • Embedding models: ONNX Runtime performance is similar across platforms
  • Database: SQLite performance is consistent on Windows

See Also