ChromaDB

Category: Infrastructure Stack: Sentient Stronghold Status: ✅ Operational Deployed: 2026-02-09 Server: Dell Stronghold (192.168.1.XXX)

Overview

ChromaDB is a vector database providing semantic memory capabilities for Claude Code and OpenClaw. It enables intelligent knowledge retrieval by storing and searching homelab documentation, decisions, and infrastructure details using embeddings.

Purpose

Semantic Memory Backend for Claude Code CLI
Shared Knowledge Base for AI agents (Claude Code + OpenClaw)
Context Window Optimization - load only relevant chunks instead of full files
Intelligent Search across 1,460+ documents from Obsidian vault and project files

Service Details

Connection Info

Host: 192.168.1.XXX
Port: 8000 (HTTP)
API: ChromaDB v1.0.0 (using v2 API)
Authentication: bearer [REDACTED] (environment variable)
Network: Homelab subnet only (192.168.1.XXX/24)

Docker Configuration

services:
  chromadb:
    image: chromadb/chroma:latest
    container_name: chromadb
    ports:
      - "192.168.1.XXX:8000:8000"
    environment:
      - CHROMA_SERVER_AUTHN_PROVIDER=chromadb.auth.token_authn.TokenAuthenticationServerProvider
      - CHROMA_SERVER_AUTHN_CREDENTIALS=${CHROMADB_AUTH_TOKEN}
      - CHROMA_AUTH_TOKEN_TRANSPORT_HEADER=Authorization
    volumes:
      - ./chroma-data:/chroma/chroma
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v2/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 2G

Collections

Collection	Documents	Content
`infrastructure`	252	Network topology, service configs, Docker stacks, Dell Stronghold plan
`decisions`	431	Changelogs, security decisions, architecture choices, troubleshooting
`documentation`	777	Service pages, project docs, references, guides
Total	1,460	Complete homelab knowledge base

Architecture

Workstation (Pop!_OS)                    Dell Stronghold (192.168.1.XXX)
┌─────────────────────┐                  ┌──────────────────────────┐
│ Claude Code CLI     │                  │ ChromaDB (:8000)         │
│   ↕ MCP (stdio)     │                  │   - infrastructure       │
│ chroma-mcp server   │──── HTTP ───────▶│   - decisions            │
│                     │   (token auth)   │   - documentation        │
│ Ingestion Script    │──── HTTP ───────▶│                          │
└─────────────────────┘                  │ OpenClaw ── internal ──▶ │
                                         └──────────────────────────┘

Components

ChromaDB Server - Vector database running in Docker
Ingestion Pipeline - Python script that processes markdown files
MCP Server - Claude Code integration (known SSL issue)
Python Client - Direct HTTP access for ingestion and queries

Embedding Model

Current: all-MiniLM-L6-v2 (ChromaDB default)
Runtime: In-container (no external dependencies)
Future: Migrate to nomic-embed-text via Mac Studio Ollama

Security

Defense in Depth

Network Binding - Bound to Dell IP only (192.168.1.XXX:8000, not 0.0.0.0)
Token Authentication - bearer [REDACTED] required for all API requests
UFW Firewall - Port 8000 restricted to homelab subnet (192.168.1.XXX/24)
No External Exposure - Internal network only

Credentials

Token Location (Dell): ~/stronghold/.env → CHROMADB_AUTH_TOKEN
Token Location (Workstation): /home/cib/ai-assistant-config/scripts/.env
Token Generation: openssl rand -hex 32 (256-bit entropy)
File Permissions: chmod 600 .env (read/write owner only)
Version Control: .env files excluded via .gitignore

Operations

Ingestion Pipeline

Script: /home/cib/ai-assistant-config/scripts/ingest-to-chromadb.py

Full Sync (Re-index everything):

cd /home/cib/ai-assistant-config/scripts
./venv/bin/python ingest-to-chromadb.py --full

Incremental Sync (Changed files only):

cd /home/cib/ai-assistant-config/scripts
./venv/bin/python ingest-to-chromadb.py

Dry Run (Preview without writing):

./venv/bin/python ingest-to-chromadb.py --dry-run --verbose

Source Files

The ingestion pipeline automatically processes:

Obsidian Vault: /home/cib/Documents/HomeLab/HomeLab/**/*.md
Documents: /home/cib/Documents/*.md
Claude Config: /home/cib/ai-assistant-config/session/MEMORY.md
Project Files: /home/cib/ai-assistant-config/projects/*/CLAUDE.md
Docker Configs: docker-compose.yml files

Querying

Python Client Example:

import chromadb
import os
 
client = chromadb.HttpClient(
    host="192.168.1.XXX",
    port=8000,
    headers={"Authorization": f"Bearer {os.getenv('CHROMADB_AUTH_TOKEN')}"}
)
 
# Query infrastructure
infra = client.get_collection("infrastructure")
results = infra.query(
    query_texts=["What services are running on Dell?"],
    n_results=5
)
 
for doc in results['documents'][0]:
    print(doc)

Monitoring

Health Check:

curl -H "Authorization: Bearer $CHROMADB_AUTH_TOKEN" \
  http://192.168.1.XXX:8000/api/v2/heartbeat

Collection Counts:

cd /home/cib/ai-assistant-config/scripts
./venv/bin/python << EOF
import chromadb, os
from dotenv import load_dotenv
load_dotenv('.env')
client = chromadb.HttpClient(
    host="192.168.1.XXX", port=8000,
    headers={"Authorization": f"Bearer {os.getenv('CHROMADB_AUTH_TOKEN')}"}
)
for coll in client.list_collections():
    print(f"{coll.name}: {coll.count()} documents")
EOF

Container Status:

ssh 192.168.1.XXX 'docker ps | grep chromadb'

Troubleshooting

Connection Refused

Symptoms: Cannot connect to ChromaDB at 192.168.1.XXX:8000

Solutions:

Verify Dell is reachable: ping 192.168.1.XXX
Check container status: ssh 192.168.1.XXX 'docker ps | grep chromadb'
Check UFW: ssh 192.168.1.XXX 'sudo ufw status | grep 8000'
Test heartbeat: curl http://192.168.1.XXX:8000/api/v2/heartbeat

Authentication Failed (401)

Symptoms: ChromaDB returns 401 Unauthorized

Solutions:

Verify token matches between workstation and Dell:

grep CHROMADB_AUTH_TOKEN /home/cib/ai-assistant-config/scripts/.env
ssh 192.168.1.XXX 'grep CHROMADB_AUTH_TOKEN ~/stronghold/.env'

Ensure token is sent in header: -H "Authorization: Bearer $TOKEN"

MCP Server Not Connected

Status: Known issue - SSL/HTTPS mismatch

Workaround: Use Python client directly (already working)

Future Fix Options:

Configure ChromaDB with SSL/TLS certificates
Find chroma-mcp SSL configuration settings
Use alternative MCP integration

No Search Results

Symptoms: Queries return empty results

Solutions:

Verify collections populated:

cd /home/cib/ai-assistant-config/scripts
./venv/bin/python << EOF
import chromadb, os
from dotenv import load_dotenv
load_dotenv('.env')
client = chromadb.HttpClient(
    host="192.168.1.XXX", port=8000,
    headers={"Authorization": f"Bearer {os.getenv('CHROMADB_AUTH_TOKEN')}"}
)
for coll in client.list_collections():
    print(f"{coll.name}: {coll.count()}")
EOF

Re-run ingestion if counts are low:

./venv/bin/python ingest-to-chromadb.py --full

Embedding Dependencies

Error: onnxruntime or tokenizers not installed

Solution:

cd /home/cib/ai-assistant-config/scripts
./venv/bin/pip install onnxruntime tokenizers

Maintenance

Daily (Automated)

Incremental Ingestion - Optional cron job for auto-sync

0 6 * * * cd /home/cib/ai-assistant-config && python3 scripts/ingest-to-chromadb.py >> /tmp/chromadb-ingest.log 2>&1

Weekly

Review ingestion logs: tail -100 /tmp/chromadb-ingest.log
Check collection counts for unexpected changes
Verify disk space: ssh 192.168.1.XXX 'du -sh ~/stronghold/chroma-data'

Monthly

Backup ChromaDB data:

ssh 192.168.1.XXX 'tar -czf ~/chroma-backup-$(date +%Y%m%d).tar.gz ~/stronghold/chroma-data'

Token Rotation: Regenerate auth token for security best practice
Review embedding model performance (consider upgrade to nomic-embed-text)

Quarterly

Update Python dependencies: pip install --upgrade -r requirements-chromadb.txt
Review context window savings vs semantic quality
Evaluate migration to advanced embedding models

Performance

Current Metrics

Total Documents: 1,460
Query Latency: <1 second for semantic search
Embedding Model: all-MiniLM-L6-v2 (384 dimensions)
Memory Usage: ~500MB (varies with dataset size)
Storage: ~50MB for 1,460 documents + embeddings

Expected Savings

Metric	Before ChromaDB	After ChromaDB	Improvement
Base Context Load	9.1 KB	9.1 KB	-
Worst Case (homelab-ops)	23.8 KB	~9.3 KB	-61%
Knowledge Retrieval	Load everything	Load relevant chunks	Semantic
Scalability	Linear growth	Constant base + query	∞

Future Enhancements

Planned

Migrate to nomic-embed-text embeddings via Mac Studio Ollama
Fix MCP server SSL issue for native Claude Code integration
Implement document versioning/history tracking
Add monitoring/metrics (query latency, hit rate)
Support for non-markdown formats (logs, configs)

Considered

Collection-level access control (if multi-user needed)
Automated collection cleanup/archival
Integration with Grafana for usage dashboards
Export/backup automation to Synology NAS

Resources

Documentation: /home/cib/ai-assistant-config/scripts/README-chromadb.md
Deployment Guide: /home/cib/Documents/ChromaDB-Implementation-Summary.md
Quick Start: /home/cib/ai-assistant-config/scripts/QUICKSTART.md
Upstream Docs: https://docs.trychroma.com/
MCP Integration: https://github.com/chroma-core/chroma-mcp

Sentient Stronghold - Parent infrastructure project
Dell Stronghold - Host server
LiteLLM - AI router (future integration)
OpenClaw - Agent framework (future integration)
Obsidian-LiveSync - Vault sync (source data)

Notes

ChromaDB is part of the Sentient Stronghold stack but runs independently
The ingestion pipeline is idempotent - safe to run multiple times
Document IDs are based on file hash + chunk index for stable references
Telemetry to posthog.com fails (expected - no internet from ChromaDB)
Phase 6 (slimming CLAUDE.md files) is pending - awaiting further testing

Last Updated: 2026-02-09 Maintained By: James Hathcock via Claude Code

Hathcock Homelab Wiki

Explorer

ChromaDB

ChromaDB

Overview

Purpose

Service Details

Connection Info

Docker Configuration

Collections

Architecture

Components

Embedding Model

Security

Defense in Depth

Credentials

Operations

Ingestion Pipeline

Source Files

Querying

Monitoring

Troubleshooting

Connection Refused

Authentication Failed (401)

MCP Server Not Connected

No Search Results

Embedding Dependencies

Maintenance

Daily (Automated)

Weekly

Monthly

Quarterly

Performance

Current Metrics

Expected Savings

Future Enhancements

Planned

Considered

Resources

Related Services

Notes

Graph View

Table of Contents

Backlinks