Skip to content

Configuration

Jump to bottom
hitchhiker edited this page Feb 9, 2026 · 10 revisions

Configuration Guide

Fold is configured entirely through environment variables, making it easy to deploy across different environments. This guide covers all configuration options.

Quick Start

Get Fold running in 5 minutes:

# 1. Create .env file
cat > .env << EOF
HOST=0.0.0.0
PORT=8765
DATABASE_PATH=./data/fold.db
QDRANT_URL=http://localhost:6333
GOOGLE_API_KEY=your-gemini-api-key
SESSION_SECRET=$(head -c 32 /dev/urandom | base64)
EOF

# 2. Start Qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant &

# 3. Run Fold
cargo run

Server starts on http://localhost:8765

.env File Format

Fold loads environment variables from a .env file in the server directory using dotenvy.

Values with spaces must be quoted:

# Correct
AUTH_PROVIDER_GITHUB_SCOPES="read:user user:email repo"

# Wrong -- causes a parse error and stops loading the rest of the file
AUTH_PROVIDER_GITHUB_SCOPES=read:user user:email repo

If dotenvy encounters a parse error, it stops processing the .env file at that line. Any variables defined after the bad line will not be loaded. The server logs an error on startup when this happens -- check the logs if providers or other settings are missing.

Server Configuration

Basic Settings

# Bind address
HOST=0.0.0.0                    # All interfaces (0.0.0.0) or localhost (127.0.0.1)
PORT=8765                       # Port number

# Public URL for OIDC callbacks and webhooks
PUBLIC_URL=https://fold.example.com

# Environment
RUST_LOG=fold=debug,tower_http=debug  # Logging level

Why they matter:

  • HOST=0.0.0.0 allows Docker containers to reach Fold
  • PUBLIC_URL must match your actual domain for OAuth callbacks
  • RUST_LOG controls debug output

Database Configuration

SQLite

# Database file location
DATABASE_PATH=./data/fold.db        # Development (relative path)
DATABASE_PATH=/var/lib/fold/fold.db # Production (absolute path)

# For network access (NFS, mounted volume)
DATABASE_PATH=/mnt/shared/fold.db

Storage expectations:

  • Empty database: ~1 MB
  • 10,000 memories: ~50 MB
  • 100,000 memories: ~500 MB

High availability:

  • SQLite isn't suitable for multiple concurrent writers
  • For Fold's read-heavy workload, use a shared network volume
  • Or use read replicas with proper database synchronization

Vector Store (Qdrant)

Configuration

# Qdrant server URL
QDRANT_URL=http://localhost:6333      # Local development
QDRANT_URL=http://qdrant:6333         # Docker network
QDRANT_URL=http://qdrant.example.com  # Remote instance

# API key (if Qdrant has auth enabled)
QDRANT_API_KEY=your-api-key           # Optional

Docker Compose Setup

qdrant:
  image: qdrant/qdrant:latest
  ports:
    - "6333:6333"   # REST API
    - "6334:6334"   # gRPC
  volumes:
    - qdrant-data:/qdrant/storage
  environment:
    QDRANT_API_KEY: your-api-key-here  # Optional
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:6333/health"]

Monitoring

# Health check
curl http://localhost:6333/health

# Collection info
curl http://localhost:6333/collections/fold_memories

# Performance stats
curl http://localhost:6333/collections/fold_memories/snapshots

Storage expectations:

  • 10,000 embeddings: ~30 MB
  • 100,000 embeddings: ~300 MB
  • Vector dimension: 768 (by default)

Fold Storage Configuration

Directory Structure

Manually created memories are stored in a fold/ directory at your project root:

fold/
├── a/
│   ├── b/
│   │   ├── aBcD123456789abc.md  (16-char SHA256 of repo path)
│   │   └── aC12def456789abcd.md
├── 9/
│   └── a/
│       └── 9a8b7c6d5e4f3g2h.md

Key points:

  • fold/ contains markdown files committed to your repository or source storage
  • Hash is based on normalised repo path (machine-independent)
  • Can be rebuilt from database at any time
  • Committed to your repo

Embeddings Configuration

Provider and Model

# Which embedding service to use
EMBEDDING_PROVIDER=gemini        # or: openai

# Model identifier
EMBEDDING_MODEL=gemini-embedding-001    # Gemini (default)
# EMBEDDING_MODEL=text-embedding-3-small  # OpenAI

# Vector dimension (standardized across all providers for flexibility)
EMBEDDING_DIMENSION=768          # Universal standard: 768 dimensions for all providers

Gemini Embeddings

# Use Gemini for embeddings
EMBEDDING_PROVIDER=gemini
EMBEDDING_MODEL=gemini-embedding-001
GOOGLE_API_KEY=your-gemini-api-key

Characteristics:

  • Dimension: 768 (standardized)
  • Speed: Fast (~100 embeddings/second)
  • Quality: Good for code and technical docs
  • Cost: Generous free tier

OpenAI Embeddings

# Use OpenAI for embeddings (reduced to 768 dimensions for compatibility)
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=your-openai-api-key

Characteristics:

  • Dimension: 768 (reduced from native 1536 for provider flexibility)
  • Speed: Slightly slower than Gemini
  • Quality: Excellent semantic understanding (~95% of maximum precision)
  • Cost: Charged per API call
  • Note: Uses OpenAI's dimensions parameter to reduce from 1536 to 768

OpenRouter Embeddings

# Use OpenRouter for embeddings (OpenAI models via OpenRouter proxy)
OPENROUTER_API_KEY=your-openrouter-api-key

Or configure via the API:

curl -X POST http://localhost:8765/providers/embedding \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openrouter",
    "enabled": true,
    "priority": 50,
    "api_key": "sk-or-...",
    "config": { "model": "openai/text-embedding-3-small" }
  }'

Characteristics:

  • Dimension: 768 (reduced from native 1536 via dimensions parameter)
  • Model: openai/text-embedding-3-small (default)
  • Quality: Same as OpenAI (routes to the same underlying model)
  • Cost: Pay-per-use via OpenRouter billing
  • Useful when you already have an OpenRouter API key and want a single key for both LLM and embeddings

Ollama Embeddings (Local)

# Use Ollama for embeddings (local/self-hosted)
OLLAMA_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_PRIORITY=1

Setup:

# 1. Install Ollama
# Download from https://ollama.ai or use Docker
docker run -d -p 11434:11434 ollama/ollama

# 2. Pull an embedding model
docker exec <container-id> ollama pull nomic-embed-text

# 3. Verify it's running
curl http://localhost:11434/api/embeddings -X POST \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic-embed-text", "prompt": "test"}'

Supported models (all standardized to 768 dimensions):

Model Native Dims Standardized Speed Quality Best For
nomic-embed-text 768 768 Fast Good Recommended - balanced quality/speed
all-minilm 384 768 Very Fast Good Lightweight, quick indexing
all-mpnet-base-v2 768 768 Fast Very Good High-quality semantic matching
bge-large 1024 768 Medium Excellent High-quality semantic matching
mxbai-embed-large 1024 768 Medium Excellent Alternative high-quality model

Characteristics:

  • Dimension: 768 (standardized across all models for consistency)
  • Speed: Very fast (sub-millisecond local inference)
  • Quality: Good to excellent depending on model
  • Cost: Zero (fully open source, runs locally)
  • Privacy: All data stays local
  • Requires: Ollama server running (http://localhost:11434 by default)
  • Benefit: Provider flexibility - can switch between Ollama, Gemini, and OpenAI without re-indexing

Configuration options:

# Model selection (default: nomic-embed-text)
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_EMBEDDING_MODEL=all-minilm              # Lightweight variant
OLLAMA_EMBEDDING_MODEL=all-mpnet-base-v2       # High quality
OLLAMA_EMBEDDING_MODEL=bge-large               # Maximum precision

# Server location
OLLAMA_URL=http://localhost:11434              # Local development
OLLAMA_URL=http://ollama:11434                 # Docker network
OLLAMA_URL=http://ollama.example.com           # Remote instance

# Priority in provider fallback
OLLAMA_PRIORITY=1                              # Try Ollama first (recommended)
OLLAMA_PRIORITY=3                              # Use as fallback

Multi-provider with Ollama fallback:

# Prefer Ollama, fall back to Gemini if unavailable
OLLAMA_URL=http://localhost:11434
OLLAMA_PRIORITY=1
GOOGLE_API_KEY=your-gemini-api-key             # Fallback provider

Why use Ollama:

  • Zero embedding costs compared to API-based providers
  • Private: all data stays on your infrastructure
  • Fast: local inference avoids network latency
  • Offline: works without internet connection
  • Flexible: swap models without code changes

Provider Standardization

All embedding providers are standardized to 768 dimensions for consistency and flexibility:

  • Gemini: Native 768-dimensional embeddings
  • OpenAI: Reduced from 1536 to 768 dimensions (~95% of maximum semantic precision)
  • OpenRouter: Same as OpenAI (routes to OpenAI embedding models, reduced to 768)
  • Ollama: All models standardized to 768 dimensions

Benefits:

  • Seamless provider switching without re-indexing existing memories
  • Swap providers at runtime (e.g., local Ollama during development, cloud Gemini in production)
  • Consistent vector space across all providers

Trade-offs:

  • OpenAI at 768-dim has slightly lower semantic precision than native 1536-dim (~5% loss)
  • Other providers have negligible impact - they use 768 or are mapped to it

Search-Time Provider Priority

You can use different providers for indexing vs search queries:

  • Indexing: Use high-quality providers (e.g., OpenAI) for best semantic representation
  • Search: Use fast local providers (e.g., Ollama) for quick query embedding generation

Configuration via API:

# Create provider with search_priority
curl -X POST http://localhost:8765/providers/embedding \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ollama",
    "priority": 2,
    "search_priority": 1,
    "config": {
      "endpoint": "http://localhost:11434",
      "model": "nomic-embed-text"
    }
  }'

# Update existing provider with search_priority
curl -X PUT http://localhost:8765/providers/embedding/{id} \
  -H "Content-Type: application/json" \
  -d '{"search_priority": 1}'

How it works:

  • priority: Used for indexing (lower = tried first)
  • search_priority: Used for search queries (lower = tried first)
  • If search_priority is not set, falls back to priority

Example setup:

Provider priority search_priority Use Case
OpenAI 1 3 Best quality for indexing
Gemini 2 2 Good fallback
OpenRouter 3 3 Alternative to direct OpenAI
Ollama 4 1 Fast local search

This configuration indexes with OpenAI (highest quality) but searches with Ollama (fastest).

LLM Provider Configuration

Fold supports multiple LLM providers with automatic fallback.

Primary Provider

# Use Gemini
GOOGLE_API_KEY=your-gemini-api-key

# OR use Anthropic (Claude)
ANTHROPIC_API_KEY=your-anthropic-api-key

# OR use OpenAI
OPENAI_API_KEY=your-openai-api-key

# OR use OpenRouter (proxy for multiple models)
OPENROUTER_API_KEY=your-openrouter-api-key

At least one provider is required.

Fallback Chain

# Set multiple providers - they're tried in order:
GOOGLE_API_KEY=...        # Try Gemini first
ANTHROPIC_API_KEY=...     # Fallback to Claude
OPENAI_API_KEY=...        # Fallback to OpenAI
OPENROUTER_API_KEY=...    # Last resort

If Gemini fails, Fold automatically tries the next provider.

Configuration by Provider

Gemini

GOOGLE_API_KEY=AIza...
# Uses text-bison for summaries
# Free tier: 60 requests per minute

Anthropic (Claude)

ANTHROPIC_API_KEY=sk-ant-...
# Uses Claude for summaries and LLM tasks
# Good for technical analysis

OpenAI

OPENAI_API_KEY=sk-...
# Uses GPT-4 or GPT-3.5 for summaries
# More expensive than Gemini

OpenRouter

OPENROUTER_API_KEY=sk-...
# Access to multiple models
# Useful for load balancing

Memory Decay Configuration

ACT-R inspired memory strength decay.

# How long until memory strength halves
DECAY_HALF_LIFE_DAYS=30              # Default: 30 days

# Blend factor in search scoring
DECAY_STRENGTH_WEIGHT=0.3            # Default: 0.3
# 0.0 = pure semantic similarity
# 1.0 = pure memory strength
# 0.3 = 70% semantic, 30% strength (recommended)

Use Cases

Project Type half_life strength_weight Rationale
Fast-moving startup 7 0.4 Recent context matters more
Stable codebase 30 0.3 Balanced approach
Long-term project 90 0.2 Older decisions still relevant
Reference docs 365 0.1 Architectural decisions stay current

Example configurations:

# Fast-moving project (e.g., startup)
DECAY_HALF_LIFE_DAYS=7
DECAY_STRENGTH_WEIGHT=0.4

# Stable project (e.g., production app)
DECAY_HALF_LIFE_DAYS=30
DECAY_STRENGTH_WEIGHT=0.3

# Pure semantic search (disable decay)
DECAY_STRENGTH_WEIGHT=0.0

Authentication (OIDC)

Fold uses OpenID Connect for authentication. Configure at least one provider.

Google

AUTH_PROVIDER_GOOGLE_TYPE=oidc
AUTH_PROVIDER_GOOGLE_DISPLAY_NAME=Google
AUTH_PROVIDER_GOOGLE_ISSUER=https://accounts.google.com
AUTH_PROVIDER_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
AUTH_PROVIDER_GOOGLE_CLIENT_SECRET=your-client-secret
AUTH_PROVIDER_GOOGLE_SCOPE=openid email profile

Setup:

  1. Go to Google Cloud Console
  2. Create OAuth 2.0 credential (Web application)
  3. Authorized redirect URIs: https://fold.example.com/auth/callback/google
  4. Copy Client ID and Secret

GitHub (GitHub App)

AUTH_PROVIDER_GITHUB_TYPE=github
AUTH_PROVIDER_GITHUB_CLIENT_ID=Iv23lixxxxxxxxxx
AUTH_PROVIDER_GITHUB_CLIENT_SECRET=your-github-secret
AUTH_PROVIDER_GITHUB_APP_SLUG=my-fold-app
AUTH_PROVIDER_GITHUB_ENABLED=true

Setup:

  1. Go to GitHub Settings > Developer settings > GitHub Apps > New GitHub App
  2. Set the Callback URL to https://fold.example.com/auth/callback/github (must point to the backend, not the frontend dev server)
  3. Tick Expire user authorization tokens and Request user authorization (OAuth) during installation
  4. Under Permissions, grant Contents (read), Metadata (read), and Email addresses (read)
  5. Copy the Client ID and generate a Client Secret
  6. Note the App slug from the URL (e.g. my-fold-app from github.com/apps/my-fold-app)

Permissions are configured on the GitHub App itself, not via OAuth scopes. The APP_SLUG is used to build the installation URL that gives users the "All repositories" / "Only select repositories" picker.

GitHub App user tokens expire after 8 hours and are automatically refreshed using a stored refresh token.

See Connected Accounts for how users link their GitHub identity to Fold for automatic token management.

Custom OIDC Provider

AUTH_PROVIDER_CUSTOM_TYPE=oidc
AUTH_PROVIDER_CUSTOM_DISPLAY_NAME=Corporate SSO
AUTH_PROVIDER_CUSTOM_ISSUER=https://auth.mycompany.com
AUTH_PROVIDER_CUSTOM_CLIENT_ID=fold-app-id
AUTH_PROVIDER_CUSTOM_CLIENT_SECRET=fold-app-secret
AUTH_PROVIDER_CUSTOM_SCOPE=openid email profile

Session Configuration

# Session secret (generate random 32+ bytes)
SESSION_SECRET=your-random-32-byte-secret

# Session timeout (hours)
SESSION_TIMEOUT_HOURS=24

Generate secure secret:

head -c 32 /dev/urandom | base64

Git Integration

GitHub Projects

When creating a project with provider: github:

  1. Configure the project with remote_owner, remote_repo, and access_token
  2. Set up a webhook in GitHub pointing to https://fold.example.com/webhooks/github/{project_id}
  3. Fold automatically indexes changed files when pushes occur

Webhook secret verification:

# Fold automatically verifies webhook signatures
# The project's webhook_secret is used for verification
WEBHOOK_VERIFY_SIGNATURES=true  # Default: true

GitLab Projects

Similar to GitHub:

  1. Create project with provider: gitlab
  2. Set up a GitLab webhook
  3. Fold indexes changed files

Local Projects

For local development (provider: local):

# Index local project (doesn't require webhooks)
# Use API: POST /api/projects/{slug}/sync

Project Configuration

Each project has optional fold/project.toml:

[project]
id = "proj_abc123"
slug = "my-app"
name = "My Application"
created_at = "2026-02-03T10:00:00Z"

[indexing]
# Include patterns (glob) - see "Supported Languages" below for full list
include = [
  "**/*.ts",
  "**/*.tsx",
  "**/*.js",
  "**/*.jsx",
  "**/*.py",
  "**/*.rs",
  "**/*.go",
  "**/*.java",
  "**/*.cs",
  "**/*.md"
]

# Exclude patterns (glob)
exclude = [
  "node_modules/**",
  "dist/**",
  ".git/**",
  "fold/**",
  "*.test.ts",
  "*.spec.ts"
]

# Skip files larger than this (KB)
max_file_size = 100

[embedding]
provider = "gemini"
model = "gemini-embedding-001"
dimension = 768

[decay]
half_life_days = 30
strength_weight = 0.3

Supported Languages and File Types

Fold supports semantic chunking (AST-based) for code files and intelligent chunking for documentation and data files.

Languages with AST-based Semantic Chunking:

Category Languages Extensions
Systems Rust, C, C++, Zig .rs, .c, .h, .cpp, .cc, .cxx, .hpp, .hxx, .zig
JVM Java, Kotlin, Scala .java, .kt, .kts, .scala, .sc
.NET C#, F# .cs, .fs
Scripting Python, Ruby, PHP, Lua, Elixir, Bash .py, .pyi, .rb, .php, .lua, .ex, .exs, .sh, .bash
Web JavaScript, TypeScript, HTML, CSS .js, .mjs, .jsx, .ts, .mts, .tsx, .html, .htm, .css, .scss, .sass
Mobile Swift, Objective-C .swift, .m, .mm
Other Go, Dart, Clojure .go, .dart, .clj, .cljs

Data and Config Formats:

Format Extensions
JSON .json, .jsonc
YAML .yaml, .yml
TOML .toml
XML .xml
SQL .sql
GraphQL .graphql, .gql
Protobuf .proto
Terraform .tf, .tfvars, .hcl

Documentation:

Format Extensions
Markdown .md, .mdx
reStructuredText .rst
Plain text .txt, .log

Other Indexed Files:

  • Config files: .env, .ini, .cfg, .conf, .properties
  • Data files: .csv, .tsv
  • Build files: Makefile, Dockerfile, Cargo.toml, package.json

Default Index Patterns

If no patterns are specified, Fold uses these defaults:

include = [
  # Systems
  "**/*.rs", "**/*.c", "**/*.h", "**/*.cpp", "**/*.hpp", "**/*.zig",
  # JVM
  "**/*.java", "**/*.kt", "**/*.kts", "**/*.scala",
  # .NET
  "**/*.cs", "**/*.fs",
  # Scripting
  "**/*.py", "**/*.rb", "**/*.php", "**/*.lua", "**/*.ex", "**/*.exs", "**/*.sh",
  # Web
  "**/*.js", "**/*.mjs", "**/*.jsx", "**/*.ts", "**/*.mts", "**/*.tsx",
  "**/*.html", "**/*.css", "**/*.scss", "**/*.vue", "**/*.svelte",
  # Mobile
  "**/*.swift", "**/*.m",
  # Other
  "**/*.go", "**/*.dart", "**/*.clj",
  # Config/Data
  "**/*.json", "**/*.toml", "**/*.yaml", "**/*.yml",
  # Documentation
  "**/*.md", "**/*.mdx", "**/*.rst", "**/*.txt",
  # Build/Config files
  "**/*.xml", "**/*.sql", "**/*.graphql", "**/*.proto", "**/*.tf",
  "**/Dockerfile", "**/Makefile", "**/Cargo.toml", "**/package.json"
]

exclude = [
  "**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**",
  "**/__pycache__/**", "**/bin/**", "**/obj/**", "**/target/**",
  "**/vendor/**", "**/*.min.js", "**/*.min.css", "**/*.generated.*",
  "**/*.g.cs", "**/*.designer.cs", "fold/**", ".fold/**"
]

API Token Management

Create API Token

In Fold web UI:

Settings → API Tokens → Create Token

Configure:

  • Name: Descriptive name (e.g., "Claude Code")
  • Projects: Which projects this token can access
  • Scopes: (typically all scopes enabled)

Use with Claude Code

claude mcp add -t http -s user fold http://localhost:8765/mcp \
  --header "Authorization: Bearer fold_YOUR_TOKEN_HERE"

Revoke Token

Settings → API Tokens → Delete

Production Deployment

Environment Template

# Server
HOST=0.0.0.0
PORT=8765
PUBLIC_URL=https://fold.example.com
RUST_LOG=fold=info

# Database
DATABASE_PATH=/var/lib/fold/fold.db

# Vector Store
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=secure-api-key

# Embeddings (choose one provider)
# Option 1: Ollama (local, recommended for zero cost)
OLLAMA_URL=http://ollama:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_PRIORITY=1

# Option 2: Gemini (cloud, with Ollama fallback)
# GOOGLE_API_KEY=...
# EMBEDDING_DIMENSION=768

# Option 3: OpenAI (cloud)
# OPENAI_API_KEY=...
# EMBEDDING_DIMENSION=1536

# LLM
GOOGLE_API_KEY=...
ANTHROPIC_API_KEY=...  (fallback)

# Memory Decay
DECAY_HALF_LIFE_DAYS=30
DECAY_STRENGTH_WEIGHT=0.3

# Auth
AUTH_PROVIDER_GOOGLE_CLIENT_ID=...
AUTH_PROVIDER_GOOGLE_CLIENT_SECRET=...
SESSION_SECRET=... (32+ bytes)

# Webhook
PUBLIC_URL=https://fold.example.com

Docker Compose

version: '3.8'

services:
  fold:
    image: fold:latest
    ports:
      - "8765:8765"
    environment:
      DATABASE_PATH: /data/fold.db
      QDRANT_URL: http://qdrant:6333
      GOOGLE_API_KEY: ${GOOGLE_API_KEY}
      PUBLIC_URL: https://fold.example.com
    volumes:
      - fold-data:/data
      - fold-repository:/fold

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant-data:/qdrant/storage

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    environment:
      OLLAMA_HOST: 0.0.0.0:11434
    # Initialize with model (optional)
    command: serve

volumes:
  fold-data:
  qdrant-data:
  ollama-data:
  fold-repository:

Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: fold-config
data:
  QDRANT_URL: "http://qdrant:6333"
  PUBLIC_URL: "https://fold.example.com"
  RUST_LOG: "fold=info"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fold
spec:
  replicas: 2
  selector:
    matchLabels:
      app: fold
  template:
    metadata:
      labels:
        app: fold
    spec:
      containers:
      - name: fold
        image: fold:latest
        ports:
        - containerPort: 8765
        envFrom:
        - configMapRef:
            name: fold-config
        env:
        - name: DATABASE_PATH
          value: /data/fold.db
        - name: GOOGLE_API_KEY
          valueFrom:
            secretKeyRef:
              name: fold-secrets
              key: google-api-key
        volumeMounts:
        - name: fold-data
          mountPath: /data
        - name: fold-repo
          mountPath: /fold
        livenessProbe:
          httpGet:
            path: /health
            port: 8765
          initialDelaySeconds: 10
      volumes:
      - name: fold-data
        persistentVolumeClaim:
          claimName: fold-data-pvc
      - name: fold-repo
        persistentVolumeClaim:
          claimName: fold-repo-pvc

Troubleshooting

"Qdrant connection failed"

# Check if Qdrant is running
curl http://localhost:6333/health

# Restart Qdrant
docker-compose restart qdrant

# Check network connectivity
docker network ls
docker network inspect fold_default  # or your network name

"LLM provider unavailable"

# Verify API key is set
echo $GOOGLE_API_KEY

# Test connection
curl -H "Authorization: Bearer $GOOGLE_API_KEY" \
  https://generativelanguage.googleapis.com/v1/models/list

"Ollama connection failed"

# Check if Ollama is running
curl http://localhost:11434/api/embeddings -X POST \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic-embed-text", "prompt": "test"}'

# If it fails:
# 1. Start Ollama
docker run -d -p 11434:11434 ollama/ollama

# 2. Pull the embedding model
docker exec <container-id> ollama pull nomic-embed-text

# 3. Verify connection again
curl http://localhost:11434/api/tags

# If using remote Ollama:
# Verify OLLAMA_URL matches the server location
# Make sure the server is accessible from Fold's network

"Ollama model not found"

# List available models
curl http://localhost:11434/api/tags

# Pull missing model
docker exec <container-id> ollama pull nomic-embed-text

# For other models:
docker exec <container-id> ollama pull all-minilm
docker exec <container-id> ollama pull all-mpnet-base-v2
docker exec <container-id> ollama pull bge-large

"Memory not indexed"

Check:

  1. Repository is connected
  2. Files aren't in exclude patterns
  3. File size < max_file_size (100KB default)
  4. Job queue status: GET /status/jobs

"Permission denied" errors

# Check file/directory permissions
ls -la /var/lib/fold/fold.db
chmod 755 /var/lib/fold/

# Check Fold process user
ps aux | grep fold

Security Considerations

Database

# Restrict database file permissions
chmod 600 /var/lib/fold/fold.db

# Backup encryption
tar czf - fold.db | openssl enc -aes-256-cbc > backup.tar.gz.enc

Session Secrets

# Generate 32+ random bytes
openssl rand -base64 32
# Or: head -c 32 /dev/urandom | base64

API Tokens

# Never commit tokens to git
echo "fold_*.txt" >> .gitignore

# Rotate tokens regularly
# Revoke old tokens in Settings

HTTPS

# Always use HTTPS in production
PUBLIC_URL=https://fold.example.com  # NOT http://

# Use reverse proxy for SSL/TLS
# nginx, Caddy, or Let's Encrypt + Certbot

LLM API Keys

# Never commit API keys
# Use environment variables or secrets management

# Rotate keys regularly
# Use provider-specific API key management

Clone this wiki locally