Configuration

Configuration

Environment Variables

Copy .env.example to .env in the project root and edit as needed:

cp .env.example .env

Variable	Default	Description
SYNAPSE_DATA_DIR	backend/data (dev) / ~/.synapse/data (installed)	Where agents store files, memory, and state
OLLAMA_BASE_URL	http://127.0.0.1:11434	Local Ollama endpoint
SYNAPSE_BACKEND_PORT	8000	Backend API port
SYNAPSE_FRONTEND_PORT	3000	Frontend UI port
NEXT_PUBLIC_BACKEND_PORT	8000	Backend port exposed to the browser bundle (must match SYNAPSE_BACKEND_PORT; requires a frontend rebuild when changed)
BACKEND_URL	auto-derived	Backend URL as seen by the Next.js server — set this in Docker/remote deployments (e.g. http://synapse-backend:8000)
CORS_ORIGINS	http://localhost:3000	Allowed CORS origins (comma-separated)
DATABASE_URL	postgres://postgres:password@localhost:5432/synapse	Default database for the SQL Agent tool
SYNAPSE_PROFILING	false	Enable performance profiling

---

LLM Provider Setup

Switch providers globally in Settings → Model, or per-agent in the agent editor.

Ollama (Local)

No API key needed. Install Ollama and pull a model:

ollama pull mistral-nemo   # default
ollama pull llama3

Synapse auto-discovers available models from your Ollama instance.

Anthropic (Claude)

Set ANTHROPIC_API_KEY in .env:

ANTHROPIC_API_KEY=sk-ant-...

Supported models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3.7 Sonnet, and others.

OpenAI

OPENAI_API_KEY=sk-...

Supported models: GPT-4o, GPT-4 Turbo, o1, o3-mini, and others.

Google Gemini

GEMINI_API_KEY=...

Supported models: Gemini 1.5 Pro, Gemini 2.0 Flash, and others.

xAI (Grok)

XAI_API_KEY=...

Base URL: https://api.x.ai/v1. Supported models: Grok-2, Grok-3, Grok-3 Mini.

DeepSeek

DEEPSEEK_API_KEY=...

Base URL: https://api.deepseek.com. Supported models: DeepSeek-V3, DeepSeek-R1 (reasoning).

---

Provider Summary

Provider	Mode	API Key Variable
Ollama	Local	none
Anthropic	Cloud	ANTHROPIC_API_KEY
OpenAI	Cloud	OPENAI_API_KEY
Gemini	Cloud	GEMINI_API_KEY
xAI (Grok)	Cloud	XAI_API_KEY
DeepSeek	Cloud	DEEPSEEK_API_KEY

---

Per-Agent Model Override

Every agent can use a different model and provider. In Settings → Agents, edit an agent and set:

• LLM Provider — select from configured providers
• Model — choose from available models for that provider

This lets you run cheap/fast models for routing steps and powerful models for analysis — all in the same orchestration.

---

Data Directory

All user data (agents, orchestrations, vault files, logs, memory) is stored under SYNAPSE_DATA_DIR:

~/.synapse/data/           (installed)
backend/data/              (dev/cloned)
/data/                     (Docker volume)
  user_agents.json         Agent configurations
  orchestrations.json      Workflow definitions
  mcp_servers.json         Remote MCP server configs
  vault/                   Agent file storage
  sessions/                Conversation history
  logs/                    Audit logs

Never hardcode paths — always derive from SYNAPSE_DATA_DIR.