Quickstart (Self-Hosted)

Overview

You can start the self-hosted sovseal service—which bundles the Hono REST API, Postgres database, and browser dashboard—with a single command.

Choose between the Browser-first (Setup Wizard) or the Agent-first (CLI Bootstrap) path depending on your workflow.

Prerequisites

Docker and Docker Compose installed.
Outbound access to internet (for LLM provider API queries).
Local ports 8888 (API) and 3000 (Dashboard) must be free.

Option A: Browser-First Setup (Wizard)

Recommended for teams and developers who prefer using a GUI setup helper.

Step 1: Start the Containers

Navigate to your server directory and boot:

cd server
make up

This boots the API server, pgvector database, runs migrations, and opens listening ports.

Step 2: Open Setup Wizard

Open your browser and navigate to:

http://localhost:3000/setup

Step 3: Run Setup Wizard Steps

Create Admin Account: Enter your name, admin email, and password. Account creation shuts down after the first registration.
Verify Configuration: Review the read-only list of effective environmental settings (LLM and Embedder models).
Generate API Key: Create your first sov_live_ token. Copy the secret key immediately—the database only stores the prefix and a bcrypt hash.
Test the Configuration: Click "Run Test" in the browser. The wizard executes a test store_memory write. Success redirects you to the requests dashboard at http://localhost:3000/dashboard.

Option B: Agent-First Setup (Command Line)

Recommended for headless servers, automation scripts, and developers.

Step 1: Configure Credentials

Make sure you have exported your API credentials in server/.env:

export OPENAI_API_KEY="your-api-key"

Step 2: Bootstrap Server

Run the bootstrap command:

cd server
make bootstrap

This spins up the containers and automatically creates the admin account using defaults.

Customizing Bootstrap Credentials

You can override default bootstrap parameters:

make bootstrap [email protected] PASSWORD='StrongPassword123' NAME='DevAdmin'

The console will print the generated API Key once. Copy it immediately. You can now login at http://localhost:3000 without running the setup wizard.

Testing Your First Key

Verify the endpoints are responding correctly using curl:

curl -i -X POST http://localhost:8888/v3/memories/add/ \
  -H "Authorization: Bearer <your-generated-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer dark mode in development"}
    ],
    "user_id": "alex-test"
  }'

You should receive a 202 Accepted status with a pending processing token.

Quickstart (Self-Hosted)

On this page