Deployment

Deploy th0th to production using Docker or from source

Overview

th0th can be deployed in multiple ways depending on your infrastructure needs. The system is designed for local-first operation with zero external dependencies when using Ollama for embeddings.

Quick Start with Docker

The recommended deployment method uses Docker Compose for both the API and MCP services.

1. Clone the repository

   git clone https://github.com/S1LV4/th0th.git
   cd th0th
   
2. Set up environment variables

   Create a .env file in the project root:

   # Ollama Configuration (Local)
   OLLAMA_BASE_URL=http://host.docker.internal:11434
   OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest
   OLLAMA_EMBEDDING_DIMENSIONS=768
   
   # Optional: API Configuration
   TH0TH_API_PORT=3333
   NODE_ENV=production
   
   # Optional: Cloud Embedding Providers
   MISTRAL_API_KEY=
   RLM_LLM_API_KEY=
   RLM_LLM_MODEL=
   RLM_LLM_ENABLED=false
   

   The default configuration uses Ollama running on your host machine. Docker containers access it via host.docker.internal:11434.

3. Pull embedding models

   Before starting the containers, ensure your embedding model is available:

   # On your host machine
   ollama pull nomic-embed-text:latest
   # Or use the alternative model
   ollama pull bge-m3
   
4. Start the services

   # Start API only
   docker compose up -d api
   
   # Or start both API and MCP
   docker compose up -d
   
5. Verify deployment

   # Check health
   curl http://localhost:3333/health
   
   # Expected response:
   # {
   #   "status": "ok",
   #   "service": "th0th-tools-api",
   #   "version": "1.0.0",
   #   "timestamp": "2026-03-09T..."
   # }
   

Docker Compose Services

The docker-compose.yml defines two services:

API Service

api:
  build:
    context: .
    target: api
  container_name: th0th-api
  restart: unless-stopped
  ports:
    - "${TH0TH_API_PORT:-3333}:3333"
  volumes:
    - th0th-data:/data
  environment:
    - NODE_ENV=production
    - TH0TH_API_PORT=3333
    - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
  healthcheck:
    test: ["CMD", "curl", "-sf", "http://localhost:3333/health"]
    interval: 30s
    timeout: 3s
    start_period: 40s
    retries: 3

Key features:

• Exposes port 3333 (configurable via TH0TH_API_PORT)
• Persistent data stored in Docker volume th0th-data
• Automatic health checks every 30 seconds
• Restarts automatically unless manually stopped

MCP Service

mcp:
  build:
    context: .
    target: mcp
  container_name: th0th-mcp
  stdin_open: true
  environment:
    - NODE_ENV=production
    - TH0TH_API_URL=http://api:3333
  depends_on:
    api:
      condition: service_healthy

Key features:

• Stdio transport for MCP protocol
• Depends on healthy API service
• Connects to API via Docker internal network

Deployment from Source

For development or custom deployments:

1. Install dependencies

   bun install
   

   th0th uses Bun as its runtime. Install from bun.sh if needed.

2. Run the setup script

   ./scripts/setup-local-first.sh
   

   This script will:

   • Install/start Ollama if needed
   • Pull the embedding model (bge-m3 by default)
   • Create ~/.config/th0th/config.json
   • Create a .env file with defaults
3. Build the project

   bun run build
   
4. Start the API

   # Development mode (with hot reload)
   bun run dev:api
   
   # Production mode
   bun run start:api
   

Environment Variables Reference

Core Configuration

Variable	Default	Description
TH0TH_API_PORT	3333	API server port
NODE_ENV	production	Runtime environment
LOG_LEVEL	info	Logging verbosity
ENABLE_METRICS	false	Enable metrics collection

Embedding Providers

Ollama (Default)

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest
OLLAMA_EMBEDDING_DIMENSIONS=768

Database Paths

Variable	Default	Description
VECTOR_DB_PATH	./data/chroma	Vector database location
CACHE_DB_PATH	./data/cache.db	Cache database
KEYWORD_DB_PATH	./data/keyword.db	Keyword search index
EMBEDDING_CACHE_DB_PATH	./data/embedding-cache.db	Embedding cache

Cache Configuration

Variable	Default	Description
L1_CACHE_MAX_SIZE	104857600	L1 cache max size (100MB)
L1_CACHE_TTL	300	L1 TTL in seconds (5 min)
L2_CACHE_MAX_SIZE	524288000	L2 cache max size (500MB)
L2_CACHE_TTL	3600	L2 TTL in seconds (1 hour)

Production Considerations

Resource Requirements

Minimum Requirements

• CPU: 2 cores
• Memory: 4GB RAM (8GB recommended with Ollama)
• Storage: 10GB for databases and models
• Network: Port 3333 accessible

Data Persistence

When using Docker, ensure the th0th-data volume is backed up regularly. All indexed projects, memories, and caches are stored here.

Inspect the volume location:

docker volume inspect th0th-data

Backup the volume:

# Create a backup
docker run --rm -v th0th-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/th0th-data-backup.tar.gz /data

# Restore from backup
docker run --rm -v th0th-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/th0th-data-backup.tar.gz -C /

Scaling Considerations

1. Ollama Server: For high-load deployments, run Ollama on a dedicated machine with GPU support
2. API Instances: The API is stateless and can be load-balanced across multiple instances
3. Data Volume: Use network-attached storage (NFS, EBS) for shared data access

Security

The current version does not include built-in authentication. Deploy behind a reverse proxy (nginx, Traefik) with authentication for production use.

Example nginx configuration:

server {
  listen 80;
  server_name th0th.example.com;

  location / {
    proxy_pass http://localhost:3333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # Optional: Basic auth
    auth_basic "th0th API";
    auth_basic_user_file /etc/nginx/.htpasswd;
  }
}

Container Management

View Logs

# Follow all logs
docker compose logs -f

# API logs only
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Restart Services

# Restart all
docker compose restart

# Restart API only
docker compose restart api

Update to Latest Version

# Pull latest code
git pull origin main

# Rebuild containers
docker compose build

# Restart with new images
docker compose up -d

Clean Up

# Stop and remove containers
docker compose down

# Remove containers and volumes (DELETES ALL DATA)
docker compose down -v

Next Steps

Monitoring

Set up health checks and monitoring

Troubleshooting

Common issues and solutions