Installation

This guide covers installing Sibyl for both local development and production use.

Prerequisites

Sibyl requires the following:

• Python 3.13+ - Core backend language
• Node.js 22+ - For the web frontend
• FalkorDB - Graph database (runs on port 6380)
• PostgreSQL - Relational storage for users and documents
• OpenAI API Key - For generating embeddings

Version Management

We recommend using proto for managing tool versions:

# Install proto
curl -fsSL https://moonrepo.dev/install/proto.sh | bash

# Proto will automatically use correct versions from .prototools

Quick Install

Using uv (Recommended)

The fastest way to install Sibyl for development:

# Clone the repository
git clone https://github.com/hyperb1iss/sibyl.git
cd sibyl

# Install Python dependencies
uv sync

# Install the CLI tool globally
uv tool install sibyl-cli

# Or install in development mode (editable)
moon run install-dev

Install Individual Components

# Install just the CLI
uv tool install sibyl-cli

# Install sibyl-core library
uv add sibyl-core

Infrastructure Setup

Start FalkorDB

Sibyl uses FalkorDB (a Redis-compatible graph database) on port 6380:

# Using Docker
docker run -d \
  --name falkordb \
  -p 6380:6379 \
  -v falkordb-data:/data \
  falkordb/falkordb:latest

# Or using moon
moon run docker-up

Port 6380 FalkorDB runs on port 6380 (not 6379) to avoid conflicts with a standard

Redis installation. :::

PostgreSQL Setup

PostgreSQL stores users, sessions, API keys, and crawled documents:

# Using Docker
docker run -d \
  --name sibyl-postgres \
  -e POSTGRES_USER=sibyl \
  -e POSTGRES_PASSWORD=sibyl \
  -e POSTGRES_DB=sibyl \
  -p 5432:5432 \
  postgres:16

# Run migrations
cd apps/api
uv run alembic upgrade head

Configuration

Environment Variables

Create a .env file in apps/api/:

cp apps/api/.env.example apps/api/.env

Edit the file with your configuration:

# Required
SIBYL_OPENAI_API_KEY=sk-...        # For embeddings
SIBYL_JWT_SECRET=your-secret-key   # For authentication

# FalkorDB
SIBYL_FALKORDB_HOST=localhost
SIBYL_FALKORDB_PORT=6380
SIBYL_FALKORDB_PASSWORD=conventions

# PostgreSQL
SIBYL_DATABASE_URL=postgresql+asyncpg://sibyl:sibyl@localhost:5432/sibyl

# Optional
SIBYL_LOG_LEVEL=INFO
SIBYL_EMBEDDING_MODEL=text-embedding-3-small
SIBYL_ANTHROPIC_API_KEY=...        # For LLM operations

Required Environment Variables

Variable	Description
SIBYL_OPENAI_API_KEY	OpenAI API key for generating embeddings
SIBYL_JWT_SECRET	Secret key for JWT token signing

Optional Environment Variables

Variable	Default	Description
SIBYL_FALKORDB_HOST	localhost	FalkorDB hostname
SIBYL_FALKORDB_PORT	6380	FalkorDB port
SIBYL_DATABASE_URL	-	PostgreSQL connection string
SIBYL_LOG_LEVEL	INFO	Logging level
SIBYL_EMBEDDING_MODEL	text-embedding-3-small	OpenAI embedding model
SIBYL_SERVER_URL	-	Public server URL (for OAuth callbacks)
SIBYL_FRONTEND_URL	-	Frontend URL (for redirects)

Running Sibyl

Development Mode

Start all services with a single command:

moon run dev

This starts:

• API server on port 3334
• Background worker for async jobs
• Web frontend on port 3337

Individual Services

# API server only
moon run dev-api

# Web frontend only
moon run dev-web

# Background worker
cd apps/api && uv run arq sibyl.jobs.WorkerSettings

Direct Commands

# Start the API server
cd apps/api
uv run sibyl-serve

# Start in stdio mode (for MCP subprocess)
uv run sibyl-serve -t stdio

Verify Installation

Check Server Health

curl http://localhost:3334/api/health

Check CLI

sibyl health
sibyl version

Access Web UI

Open http://localhost:3337 in your browser.

Ports Reference

Service	Port
API + MCP	3334
Web Frontend	3337
FalkorDB	6380
PostgreSQL	5432

Troubleshooting

FalkorDB Connection Failed

# Check if FalkorDB is running
docker ps | grep falkordb

# Check the port
redis-cli -p 6380 ping

Graph Corruption

If you encounter graph corruption errors:

# Nuclear option: delete the graph
redis-cli -p 6380
> GRAPH.DELETE <org-uuid>

Database Migration Errors

# Reset and re-run migrations
cd apps/api
uv run alembic downgrade base
uv run alembic upgrade head

OpenAI API Errors

Ensure your API key is set and has credits:

echo $SIBYL_OPENAI_API_KEY

Docker Deployment

[SCREENSHOT: Docker compose architecture diagram]

A production Docker Compose configuration is planned. For now, use the individual Docker commands above.

Next Steps

• Quick Start - 5-minute tutorial
• MCP Configuration - Configure Claude Code integration