Thoth Setup Guide

Complete installation and configuration guide for Thoth Research Assistant.

Quick Start
Prerequisites
Installation
Setup Wizard
Manual Configuration
Verification
Troubleshooting

Quick Start

One-Command Installation

Linux/Mac:

curl -fsSL https://raw.githubusercontent.com/acertainKnight/project-thoth/main/install.sh | bash

Windows (WSL2):

# 1. Install WSL2 (PowerShell as Administrator, one-time)
wsl --install

# 2. Restart computer

# 3. Open Ubuntu terminal and run:
curl -fsSL https://raw.githubusercontent.com/acertainKnight/project-thoth/main/install.sh | bash

What happens:

Detects/installs Docker automatically
Runs interactive setup wizard
Installs thoth command to PATH
Optionally starts services immediately

Time: ~5 minutes

Prerequisites

Required

Docker installed and running
- Check: docker --version && docker compose version
- Install: docs.docker.com
- Important: The Docker daemon must be running (open Docker Desktop)
Obsidian (for plugin integration)
- Download: obsidian.md

System Requirements

OS: Linux, macOS, or Windows (WSL2)
RAM: 4GB minimum, 8GB recommended
Disk: 5GB free space
CPU: Multi-core recommended

Installation

Automated Install (Recommended)

The install script handles everything:

curl -fsSL https://raw.githubusercontent.com/acertainKnight/project-thoth/main/install.sh | bash

Options:

# Install specific version
bash install.sh --version 0.3.0-alpha.2

# Install latest alpha/pre-release
bash install.sh --alpha

# Install nightly build
bash install.sh --nightly

# List available versions
bash install.sh --list

What happens:

Verifies Docker is installed and running
Clones repository and builds setup container
Runs interactive setup wizard
Installs thoth CLI command to PATH
Optionally starts services immediately

Time: ~5 minutes (first run includes Docker image builds)

Setup Wizard

The interactive setup wizard guides you through configuration.

Wizard Flow

1. Welcome Screen

Introduction and prerequisites check
Navigation instructions

2. Vault Selection

Select your Obsidian vault directory
Validates vault path
Creates _thoth/ directory if needed

3. Letta Mode Selection

Choose how to run agent memory:

Option A: Letta Cloud (easiest)

Hosted service at app.letta.com
Free tier available
Just need API key
No local infrastructure

Option B: Self-Hosted (full control)

Local Docker container
Works offline
All data stays local
~500MB extra RAM

5. API Keys Configuration

Enter keys for LLM providers:

OpenAI (required — embeddings): platform.openai.com
OpenRouter (required — backend LLM): openrouter.ai/keys
Mistral AI (required — PDF OCR extraction): console.mistral.ai
Cohere (optional — dedicated reranking API): dashboard.cohere.com
Semantic Scholar (optional): semanticscholar.org/product/api

4. Model Selection

Choose default models:

Analysis: For research analysis (default: Claude 3.5 Sonnet via OpenRouter)
Generation: For content generation (default: Mistral Large)
Embeddings: For vector search (default: text-embedding-3-small)

7. Deployment Mode

Choose deployment architecture:

Local Mode: All-in-one container (default, 1 container)
Microservices Mode: Separate services (5 containers, advanced)

8. Optional Features

Enable additional capabilities:

RAG (semantic search): Requires embeddings
Hybrid Search: Combines semantic + keyword search (~35% better accuracy, enabled by default)
Reranking: LLM-based (zero-cost) or Cohere API (~20-30% improvement, enabled by default)
Discovery (automated paper finding): Requires browser automation
Advanced Citation Analysis: Requires external APIs
Contextual Enrichment: LLM per-chunk enrichment (disabled by default, expensive at indexing time)
Adaptive Routing: Query classification for optimized retrieval (disabled by default, experimental)

9. Configuration Review

Review all settings before installation:

Vault path
Letta mode
API keys (masked)
Models
Optional features

6. Installation

Wizard performs installation:

Creates settings.json
Generates Docker config
Builds/pulls images
Initializes database
Deploys Obsidian plugin

7. Completion

Success summary
Next steps
Quick start commands

Manual Configuration

If you prefer to configure manually instead of using the wizard:

1. Create Workspace & Copy Required Files

# Create directory structure
mkdir -p "$OBSIDIAN_VAULT_PATH/thoth/_thoth"/{templates,prompts,data/{output,knowledge,queries,agent},logs,cache,skills}
mkdir -p "$OBSIDIAN_VAULT_PATH/thoth/papers"/{pdfs,markdown}
mkdir -p "$OBSIDIAN_VAULT_PATH/thoth/notes"

# Copy settings
cp templates/thoth.settings.json "$OBSIDIAN_VAULT_PATH/thoth/_thoth/settings.json"

# Copy templates (required for PDF processing)
cp templates/obsidian_note.md "$OBSIDIAN_VAULT_PATH/thoth/_thoth/templates/"
cp templates/analysis_schema.json "$OBSIDIAN_VAULT_PATH/thoth/_thoth/templates/"
cp templates/analysis_schema.json "$OBSIDIAN_VAULT_PATH/thoth/_thoth/"

# Copy prompt templates (required for LLM analysis)
cp -r data/prompts/* "$OBSIDIAN_VAULT_PATH/thoth/_thoth/prompts/"

2. Edit Settings

{
  "api_keys": {
    "mistralKey": "your_key_here",
    "openrouterKey": "your_key_here"
  },
  "llm_config": {
    "default": {
      "model": "mistral/mistral-large-latest",
      "temperature": 0.7
    }
  },
  "memory": {
    "letta": {
      "mode": "self-hosted",
      "base_url": "http://localhost:8283"
    }
  }
}

3. Set Environment Variables

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
export API_MISTRAL_KEY="your_key_here"
export API_OPENROUTER_KEY="your_key_here"

4. Start Services

# Development mode (hot-reload enabled)
make dev

# Production mode (optimized)
make prod

Verification

Check Services

# Health check all services
make health

# Expected output:
# API Server (8000/8080): healthy
# MCP Server (8082): healthy
# Letta (8283): healthy
# PostgreSQL: healthy

Test API Connection

# Test API endpoint
curl http://localhost:8000/health | jq

# Test MCP server
curl http://localhost:8082/health | jq

# List MCP tools
curl -X POST http://localhost:8082/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

Test Document Processing

# Copy a test PDF to watch directory
cp test-paper.pdf "$OBSIDIAN_VAULT_PATH/thoth/papers/pdfs/"

# Check for generated note
ls "$OBSIDIAN_VAULT_PATH/thoth/notes/"

# View logs
tail -f "$OBSIDIAN_VAULT_PATH/thoth/_thoth/logs/thoth.log"

Verify Plugin

Open Obsidian
Settings → Community Plugins
Check "Thoth Research Assistant" is enabled
Click Thoth icon in left sidebar
Should open chat interface

Troubleshooting

Docker Issues

Port conflicts:

# Check what's using ports
lsof -i :8000
lsof -i :8082
lsof -i :8283

# Stop conflicting services or edit ports in settings.json

Permission errors:

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Out of disk space:

# Clean Docker system
docker system prune -a --volumes

# Check usage
docker system df

Vault Detection Issues

Error: "Could not detect vault"

# Verify OBSIDIAN_VAULT_PATH is set
echo $OBSIDIAN_VAULT_PATH

# Should output your vault path, not empty

# Set it if not set
export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

# Or add to ~/.bashrc for persistence
echo 'export OBSIDIAN_VAULT_PATH="/path/to/your/vault"' >> ~/.bashrc
source ~/.bashrc

Wrong vault detected:

# Explicitly set the correct vault
export OBSIDIAN_VAULT_PATH="/correct/path/to/vault"

# Verify
python -c "from thoth.config import get_vault_root; print(get_vault_root())"

Letta Connection Issues

Letta not responding:

# Check if Letta is running
docker ps | grep letta

# Start Letta if not running
docker compose -f docker-compose.letta.yml up -d

# Check Letta health
curl http://localhost:8283/v1/health

# View Letta logs
docker logs letta-server

Agents not created:

# Manually trigger agent initialization
python -c "
from thoth.services.agent_initialization_service import AgentInitializationService
service = AgentInitializationService()
service.initialize_all_agents()
"

# Verify agents exist
curl http://localhost:8283/v1/agents

Plugin Issues

Plugin not loading:

Check plugin directory exists:

ls "$OBSIDIAN_VAULT_PATH/.obsidian/plugins/thoth-obsidian/"

Verify files: main.js, manifest.json, styles.css
Disable "Restricted Mode" in Obsidian Settings
Enable "Thoth Research Assistant" in Community Plugins
Restart Obsidian

Connection failed:

Check backend is running: make health
Check plugin settings in Obsidian
Default: http://localhost:8000
For Docker: Use host IP or http://host.docker.internal:8000

Hot-Reload Issues

Settings changes not applying:

Verify dev mode (not prod): docker ps | grep dev
Check logs: make dev-logs
Manual trigger: make reload-settings
Verify file path: $OBSIDIAN_VAULT_PATH/thoth/_thoth/settings.json

Python Version Issues

Error: "Python 3.13 not supported"

Thoth requires Python 3.12 (3.13 has dependency incompatibilities):

# Check Python version
python3 --version

# Install Python 3.12 if needed (Ubuntu)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.12 python3.12-venv

# Use specific version
python3.12 -m venv .venv
source .venv/bin/activate

Next Steps

After successful installation:

Start services: thoth start (or make dev for development)
Check health: make health
Open Obsidian: Click Thoth icon to start chatting
Read usage guide: usage.md
Explore features: Try paper discovery, Q&A, citation analysis

Getting Help

Documentation: docs/ - All guides and references
GitHub Issues: Report a bug
Logs: make dev-logs or check thoth/_thoth/logs/
Health Check: make health to diagnose service issues

Setup Guide Version: 3.1 Last Updated: February 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Thoth Setup Guide

Table of Contents

Quick Start

One-Command Installation

Prerequisites

Required

Recommended

System Requirements

Installation

Automated Install (Recommended)

Setup Wizard

Wizard Flow

Manual Configuration

1. Create Workspace & Copy Required Files

2. Edit Settings

3. Set Environment Variables

4. Start Services

Verification

Check Services

Test API Connection

Test Document Processing

Verify Plugin

Troubleshooting

Docker Issues

Vault Detection Issues

Letta Connection Issues

Plugin Issues

Hot-Reload Issues

Python Version Issues

Next Steps

Getting Help

FilesExpand file tree

setup.md

Latest commit

History

setup.md

File metadata and controls

Thoth Setup Guide

Table of Contents

Quick Start

One-Command Installation

Prerequisites

Required

Recommended

System Requirements

Installation

Automated Install (Recommended)

Setup Wizard

Wizard Flow

Manual Configuration

1. Create Workspace & Copy Required Files

2. Edit Settings

3. Set Environment Variables

4. Start Services

Verification

Check Services

Test API Connection

Test Document Processing

Verify Plugin

Troubleshooting

Docker Issues

Vault Detection Issues

Letta Connection Issues

Plugin Issues

Hot-Reload Issues

Python Version Issues

Next Steps

Getting Help