Installation

Installation Methods

th0th supports multiple installation methods to suit different environments and use cases.

Local + Ollama

100% offline, zero cost, perfect for development

Docker

Containerized deployment for production

From Source

Full control for customization and development

Local Setup with Ollama

The recommended approach for local development with 100% offline operation.

Prerequisites

Install Bun

th0th uses Bun as the package manager and runtime:

curl -fsSL https://bun.sh/install | bash

Verify installation:

bun --version  # Should be 1.2.0 or higher

Install Node.js

Ensure Node.js 18 or higher is installed:

node --version  # Should be v18.0.0 or higher

Install from nodejs.org if needed.

Install Git

Required for cloning the repository:

git --version

Automated Setup

The setup script handles everything automatically:

Clone Repository

git clone <repo-url>
cd th0th

Install Dependencies

bun install

This installs all workspace packages:

@th0th-ai/core - Core search and compression logic
@th0th-ai/tools-api - REST API server
@th0th-ai/mcp-client - MCP server for OpenCode/Claude
@th0th-ai/shared - Shared utilities and types

Run Setup Script

./scripts/setup-local-first.sh

The script performs these actions:

# Detects Ollama CLI or API
# Installs Ollama on Linux if needed
# Starts Ollama service if not running
# Supports WSL → Windows host scenarios

The script is idempotent - safe to run multiple times.

Build and Start

bun run build
bun run start:api

The API will be available at http://localhost:3333.

Manual Setup (Advanced)

If you prefer manual configuration:

Install Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &

Pull Embedding Model

ollama pull bge-m3

Alternative models:

ollama pull nomic-embed-text  # 768 dimensions, smaller

Create Configuration

Create ~/.config/th0th/config.json:

{
  "embedding": {
    "provider": "ollama",
    "model": "bge-m3",
    "baseURL": "http://localhost:11434",
    "dimensions": 768
  },
  "compression": {
    "enabled": true,
    "strategy": "code_structure",
    "targetRatio": 0.7
  },
  "cache": {
    "enabled": true,
    "l1MaxSizeMB": 100,
    "l2MaxSizeMB": 500,
    "defaultTTLSeconds": 3600
  },
  "dataDir": "~/.rlm",
  "logging": {
    "level": "info",
    "enableMetrics": false
  }
}

Create Environment File

Create .env in project root:

# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=bge-m3
OLLAMA_EMBEDDING_DIMENSIONS=1024

# Database Paths (relative to project root)
VECTOR_DB_PATH=./data/chroma
CACHE_DB_PATH=./data/cache.db
KEYWORD_DB_PATH=./data/keyword.db
EMBEDDING_CACHE_DB_PATH=./data/embedding-cache.db

# Logging
LOG_LEVEL=info
ENABLE_METRICS=false

# Cache Configuration
L1_CACHE_MAX_SIZE=104857600  # 100MB
L1_CACHE_TTL=300             # 5 minutes
L2_CACHE_MAX_SIZE=524288000  # 500MB
L2_CACHE_TTL=3600            # 1 hour

Create Data Directory

mkdir -p ~/.rlm
mkdir -p ./data

Docker Installation

Deploy th0th using Docker Compose for production environments.

Prerequisites

Docker 20.10 or higher
Docker Compose v2 or higher
Ollama running on host machine (or configure remote URL)

Quick Start

Clone Repository

git clone <repo-url>
cd th0th

Configure Environment

Create .env file or use environment variables:

# API Port
TH0TH_API_PORT=3333

# Ollama Configuration
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_EMBEDDING_MODEL=bge-m3
OLLAMA_EMBEDDING_DIMENSIONS=1024

# Optional: Mistral API
MISTRAL_API_KEY=your-api-key

Use host.docker.internal to access Ollama running on the host machine.

Start Services

docker compose up -d api

Verify Deployment

curl http://localhost:3333/health

Docker Compose Configuration

The docker-compose.yml defines two services:

services:
  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
      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:3333/health"]
      interval: 30s
      timeout: 3s
      start_period: 40s
      retries: 3

Using MCP via Docker

Integrate with OpenCode using Docker:

{
  "mcpServers": {
    "th0th": {
      "type": "local",
      "command": ["docker", "compose", "run", "--rm", "-i", "mcp"],
      "enabled": true
    }
  }
}

Ensure Docker Compose is in your PATH and accessible from your editor.

From Source Installation

For development or customization:

Clone and Install

git clone <repo-url>
cd th0th
bun install

Run Setup

./scripts/setup-local-first.sh

Build Packages

bun run build

This builds all workspace packages using Turbo:

packages/core
packages/shared
apps/tools-api
apps/mcp-client

Run Development Mode

bun run dev:api

Development Commands

Command	Description
`bun run build`	Build all packages
`bun run dev`	Development mode (all apps)
`bun run dev:api`	REST API with hot reload
`bun run dev:mcp`	MCP server with watch
`bun run start:api`	Start REST API (production)
`bun run start:mcp`	Start MCP server (production)
`bun run test`	Run tests
`bun run lint`	Lint code
`bun run type-check`	Type checking

Platform-Specific Notes

Windows + WSL

The setup script automatically detects and handles WSL scenarios:

Ollama on Windows Host

If Ollama is installed on Windows:

# WSL will automatically connect to Windows Ollama
# No additional configuration needed

Set OLLAMA_HOST (if needed)

export OLLAMA_HOST=http://$(hostname).local:11434

macOS

For macOS users:

Install Ollama

Download from ollama.com/download or:

brew install ollama

Start Ollama Service

ollama serve

Or use the macOS app to run in the background.

Linux

On Linux, the setup script handles everything:

# Auto-installs Ollama if not present
./scripts/setup-local-first.sh

Manual installation:

curl -fsSL https://ollama.com/install.sh | sh

Embedding Provider Options

Choose your embedding provider based on your needs:

Ollama (Default - Free)

# Already configured by setup script
# No additional steps needed

Models:

bge-m3 - 1024 dimensions, best quality
nomic-embed-text - 768 dimensions, smaller

Mistral API

npx @th0th-ai/mcp-client --config-init --mistral your-api-key

Models:

mistral-embed - General purpose
codestral-embed - Optimized for code (coming soon)

OpenAI API

npx @th0th-ai/mcp-client --config-init --openai your-api-key

Models:

text-embedding-3-small - Cost-effective
text-embedding-3-large - Higher quality

Configuration Management

View Current Configuration

npx @th0th-ai/mcp-client --config-show

View Config Paths

# Config file location
npx @th0th-ai/mcp-client --config-path

# Config directory
npx @th0th-ai/mcp-client --config-dir

Initialize Configuration

# Default (Ollama)
npx @th0th-ai/mcp-client --config-init

# With Mistral
npx @th0th-ai/mcp-client --config-init --mistral your-api-key

# With OpenAI
npx @th0th-ai/mcp-client --config-init --openai your-api-key

Switch Providers

# Switch to Mistral
npx @th0th-ai/mcp-client --config-init --mistral your-api-key

# Switch to Ollama with different model
npx @th0th-ai/mcp-client --config-init --ollama-model nomic-embed-text

Verification

Verify your installation:

Check Ollama

curl http://localhost:11434/api/tags

Should show available models including bge-m3.

Check API

curl http://localhost:3333/health

Should return health status.

Check Configuration

npx @th0th-ai/mcp-client --config-show

Should display your configuration.

View Swagger Docs

Navigate to http://localhost:3333/swagger to see interactive API documentation.

Directory Structure

After installation, your directory structure will look like:

th0th/
├── .env                         # Environment configuration
├── apps/
│   ├── mcp-client/             # MCP server
│   ├── tools-api/              # REST API
│   └── opencode-plugin/        # OpenCode plugin
├── packages/
│   ├── core/                   # Core logic
│   └── shared/                 # Utilities
├── scripts/
│   └── setup-local-first.sh    # Setup script
├── data/                        # Local databases (created on first run)
│   ├── chroma/                 # Vector store
│   ├── cache.db               # L2 cache
│   ├── keyword.db             # Keyword search
│   └── embedding-cache.db     # Embedding cache
└── docker-compose.yml          # Docker configuration

~/.config/th0th/
└── config.json                  # User configuration

~/.rlm/
└── (vector data and memories)   # Data directory

Next Steps

Quickstart

Index your first project and start searching

OpenCode Integration

Connect th0th to your AI assistant

Configuration

Configure embedding providers and advanced settings

Troubleshooting

Solve common installation issues

Troubleshooting

Ollama Not Found

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama manually
ollama serve

Port Already in Use

# Change port in .env
TH0TH_API_PORT=3334

# Or specify at runtime
PORT=3334 bun run start:api

Permission Denied

# Make setup script executable
chmod +x scripts/setup-local-first.sh

# Fix data directory permissions
mkdir -p ~/.rlm
chmod 755 ~/.rlm

Model Not Found

# Pull the embedding model
ollama pull bge-m3

# Verify it's available
ollama list

For more help, see the Troubleshooting guide.

Get Started

Integration

Core Concepts

Configuration

Operations

Documentation Index

​Installation Methods

Local + Ollama

Docker

From Source

​Local Setup with Ollama

​Prerequisites

​Automated Setup

​Manual Setup (Advanced)

​Docker Installation

​Prerequisites

​Quick Start

​Docker Compose Configuration

​Using MCP via Docker

​From Source Installation

​Development Commands

​Platform-Specific Notes

​Windows + WSL

​macOS

​Linux

​Embedding Provider Options

​Ollama (Default - Free)

​Mistral API

​OpenAI API

​Configuration Management

​View Current Configuration

​View Config Paths

​Initialize Configuration

​Switch Providers

​Verification

​Directory Structure

​Next Steps

Quickstart

OpenCode Integration

Configuration

Troubleshooting

​Troubleshooting

​Ollama Not Found

​Port Already in Use

​Permission Denied

​Model Not Found

Installation Methods

Local Setup with Ollama

Prerequisites

Automated Setup

Manual Setup (Advanced)

Docker Installation

Prerequisites

Quick Start

Docker Compose Configuration

Using MCP via Docker

From Source Installation

Development Commands

Platform-Specific Notes

Windows + WSL

macOS

Linux

Embedding Provider Options

Ollama (Default - Free)

Mistral API

OpenAI API

Configuration Management

View Current Configuration

View Config Paths

Initialize Configuration

Switch Providers

Verification

Directory Structure

Next Steps

Troubleshooting

Ollama Not Found

Port Already in Use

Permission Denied

Model Not Found