Settings Guide
Complete configuration reference for ChipOS
Features
The Features section controls which functionality is enabled in ChipOS. Toggle these settings to customize your experience.
Dark Mode
Switch between light and dark color themes
| Default | Enabled (Dark) |
| Effect | Changes entire UI color scheme |
| When to Use | Personal preference; dark mode reduces eye strain in low light |
Projects
Enable Projects and Tasks functionality
| Default | Enabled |
| Effect | Shows Projects sidebar, allows task management |
| Requirements | ChipOS schema migrations applied (chipos_projects + chipos_tasks tables) |
Note: If you see "Projects table not detected",
apply the latest ChipOS migrations in chipos-acf/migration/
(start with complete_setup.sql) or use hosted mode.
Pydantic Logfire
Structured logging and observability platform
| Default | Disabled |
| Effect | Sends telemetry data to Pydantic Logfire for debugging |
| Requirements | LOGFIRE_TOKEN in environment |
API Keys
Manage credentials for external services. API keys power the AI features, embeddings, and external integrations.
Supported API Keys
| Key Name | Service | Purpose |
|---|---|---|
VOYAGE_API_KEY |
Voyage AI | Default embeddings (voyage-code-3) |
OPENAI_API_KEY |
OpenAI | RAG queries, embeddings, AI chat |
ANTHROPIC_API_KEY |
Anthropic | Claude models for chat and reasoning |
GOOGLE_API_KEY |
Google Gemini | Alternative LLM provider |
OPENROUTER_API_KEY |
OpenRouter | Multi-provider model routing |
GROK_API_KEY |
Grok | Grok models and provider status checks |
GITHUB_TOKEN |
GitHub | Crawling private repositories |
GitHub Token
Add a GitHub token to enable private repository ingestion and higher API rate limits.
Hosted Auth
Configure hosted auth URL and project ref for hosted mode or enterprise deployments.
Key Features
Encryption
Click lock icon to encrypt sensitive values
Show/Hide
Click eye icon to reveal masked values
Add New
Add custom API keys as needed
Security Tip: Always encrypt API keys. Encrypted credentials are stored securely and cannot be viewed after saving.
Ollama (Local Models)
The Ollama panel validates local instances, discovers models, and reports health for on-prem deployments.
What You Can Do
- Validate instance URL and connectivity
- Discover and store available models
- View stored models and instance health
Docker tip: If the backend runs in Docker, use
http://host.docker.internal:11434 (or http://172.17.0.1:11434 on
Linux) as the instance URL.
RAG Settings
RAG (Retrieval-Augmented Generation) settings control how ChipOS retrieves and processes knowledge from your documentation.
Voyage AI's voyage-code-3 is now the
default embedding model, offering 13-17% better code retrieval than
OpenAI while using 33% less memory (1024 vs 1536 dimensions). Get your API key at voyage.ai.
LLM Provider & Models
| Provider | Recommended Chat Model | Embedding Model |
|---|---|---|
| Voyage AI (default) | N/A (embeddings-only) | voyage-code-3 (1024 dims) |
| OpenAI | gpt-4.1-nano (default), gpt-4o-mini, gpt-4o |
text-embedding-3-small |
| Google Gemini | gemini-1.5-flash |
text-embedding-004 |
| Ollama (local) | llama3, mistral |
nomic-embed-text |
RAG Strategy Toggles
Use Contextual Embeddings
Enhances embeddings with surrounding context for better retrieval
Default: Disabled | Workers: 1-10 (default 3)
Use Hybrid Search
Combines vector similarity with BM25 keyword search
Default: Enabled |
Better for exact identifiers like AXI_AWREADY
Use Agentic RAG
Enables agentic code-example retrieval and enhanced code search
Default: Enabled | Improves code-specific queries
Use Reranking
Applies cross-encoder reranking to improve result relevance
Default: Enabled | Re-scores top results for better accuracy
Use Query Classification
Analyzes query intent and routes to the optimal search strategy
Default: Enabled | Distinguishes code queries from conceptual queries
Use Context Expansion
Retrieves surrounding chunks from the same file for better context
Default: Enabled | Essential for code queries to understand full context
Crawling Performance Settings
| Setting | Default | Range | Description |
|---|---|---|---|
| Batch Size | 50 | 10-100 | URLs to queue per crawl batch |
| Max Concurrent | 3 | 1-20 | Pages to crawl simultaneously |
| Wait Strategy | DOM Loaded | - | When to consider page loaded |
| Page Timeout | 60 sec | 5-120 | Max time to wait for page |
| Render Delay | 0.5 sec | 0.1-5 | Wait after load before extracting |
Wait Strategy Options
Storage Performance Settings
| Setting | Default | Range | Description |
|---|---|---|---|
| Document Batch Size | 50 | 10-100 | Chunks per database insert batch |
| Embedding Batch Size | 100 | 20-200 | Embeddings per API call |
| Code Extraction Workers | 3 | 1-10 | Parallel code summary workers |
| Enable Parallel Batches | Enabled | - | Process multiple batches simultaneously |
Code Extraction Settings
These settings control how code blocks are detected and extracted from crawled documents.
Code Block Length
| Setting | Default | Range | Description |
|---|---|---|---|
| Minimum Length | 250 chars | 50-2000 | Shortest code block to extract |
| Maximum Length | 5000 chars | 1000-20000 | Longest code block to extract |
Tip: Increase minimum for higher quality (fewer snippets). Decrease to capture short examples.
Detection Features
Complete Block Detection
Extend code blocks to natural boundaries (closing braces, etc.)
Language-Specific Patterns
Use specialized patterns for TypeScript, Python, Verilog, etc.
Contextual Length Adjustment
Adjust minimum length based on context (example, snippet, implementation)
Content Filtering
Filter Prose Content
Remove documentation text mistakenly wrapped in code blocks
Filter Diagram Languages
Exclude Mermaid, PlantUML, and other diagram formats
Generate Code Summaries
Use AI to create summaries and names for code examples
Recommended Configurations
Hardware Documentation
- Use Contextual Embeddings: Enabled
- Use Hybrid Search: Enabled
- Use Agentic RAG: Enabled
- Wait Strategy: DOM Loaded
- Generate Code Summaries: Enabled
Large Codebases
- Max Discovered Pages: 50,000
- Embedding Batch Size: 200
- Code Extraction Workers: 5
- Parallel Batches: Enabled
- Use path regex filters
Low-Resource Systems
- Use Contextual Embeddings: Disabled
- Batch Size: 25
- Max Concurrent: 3
- Parallel Batches: Disabled
API Cost Optimization
- Contextual Embeddings: Disabled
- Code Summaries: Disabled
- Embedding Batch Size: 50
- Model: gpt-4.1-nano
Troubleshooting
"Failed to save settings"
- Check hosted auth connection
- Verify using service_role key (NOT anon key)
- Check browser console for detailed error
"Projects table not detected"
- Apply ChipOS migrations in
chipos-acf/migration/(start withcomplete_setup.sql) - Restart the server after migration
Slow crawling
- Reduce Max Concurrent to 3-5
- Use "DOM Loaded" wait strategy
- Check network/server response times
Poor search results
- Enable Hybrid Search
- Enable Reranking
- Increase Context Window Size
- Re-crawl sources with updated settings