Skip to content

Getting Started

Jump to bottom
hitchhiker edited this page Feb 3, 2026 · 1 revision

Getting Started with Fold

Get Fold running in minutes. Choose your path: Docker (recommended) or local development.

Prerequisites

For Docker Setup (Recommended)

  • Docker and Docker Compose installed
  • At least one LLM API key (Gemini free tier is recommended)
  • 2GB+ free disk space

For Local Development

  • Rust 1.75+ (install)
  • SQLite 3 (usually pre-installed)
  • Docker (for Qdrant only)
  • At least one LLM API key

Option 1: Docker Compose (Recommended)

Step 1: Clone the Repository

git clone https://github.com/Generation-One/fold.git
cd fold

Step 2: Create Your Environment File

# Copy the example
cp .env.example .env

# Edit .env with your settings
nano .env  # or use your favorite editor

Minimally, you need:

# Required
ADMIN_BOOTSTRAP_TOKEN=your-secret-admin-token-change-this

# LLM Provider (pick at least one)
GOOGLE_API_KEY=your-gemini-api-key     # Free tier available
# OPENROUTER_API_KEY=your-openrouter-key
# OPENAI_API_KEY=your-openai-key

# Optional: Auth Provider (skip for local dev)
# AUTH_PROVIDER_GOOGLE_TYPE=oidc
# AUTH_PROVIDER_GOOGLE_DISPLAY_NAME=Google
# ... etc (see Configuration section)

Getting API keys:

Step 3: Start Fold

docker-compose up -d
docker-compose logs -f fold    # View logs
curl http://localhost:8765/health  # Check health

Services start on:

  • Fold: http://localhost:8765
  • Qdrant: http://localhost:6333 (REST), http://localhost:6334 (gRPC)

Step 4: Create Admin User

# Bootstrap the first admin
curl -X POST http://localhost:8765/auth/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-secret-admin-token-from-.env",
    "provider": "google",  # or whichever you configured
    "subject": "admin@example.com"  # Email or ID from your provider
  }'

# Response: { "user_id": "user_123", "role": "admin", ... }

Step 5: Create an API Token

# Create an API token for API/MCP access
curl -X POST http://localhost:8765/me/tokens \
  -H "Authorization: Bearer $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api-token",
    "projects": []  # Empty = access all your projects
  }'

# Response includes: { "token": "fold_abc123...", ... }

Save this token—you'll need it for API calls and MCP setup.

Option 2: Local Development

For development or if you want to avoid Docker.

Step 1: Clone the Repository

git clone https://github.com/Generation-One/fold.git
cd fold/srv  # Navigate to the Rust server

Step 2: Create Environment File

cp .env.example .env
nano .env

Set at minimum:

ADMIN_BOOTSTRAP_TOKEN=your-secret-token
GOOGLE_API_KEY=your-gemini-key
DATABASE_PATH=./data/fold.db
QDRANT_URL=http://localhost:6334

Step 3: Start Qdrant (Docker)

# In one terminal, start just Qdrant
docker run -p 6334:6334 qdrant/qdrant

Step 4: Build and Run Fold

# In another terminal
cargo run

# Or with auto-reload (requires `cargo install cargo-watch`)
cargo watch -x run

Server runs at http://localhost:8765.

Step 5: Bootstrap Admin & Create Token

Same as Docker setup (Step 4-5 above).

Option 3: Web UI

A React-based web interface is available at fold-ui.

git clone https://github.com/Generation-One/fold-ui.git
cd fold-ui

# With Docker Compose
docker-compose up -d

# Or local development
npm install && npm run dev

Opens at http://localhost:5174

First Steps: Connect Your Git Repository

Step 1: Connect a GitHub Repo

Get a GitHub personal access token: https://github.com/settings/tokens

# Create a project first
curl -X POST http://localhost:8765/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "slug": "my-project",
    "description": "My awesome project"
  }'

# Response includes: { "id": "proj_abc123" }

Step 2: Connect a Repository

curl -X POST http://localhost:8765/projects/proj_abc123/repositories \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "owner": "your-username",
    "repo": "your-repo-name",
    "branch": "main",
    "access_token": "ghp_your_github_token",
    "history": {
      "enabled": true,
      "mode": "days",
      "value": 7  # Index last 7 days
    }
  }'

Fold will:

  1. Clone and index all files from that branch
  2. Generate semantic summaries for existing commits
  3. Register a webhook to auto-index future pushes

Step 3: Search Your Codebase

# Try a semantic search
curl -X POST http://localhost:8765/projects/proj_abc123/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do we handle authentication?",
    "limit": 5
  }'

You should get back related code files, commits, and any decisions/sessions about authentication.

Connecting Claude Code (Next Step)

Once Fold is running with your repos indexed, connect it to Claude Code for AI-assisted development.

Step 1: Get Your API Token

You already created one above. If not:

curl -X POST http://localhost:8765/me/tokens \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "projects": []}'

Step 2: Add Fold to Claude Code

Option A: Via CLI (recommended)

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

Option B: Manual Config

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "fold": {
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer fold_YOUR_TOKEN_HERE"
      }
    }
  }
}

Then restart Claude Code.

Step 3: Use Fold in Claude Code

Now you can ask Claude questions about your codebase:

Claude: Search for authentication patterns
→ Uses Fold MCP tools
→ Finds related code + decisions + sessions
→ Understands your architecture

Claude: Implement a user export feature
→ Searches Fold for existing export patterns
→ Gets your architectural decisions
→ Writes code matching your style

Verify Installation

Check that everything is working:

# Health check
curl http://localhost:8765/health
# Response: { "status": "healthy" }

# Check Qdrant connection
curl http://localhost:6333/health
# Response: { "status": "ok" }

# List projects (requires auth)
curl http://localhost:8765/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Troubleshooting

Port Already in Use

If 8765 is taken:

# Docker: Edit docker-compose.yml
# Change "8765:8765" to "9000:8765"

# Local: Edit .env
PORT=9000

Qdrant Connection Failed

# Make sure Qdrant is running
docker ps | grep qdrant

# If not, start it
docker run -p 6334:6334 qdrant/qdrant

Database Locked / SQLite Error

# Check if database file exists
ls -la data/fold.db

# If corrupted, backup and delete
mv data/fold.db data/fold.db.bak
# Fold will create a new database on next run

# Apply migrations manually
# (Usually happens automatically)

API Token Issues

# Verify your token works
curl http://localhost:8765/auth/me \
  -H "Authorization: Bearer fold_YOUR_TOKEN"

# If 401, token is invalid or expired
# Create a new one using the bootstrap admin

Next Steps

Clone this wiki locally