synapse/config.example.toml at main · dinglebear-ai/synapse · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# =============================================================================
# config.example.toml — Annotated Synapse config.toml reference
#
# This file documents the non-secret configuration options Synapse reads from
# config.toml. Copy it to config.toml and adjust for your deployment.
#
#           config.toml holds non-secret defaults. Secrets and URLs go in .env.
#           See .env.example for the secrets side of the split.
#
# SPLIT PHILOSOPHY:
#   config.toml → ports, bind addresses, feature flags, timeouts, rate limits,
#                 anything safe to commit
#   .env        → API URLs, API keys, tokens, OAuth credentials, passwords,
#                 logging env vars, deploy/runtime vars, anything secret
#
# Environment variables ALWAYS take priority over config.toml values.
# Naming:
#   SYNAPSE_MCP_*  → [mcp] section  (server config)
#   SYNAPSE_API_*  → optional upstream service process env
# =============================================================================

# ── Optional upstream integration env ─────────────────────────────────────────
# SYNAPSE_API_URL and SYNAPSE_API_KEY are loaded when present for integrations
# that need an upstream HTTP API. Flux and Scout do not require them.

# ── MCP HTTP server ───────────────────────────────────────────────────────────
[mcp]

# Bind host for the MCP HTTP server.
# SYNAPSE_MCP_HOST env var overrides this.
#   0.0.0.0   → accept connections from all interfaces (for Docker, reverse proxy)
#   127.0.0.1 → loopback only (safest for local dev; no auth required)
# Leave as 0.0.0.0 for Docker deployments. By default, non-loopback binds require
# bearer/OAuth auth. A trusted gateway may instead own auth/authz when
# SYNAPSE_NOAUTH=true, but the port must then be isolated so only that gateway
# can reach it.
host = "0.0.0.0"

# Bind port for the MCP HTTP server.
# SYNAPSE_MCP_PORT env var overrides this.
# Synapse's assigned port is 40080.
port = 40080

# Server name advertised to MCP clients in the tools/list response.
# SYNAPSE_MCP_SERVER_NAME env var overrides this.
server_name = "synapse"

# Disable authentication entirely.
# ONLY safe when host = "127.0.0.1" (loopback — your machine only).
# SYNAPSE_MCP_NO_AUTH env var overrides this.
# Never set to true in production. Use just dev for local no-auth mode.
# no_auth = false

# Static bearer token for /mcp authentication.
# SYNAPSE_MCP_TOKEN env var overrides this.
# Always set via env var, never in config.toml.
#   Generate with: openssl rand -hex 32   or   just gen-token
# api_token = ""

# Extra Host header values allowed by the RMCP host-validation middleware.
# SYNAPSE_MCP_ALLOWED_HOSTS env var (comma-separated) overrides this.
# Add your reverse proxy hostname or local DNS name.
# allowed_hosts = ["synapse.example.com", "synapse.lan"]

# Extra CORS origins for browser-based MCP clients.
# SYNAPSE_MCP_ALLOWED_ORIGINS env var (comma-separated) overrides this.
# Add your frontend origin if building a browser-based client.
# SECURITY NOTE: By default, localhost and 127.0.0.1 are always allowed.
#                Add specific client origins (e.g., https://claude.ai) in production.
#                CORS is defense-in-depth; auth (bearer token or OAuth) is the
#                primary security control. An authenticated attacker can bypass CORS.
# allowed_origins = ["https://claude.ai", "http://localhost:5173"]

# Allow destructive operations (rm, dd, mkfs, etc.).
# SYNAPSE_MCP_ALLOW_DESTRUCTIVE env var (true/false) overrides this.
# SECURITY: Only safe on loopback (localhost). If set to true with a non-loopback
#           bind address, the server will refuse to start with a clear error message.
#           Do NOT enable this in production unless absolutely necessary.
# allow_destructive = false

# ── OAuth / JWT authentication ────────────────────────────────────────────────
# This sub-section configures the optional OAuth + JWT auth layer. Activate it
# by setting SYNAPSE_MCP_AUTH_MODE=oauth in .env. Leave all sensitive values
# (client_id, client_secret, public_url) in .env — never in this file.
[mcp.auth]

# Authentication mode: "bearer" (default) or "oauth".
# SYNAPSE_MCP_AUTH_MODE env var overrides this.
# Start with "bearer" for simplicity. Switch to "oauth" when you need per-user
# identity and Google account-gated access.
mode = "bearer"

# Public URL of this MCP server (required in OAuth mode).
# SYNAPSE_MCP_PUBLIC_URL env var overrides this.
# Must be reachable from MCP clients. Set in .env, not here.
# public_url = "https://synapse.example.com"

# Google OAuth 2.0 credentials — ALWAYS set via .env, never here.
# SYNAPSE_MCP_GOOGLE_CLIENT_ID env var overrides this.
# google_client_id = ""
# SYNAPSE_MCP_GOOGLE_CLIENT_SECRET env var overrides this.
# google_client_secret = ""

# Bootstrap admin email — the first Google account allowed to authenticate.
# SYNAPSE_MCP_AUTH_ADMIN_EMAIL env var overrides this.
# Set to your Google account email. Additional accounts are managed by the OAuth
# admin store after bootstrap.
admin_email = ""

# Path to the SQLite database for OAuth sessions and client registrations.
# SYNAPSE_MCP_AUTH_SQLITE_PATH env var overrides this.
# In Docker, /data is bind-mounted from ~/.synapse on the host. For bare-metal,
# change to ~/.synapse/auth.db.
sqlite_path = "/data/auth.db"

# Path to the RS256 private key for JWT signing.
# SYNAPSE_MCP_AUTH_KEY_PATH env var overrides this.
# Auto-generated on first run if it doesn't exist.
# In Docker, /data is bind-mounted from ~/.synapse on the host. For bare-metal,
# change to ~/.synapse/auth-jwt.pem.
key_path = "/data/auth-jwt.pem"

# How long issued access tokens are valid (seconds).
# SYNAPSE_MCP_AUTH_ACCESS_TOKEN_TTL_SECS env var overrides this.
# 3600 (1 hour) is the standard. Reduce for higher security environments.
access_token_ttl_secs = 3600

# How long refresh tokens are valid (seconds).
# SYNAPSE_MCP_AUTH_REFRESH_TOKEN_TTL_SECS env var overrides this.
# 2592000 = 30 days. Increase for "remember me" UX; decrease for tighter
# security. MCP clients re-authenticate when this expires.
refresh_token_ttl_secs = 2592000

# How long OAuth authorization codes are valid (seconds).
# SYNAPSE_MCP_AUTH_CODE_TTL_SECS env var overrides this.
# 300 (5 minutes) is the OAuth spec default. Reduce to 60 for stricter setups.
auth_code_ttl_secs = 300

# Rate limit: max new client registrations per minute per IP.
# SYNAPSE_MCP_AUTH_REGISTER_REQUESTS_PER_MINUTE env var overrides this.
# 10 is reasonable for a private server. Reduce to 1-3 for strict control.
register_rpm = 10

# Rate limit: max authorization attempts per minute per IP.
# SYNAPSE_MCP_AUTH_AUTHORIZE_REQUESTS_PER_MINUTE env var overrides this.
# 60 allows normal OAuth flows. Reduce if you see abuse.
authorize_rpm = 60

# When OAuth is active, disable the static bearer token (SYNAPSE_MCP_TOKEN).
# SYNAPSE_MCP_AUTH_DISABLE_STATIC_TOKEN_WITH_OAUTH env var overrides this.
# Set to false if you want both OAuth and static token active simultaneously.
# Useful during migration from bearer to OAuth.
disable_static_token_with_oauth = true

# Extra redirect URIs allowed during OAuth.
# SYNAPSE_MCP_AUTH_ALLOWED_REDIRECT_URIS env var (comma-separated) overrides this.
# claude.ai redirect URIs are included by default.
# Add your MCP client's redirect URIs if they differ from claude.ai's.
allowed_client_redirect_uris = []

# ── Host topology (the SSH / Docker fleet) ────────────────────────────────────
# Hosts are NOT defined in this file. They are loaded by src/host_config.rs in
# precedence order (first non-empty explicit source wins; SSH config is additive):
#
#   1. SYNAPSE_HOSTS_CONFIG env — inline JSON array of host objects.
#   2. SYNAPSE_CONFIG_FILE env  — path to a JSON file ({ "hosts": [ ... ] }).
#   3. ./synapse.config.json, then ~/.config/synapse/hosts.json, etc.
#   4. ~/.ssh/config            — AUTO-DISCOVERED. Every concrete (non-wildcard)
#                                 Host block with a HostName becomes an SSH host,
#                                 inheriting User / Port / IdentityFile. This is
#                                 the recommended path: define your fleet once in
#                                 ~/.ssh/config and Synapse picks it up.
#   5. Built-in `local` host    — always appended (Docker over /var/run/docker.sock).
#
# Host protocol is authoritative. Explicit host objects default to `ssh` when
# protocol is omitted; local execution requires `protocol: "local"`. Loopback
# SSH endpoints therefore retain their configured user/key/port. Recursive SSH
# Include files are tracked for live topology refresh. Per-host Scout/Compose
# roots constrain reads and both endpoints of bounded `scout beam` transfers.
#
# In Docker, bind-mount the operator's SSH config so discovery works — the image
# sets HOME=/home/synapse, so the mount target is /home/synapse/.ssh (see
# docker-compose.prod.yml). The `local` Docker host additionally needs the daemon
# socket bind-mounted and DOCKER_GID set (see .env.example).