Skip to main content

Environment Variables

Environment variables configure infrastructure-level settings — ports, paths, and URLs. They are read at startup and cannot be changed at runtime without a restart.

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

cp .env.example .env

Data directory​

SYNAPSE_DATA_DIR — the directory where Synapse stores all user data: settings, agents, vault files, logs, and orchestration run state. Defaults to backend/data. Can be an absolute path or relative to the repo root.

For Docker deployments, mount a persistent volume at this path so data survives container restarts.

Ports​

SYNAPSE_BACKEND_PORT — port for the FastAPI backend API server. Defaults to 8000.

SYNAPSE_FRONTEND_PORT — port for the Next.js frontend. Defaults to 3000.

NEXT_PUBLIC_BACKEND_PORT — the backend port as baked into the browser bundle. Must match SYNAPSE_BACKEND_PORT. Requires a frontend rebuild when changed.

URLs​

BACKEND_URL — the backend URL as seen by the Next.js server-side renderer. Auto-derived as http://127.0.0.1:{SYNAPSE_BACKEND_PORT}. Override this for Docker or remote deployments where the backend runs on a different hostname, for example http://synapse-backend:8000.

OLLAMA_BASE_URL — the Ollama server URL for local model inference. Defaults to http://127.0.0.1:11434.

CORS_ORIGINS — comma-separated list of origins the backend allows via CORS. Defaults to http://localhost:3000,http://localhost:5173. Add your deployment origin if you're hosting Synapse at a custom domain.

Database​

DATABASE_URL — PostgreSQL connection URL for the coding agent's built-in database. Defaults to postgres://postgres:root@localhost:5432/synapse. This is separate from any user-configured database connections in Settings → DB Configs.

Security​

SYNAPSE_JWT_SECRET — the secret used to sign JWT tokens for login authentication. Auto-generated and persisted to .env on the first synapse start. For stateless container deployments where the .env file is not persisted, set this manually so that tokens remain valid across restarts.

LLM API keys via environment​

LLM provider API keys can be passed as environment variables instead of (or in addition to) entering them in the Settings UI. The backend reads these on startup:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
GROK_API_KEY=xai-...
DEEPSEEK_API_KEY=...

Values set in the Settings UI take precedence over environment variables.

Data directory layout​

When SYNAPSE_DATA_DIR is set (e.g. /data), Synapse creates and manages these files:

/data/
├── settings.json           # Global settings (editable from Settings UI)
├── user_agents.json        # Agent configurations
├── orchestrations/         # Orchestration DAGs and run state
│   └── runs/               # Per-run checkpoints (enables resume after failure)
├── custom_tools.json       # Custom HTTP and Python tool registry
├── mcp_servers.json        # MCP server configurations
├── db_configs.json         # Database connection configs
├── schedules.json          # Cron and interval schedule definitions
├── vault/                  # Persistent files accessible to agents
├── repos.json              # Code repository index configs
├── api_keys.json           # API key registry
├── credentials.json        # Google OAuth client credentials
├── token.json              # Google OAuth token
├── google-credentials/     # Workspace MCP token cache
└── logs/                   # Agent and schedule execution logs

Docker example​

docker run -d \
  -e SYNAPSE_DATA_DIR=/data \
  -e SYNAPSE_BACKEND_PORT=8000 \
  -e SYNAPSE_FRONTEND_PORT=3000 \
  -e NEXT_PUBLIC_BACKEND_PORT=8000 \
  -e BACKEND_URL=http://localhost:8000 \
  -e CORS_ORIGINS=http://localhost:3000 \
  -e SYNAPSE_JWT_SECRET=your-secret-here \
  -v synapse-data:/data \
  -p 3000:3000 -p 8000:8000 \
  synapseorchai/synapse-ai:latest
info

Mount the data volume (-v synapse-data:/data) to preserve settings, agents, and vault files across container restarts and upgrades.

Last updated on