134 lines
5.3 KiB
Markdown
134 lines
5.3 KiB
Markdown
# Sybil Server
|
|
|
|
Backend API for:
|
|
- LLM multiplexer (OpenAI Responses / Anthropic / xAI Chat Completions-compatible Grok / Gemini)
|
|
- Personal chat database (chats/messages + LLM call log)
|
|
|
|
## Stack
|
|
- Node.js + TypeScript
|
|
- Fastify (HTTP)
|
|
- Prisma + SQLite (dev)
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
npm run dev
|
|
```
|
|
|
|
Migrations are applied automatically on server startup (`prisma migrate deploy`).
|
|
|
|
Historical provider IDs are stored as strings so retiring an integration does not make saved chats or call logs unreadable. The API validates new requests against the supported provider list and returns `null` for unsupported saved provider selections. These columns remain SQLite `TEXT`; no data rewrite is required.
|
|
|
|
Inline Sybil Agent completions identify their response provider as `sybil-agent`. Release native clients that accept this response identity before deploying the server change; older clients that decode completion metadata with the selectable-provider enum cannot decode it. See the [streaming contract](../docs/api/streaming-chat.md).
|
|
|
|
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`
|
|
- `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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
## Sybil Agent
|
|
|
|
Configure the backend with:
|
|
|
|
```dotenv
|
|
SYBIL_AGENT_BASE_URL=http://sybil-agent:8788
|
|
SYBIL_AGENT_API_KEY=<the Sybil Agent service API key>
|
|
```
|
|
|
|
Use the same `SYBIL_AGENT_API_KEY` value configured on the agent service.
|
|
The base URL defaults to `http://sybil-agent:8788` and has no `/v1` suffix. In Docker,
|
|
attach Sybil's **server** container and Sybil Agent to the shared `agents` network so that
|
|
`sybil-agent` 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 Sybil Agent tab uses `/v1/agent`, `/v1/agent/messages`, and `/v1/agent/ws` to proxy the
|
|
same persistent root conversation across devices. Sybil Agent 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.
|