Sybil-2/server/README.md

Sybil Server

Backend API for:

• LLM multiplexer (OpenAI Responses / Anthropic / xAI Chat Completions-compatible Grok / Gemini / Hermes Agent)
• Personal chat database (chats/messages + LLM call log)

Stack

• Node.js + TypeScript
• Fastify (HTTP)
• Prisma + SQLite (dev)

Quick start

cp .env.example .env
npm run dev

Migrations are applied automatically on server startup (prisma migrate deploy).

Open docs: http://localhost:8787/docs

API contract docs for clients:

• ../docs/api/rest.md
• ../docs/api/streaming-chat.md

Run Modes

• npm run dev: runs src/index.ts with tsx in watch mode (auto-restart on file changes). Use for local development.
• npm run start: runs compiled dist/index.js with Node.js (no watch mode). Use for production-like runs.

Both modes run startup checks (predev / prestart) and apply migrations at app boot.

Auth

Set ADMIN_TOKEN and send:

Authorization: Bearer <ADMIN_TOKEN>

If ADMIN_TOKEN is not set, the server runs in open mode (dev).

Env

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• XAI_API_KEY
• GEMINI_API_KEY
• HERMES_AGENT_API_BASE_URL (http://127.0.0.1:8642/v1 by default; include the /v1 suffix)
• HERMES_AGENT_API_KEY (enables the Hermes Agent provider; set to Hermes API_SERVER_KEY, or any non-empty value if that local server does not require auth)
• HERMES_AGENT_MODEL (optional fallback/override model id; defaults client-side to hermes-agent)
• EXA_API_KEY
• BRAVE_SEARCH_API_KEY (required when CHAT_WEB_SEARCH_ENGINE=brave)
• CHAT_WEB_SEARCH_ENGINE (exa by default; brave and searxng are also supported for chat tool calls only)
• SEARXNG_BASE_URL (required when CHAT_WEB_SEARCH_ENGINE=searxng; instance must allow format=json)
• CHAT_MAX_TOOL_ROUNDS (100 by default; maximum model/tool result cycles per chat completion)
• CHAT_CODEX_TOOL_ENABLED (false by default; enables the codex_exec chat tool for managed-tool providers)
• CHAT_CODEX_REMOTE_HOST (required when Codex tool is enabled; SSH host/IP or user@host)
• CHAT_CODEX_REMOTE_USER (optional SSH user when host does not include one)
• CHAT_CODEX_REMOTE_PORT (22 by default)
• CHAT_CODEX_REMOTE_WORKDIR (/workspace/sybil-codex by default; created and reused on the devbox)
• CHAT_CODEX_SSH_KEY_PATH (recommended: path to a read-only mounted private key)
• CHAT_CODEX_SSH_PRIVATE_KEY_B64 (optional fallback private key delivery)
• CHAT_CODEX_EXEC_TIMEOUT_MS (600000 by default)
• CHAT_SHELL_TOOL_ENABLED (false by default; enables the shell_exec chat tool for managed-tool providers on the same devbox)
• CHAT_SHELL_EXEC_TIMEOUT_MS (120000 by default)

API

• GET /health
• GET /v1/auth/session
• GET /v1/chats
• POST /v1/chats
• GET /v1/chats/:chatId
• POST /v1/chats/:chatId/messages
• POST /v1/chat-completions
• POST /v1/chat-completions/stream (SSE)
• GET /v1/searches
• POST /v1/searches
• GET /v1/searches/:searchId
• POST /v1/searches/:searchId/run
• POST /v1/searches/:searchId/run/stream (SSE)

Search runs now execute both Exa searchAndContents and Exa answer, storing:

• ranked search results (for result cards), and
• a top-level answer block + citations.

When chatId is provided to completion endpoints, you can send full conversation context. The server now stores only new non-assistant messages to avoid duplicate history rows.

POST /v1/chat-completions body example:

{
  "chatId": "<optional chat id>",
  "provider": "openai",
  "model": "gpt-4.1-mini",
  "messages": [
    {"role":"system","content":"You are helpful."},
    {"role":"user","content":"Say hi"}
  ],
  "temperature": 0.2,
  "maxTokens": 256
}

Next steps (planned)

• Better streaming protocol compatibility (OpenAI-style chunks + cancellation)
• Tool/function calling normalization
• User accounts + per-device API keys
• Postgres support + migrations for prod
• Attachments + embeddings + semantic search

Persistent Pi Agent

Configure the backend with:

PI_AGENT_BASE_URL=http://pi-durable:8788
PI_AGENT_API_KEY=<the Pi service's PI_API_KEY>

The base URL defaults to http://pi-durable:8788 and has no /v1 suffix. In Docker, attach Sybil's server container and Pi to the shared agents network so that pi-durable resolves privately. Supply the key through a private server environment file; it is never a VITE_* variable or browser setting. Keep the existing Sybil ADMIN_TOKEN authentication for clients.

The Agent tab uses /v1/agent, /v1/agent/messages, and /v1/agent/ws to proxy the same persistent Pi root conversation across devices. Pi remains the source of truth for messages and background replies. Sybil stores only the shared, monotonically increasing read cursor in SQLite through /v1/agent/read-state; its migration is applied automatically at startup. The bundled nginx configuration forwards WebSocket upgrades. See docs/api/rest.md and docs/api/streaming-chat.md at the repository root for the client contracts.