Installation

This guide covers the main ways to run Sibyl:

• run the shell installer and start the local server UI
• install the Homebrew formula on systems where you already use Homebrew
• run a self-hosted Docker stack with sibyl docker ...
• work on the monorepo in development mode with moon run ...

Prerequisites

Sibyl requires the following for development:

• Python 3.13+ - Core backend language
• Node.js 24 - For the web frontend
• Docker - For local SurrealDB and optional dev services
• 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

Local Server

The recommended local install starts the API, web UI, and SurrealDB, then opens the setup UI when it is ready:

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh

Homebrew installs the CLI and daemon. Start the full local server UI with one command:

brew install hyperb1iss/tap/sibyl
sibyl up

Remote CLI

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --remote
sibyl init --remote https://sibyl.example.com
sibyl auth login
sibyl doctor

Docker Self-Host

sibyl up --no-browser

For lower-level compose management:

sibyl docker init
sibyl docker up
sibyl docker logs

Monorepo Development

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

# Bootstrap toolchain and dependencies
./setup-dev.sh              # macOS / Linux
pwsh -File .\setup-dev.ps1  # Windows (PowerShell 7+)

Or manually:

curl -fsSL https://moonrepo.dev/install/proto.sh | bash
proto use
proto install moon
uv sync --all-groups
pnpm install

# Optional: install repo-local CLI entrypoints into your user tool path
moon run cli:install-dev
moon run api:install-dev

Direct uv tool install commands are developer and CI escape hatches. User-facing installs should go through the shell installer, Homebrew, or Docker flow so the CLI and daemon stay paired.

Infrastructure Setup

Start Local SurrealDB

# Start the default local data service
moon run docker-up

For distributed or multi-process dev, opt into Redis explicitly:

docker compose --profile redis up -d surrealdb redis

Historical postgres.sql archive rehearsal now uses an explicitly managed external PostgreSQL database. The default compose file starts only SurrealDB, plus Redis when that profile is requested.

Configuration

Environment Variables

Create a .env file from the repo root example:

cp .env.example .env

Edit the file with your configuration:

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

# Recommended local runtime
SIBYL_STORE=surreal
SIBYL_COORDINATION_BACKEND=local
SIBYL_SURREAL_URL=ws://127.0.0.1:8000/rpc
SIBYL_SURREAL_USERNAME=root
SIBYL_SURREAL_PASSWORD=root

# 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_STORE	surreal	Active persistence runtime
SIBYL_COORDINATION_BACKEND	auto	local or redis coordination backend
SIBYL_SURREAL_URL	-	SurrealDB server URL
SIBYL_LOG_LEVEL	INFO	Logging level
SIBYL_EMBEDDING_MODEL	text-embedding-3-small	OpenAI embedding model
SIBYL_PUBLIC_URL	http://localhost:3337	Public base URL (OAuth callbacks, redirects)
SIBYL_SERVER_URL	derived	Override API base URL (defaults to public)
SIBYL_FRONTEND_URL	derived	Override frontend URL (defaults to public)
SIBYL_REDIS_HOST	127.0.0.1	Redis/Valkey host when coordination=redis
SIBYL_POSTGRES_HOST	localhost	Migration-only PostgreSQL host

Running Sibyl

Local Host Mode

The embedded daemon path is available when you want API-only local memory without the web UI:

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --daemon

Or run it manually:

sibyl init --local
sibyl serve
sibyl doctor

Use sibyl start/sibyl stop for a background daemon. To install a native user-service file without starting it automatically, run sibyl service install.

Development Mode

Start the recommended Surreal local-dev stack:

moon run dev

This starts:

• API server on port 3334
• Web frontend on port 3337
• In-process background jobs and schedules

The local FalkorDB/PostgreSQL dev fallback was retired after the v0.6.0 compatibility release. Use sibyld migrate import <archive> --source-type legacy-archive --target-mode surreal to move an exported archive into SurrealDB.

Individual Services

# API server only
moon run dev-api

# Web frontend only
moon run dev-web

# Background worker (only when SIBYL_COORDINATION_BACKEND=redis)
moon run api:worker

Direct Commands

# Start the API server
moon run api:serve

# Start in stdio mode (for MCP subprocess)
sibyld serve -t stdio

Verify Installation

Check Server Health

# If you installed the published CLI
sibyl doctor

# Basic health check
curl http://localhost:3334/api/health
sibyl health
sibyl version
sibyld --version

Access Web UI

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

Ports Reference

Service	Port
API + MCP	3334
Web Frontend	3337
SurrealDB	8000

Troubleshooting

SurrealDB Connection Failed

# Check if SurrealDB is running
docker ps | grep surreal

# Check the port
curl http://localhost:8000/health

Local Graph Reset

If a disposable local graph gets corrupted, stop Sibyl and remove the local SurrealDB data directory or reset the affected org namespace from SurrealQL.

REMOVE NAMESPACE org_<uuid_hex>;

Legacy Graph / Migration Errors

Use a retained archive file with sibyld migrate import <archive> --source-type legacy-archive --target-mode surreal. Only pass --restore-database-dump when rehearsing a historical postgres.sql payload against an explicitly managed PostgreSQL database, paired with --source-type legacy-archive --target-mode postgres-rehearsal.

OpenAI API Errors

Ensure your API key is set and has credits:

echo $SIBYL_OPENAI_API_KEY

Docker Deployment

The CLI writes a pinned compose bundle and generated secrets under ~/.sibyl/docker:

sibyl docker init --with-worker
sibyl docker up --pull
sibyl docker upgrade --tag 1.0.0-rc.1

Legacy Runtime Notes

Sibyl's current product surface centers on the knowledge graph, tasks, search, and source ingestion. If you are evaluating Sibyl today, you can ignore older experimental internal-runtime material.

Next Steps

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