Settings Reference

Settings are edited in the Settings screens, reached from the foot of the left rail. They are held in the store, scoped to the tenant, and read per call — there is no settings file.

Stored values overlay the shipped defaults, so you only ever set what you want to change. The settings screens are grouped four ways.

Repos and DB configs appear only when the coding agent is enabled. Messaging channels and widgets are not settings: they are the rail's Channels, Phone and Widgets tabs, under Channels.

General

Global agent name (agent_name, default Synapse) — the display name shown in the UI header and used when an agent introduces itself.

Default model (model, default ollama.mistral) — the model used by anything that does not override it. It is under Defaults on the Models screen, with Builder model. See Models.

Builder model (builder_model, default empty) — which model Synapse AI, the assistant that builds for you, runs on; the installer and Connect a model call it Synapse AI's model. Empty means "whatever model is". The builder is a long multi-step run, so it is worth pointing at a stronger model than the day-to-day one without changing every agent.

first_run_models_closed (default false) — set once Connect a model, the first start's model step, has been closed; it then doesn't open on its own again.

Judge model (judge_model, default empty) — the model that scores runs for evals. Empty falls back to model. It has no field on these screens; each rubric on the Evals screen picks its own Judge model.

Knowledge (knowledge_enabled, default off) — turns Knowledge on: Vault folders become searchable knowledge bases, so agents and workflows answer from your documents and cite them. It applies when the page is saved, with no restart. Then choose an embedding model under Settings → Models → Knowledge.

Large response handling (vault_enabled, default on; vault_threshold, default 100000 characters) — when a tool returns more than the threshold, the output is written to the vault and the agent is handed a reference instead of the whole payload.

Auto context compaction (auto_compact_enabled, default on; auto_compact_threshold, default 80000 characters) — shrinks a conversation that has grown past the threshold, in two stages:

1. Cheap trim — the oldest tool-call outputs are dropped with no LLM call. If that recovers at least 20% of the context, it stops there.
2. LLM summarise — otherwise the history is compressed to roughly 30% of its size, and the pre-compaction history is archived to the vault so you can still read it.

Either way, the request being worked on is kept word for word, and the newest part of the history is kept as it was. The summary is told never to add a task, goal or plan the conversation did not already hold.

Prompt caching (prompt_cache_enabled, default on) — decorates provider payloads so later turns reuse the cached system-and-tools prefix. Typically 50–80% off a multi-turn agent, against a ~25% write surcharge on the first turn. It has no field on this screen; turn it off through the settings API. See Caching.

Database write access (allow_db_write, default off) — with it off the SQL agent is limited to SELECT, SHOW and DESCRIBE.

Allowed directories (bash_allowed_dirs, default empty) — the folders agents may work in, beyond the ones they always have: linked repositories and the vault. One list serves the bash tool, the agent file tools (read_file_by_lines, grep, glob and the like) and the built-in Filesystem server, so the three never disagree. A folder added while Synapse runs applies to the next command at once, with no restart. A command run with no folder of its own starts in the first linked repository, or else the vault. See Built-in tools → Bash for how bash runs.

Code repository indexing (embed_code, default off) — enables semantic code search and reveals the PostgreSQL connection form that pgvector needs. You also need at least one repo under Settings → Repos. See Code repositories.

Global config (global_config, default {}) — key/value pairs injected into every agent's system prompt as environment context. It has no field on these screens; set it through the settings API.

{
  "COMPANY_NAME": "Acme Corp",
  "ENV": "production",
  "BASE_URL": "https://api.acme.com"
}

For values you want to reference explicitly inside prompts and tool bodies rather than inject everywhere, use Variables and {{ global.key }} instead.

Agent toggles — neither has a field on these screens. coding_agent_enabled (default on) reveals Repos and DB configs. It is an install-time choice, asked by the installer and read at startup to start the code indexer, so changing it takes a restart. messaging_enabled (default on) reveals the rail's Channels and Phone tabs (Messaging channels).

Ollama base URL (ollama_base_url, default empty) — where Ollama answers, for chat, embeddings, the model list and memory embeddings. Empty falls back to the OLLAMA_BASE_URL environment variable. No field on this screen; set it through the settings API. See Local models.

Security

Four settings move a real boundary. Two of them are the posture behind GHSA-3j67-x3j8-r32x.

Login (login_enabled, default off) — gates the UI behind a username and password, stored as a bcrypt hash. Turn on Require login under Login & security and give a username and password; you stay signed in as that user. Turning it off asks first, then applies at once. With login on, Sign out is in the rail's More menu, and a tab whose session has ended says You're signed out. with a link to sign in again. A session lasts 7 days.

The backend checks the session itself on every internal route, so a call through the app's port without one is answered 401 {"detail":"Login required"} rather than with the sign-in page. Calling the settings API from a script shows how to sign a script in.

With login off, Synapse opens with its access link instead of a password. For anything reachable beyond your own machine, turn login on.

stdio MCP registration (allow_stdio_mcp, default on) — stdio MCP servers launch local OS processes, so registering one is equivalent to running a command on the host. It is allowed by default for local single-user use and force-disabled in scale mode regardless of this setting. It is the Allow local (stdio) servers switch on the MCP Servers screen.

MCP command allowlist (mcp_command_allowlist, default empty = any command in PATH) — when non-empty, only these command basenames may be registered; it is Allowed commands on the same screen. Recommended for any exposed UI:

["npx", "uvx", "uv", "node", "python", "python3", "docker"]

Transform step Python runtime (transform_runtime, default docker) — how Python steps and tools execute. Its switch is Run Transform steps on the host:

• docker — the sandbox-python container: 512 MB, 1 CPU and a 30-second default timeout. Safe for untrusted code.
• host — an unsandboxed subprocess with full RAM, GPU, filesystem and network, and a 30-minute timeout. Needed for workflows that want torch and a GPU. Switching shows a confirmation because it removes the sandbox boundary; self-hosted single-user deployments only.

Tool policy (tool_policy_defaults, default {}) — the deployment-wide floor for which tools need a human's approval. Empty means allow everywhere, deliberately: a closed default would change the behaviour of every agent already running the moment you upgraded. Set per agent and per workspace on the Tool policy screen.

The access link

With login off, Synapse still does not open for whoever can reach its port. It opens with a link carrying this install's access token, SYNAPSE_ACCESS_TOKEN: http://localhost:3000/?token=….

• synapse start makes the token once, keeps it in the install's .env, opens the browser with the link, and prints it: Anyone with this link can use this Synapse. synapse access-link prints it again.
• The Docker images make it on first start, keep it beside the internal token on the data volume, and print it in the backend's log (docker logs synapse, or docker compose logs backend): [entrypoint] Access link (used while login is off; …). Set SYNAPSE_ACCESS_TOKEN yourself (in .env, for Compose) to pin one.

Opening the link signs that browser in for 7 days, and the token is taken out of the address so it never sits in the history. A browser without a session sees This Synapse needs its access link, with a box to paste it into.

To replace the link, run synapse access-link --rotate and restart Synapse; in Docker, delete access_token from the data volume (the synapse-secrets volume in Compose) and restart the container. Everyone signed in with the old link is signed out.

A password always wins. With login on, the access link opens nothing, and the page says to sign in instead. Platform webhooks and the chat widget never need a session, and the versioned API (/api/v1, /api/v2) takes API keys instead.

Calling the settings API from a script

A few settings have no field on these screens — prompt_cache_enabled and ollama_base_url among them — and are set through the app's own settings API, POST /api/settings, on the app's port. It takes the same session the browser does, so sign the script in once and keep the cookie:

# Login off: swap the access token (the part of the link after ?token=) for a session
curl -c synapse.cookies -X POST http://localhost:3000/api/auth/access \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_ACCESS_TOKEN"}'

# Login on: sign in with the username and password instead
curl -c synapse.cookies -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "YOUR_PASSWORD"}'

# Then send the cookie with every call
curl -b synapse.cookies -X POST http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -d '{"prompt_cache_enabled": false}'

The session lasts 7 days. What the API does with the body:

• Only the fields you send change. A field the settings do not have is refused with a 422 that names it.
• Secrets are never served back. GET /api/settings returns each provider key, token and secret as "", beside <name>_set (whether one is stored) and <name>_hint (its last four characters, for a long one). A secret sent blank keeps what is stored; to remove one, name it in clear_secrets, e.g. {"clear_secrets": ["openai_key"]}.

Agents, workflows, runs, schedules and chat are better driven through /api/v1 with an API key, which needs no session.

Models

One card per provider. Enter the key — and any extra fields Bedrock or an OpenAI-compatible endpoint needs — and that provider's models become selectable everywhere.

A saved key is never shown again: the card says A key is stored with its last characters, offers a Replace it field with its own Save, and a remove button that asks first. Each card saves and removes its own key. Keys are held in the store and read per call. They are never written to the process environment, so they are not visible in /proc/<pid>/environ and are not inherited by the stdio MCP servers and code sandbox this engine spawns.

Provider prefixes and model lists are in Hosted models, Local models, CLI mode and The model gateway.

Knowledge — shown while Knowledge is on: the embedding, rerank and Contextual Retrieval models knowledge bases use unless they name their own, and the rerank providers' keys. See Search and settings.

Knowledge

These have no field on any screen; set them through the settings API.

API Keys

Programmatic access to /api/v1 and /api/v2. Name a key, generate it, and copy it — the full value is shown once and only the prefix afterwards. Each row shows its name, prefix, creation date, last use and whether it is active. A key named Synapse CLI is the one the CLI made for itself; revoking it is safe, and the CLI makes another when next used.

Connect Claude Code or Cursor (MCP), on the same screen, shows how to add Synapse to an MCP client, with this install's address filled in — see Synapse as an MCP Server.

These are Bearer tokens for the external API and are unrelated to SYNAPSE_INTERNAL_TOKEN, which gates the UI's own routes. See the API reference.

Integrations

n8n instance URL (n8n_url, default http://localhost:5678) and API key — see n8n. Google Workspace credentials are configured here too; see Google Workspace.

Scale

Redis, Postgres and object storage for running across processes. What this screen saves: scale_mode_enabled, redis_url, scale_postgres_url, otlp_endpoint and the s3_* keys.

Worker concurrency, PgBouncer mode, the queue depth and rate limits and the metrics token are shown here but read only from the environment — WORKER_CONCURRENCY, PGBOUNCER_MODE, MAX_GLOBAL_QUEUE_DEPTH, RATE_LIMIT_PER_TENANT_RPS and METRICS_TOKEN. The screen shows them read-only, with the values in effect and the variable that sets each — never the metrics token itself, only whether one is set. The OTLP endpoint turns on telemetry export and applies on restart.

Turning scale mode on force-disables stdio MCP registration. See Scale mode.