Skip to main content

Settings Reference

All settings are managed through the Settings panel in the Synapse UI. You can reach it from the left sidebar at any time. Settings are stored in DATA_DIR/settings.json and merged with defaults on startup — you only need to include fields you want to override.

General​

The General tab controls core behaviour for your Synapse instance.

Global Agent Name sets the display name shown in the UI header and used when the agent introduces itself. Defaults to "Synapse".

Large Response Handling controls how Synapse deals with very long agent responses. Toggle it on to enable automatic summarisation once a conversation reaches the character threshold you set. The field shows a token estimate alongside the character count so you can calibrate it against your model's context window.

Auto Context Compaction works similarly but compacts the full conversation history rather than just the latest response. Enable it and set the threshold at which compaction kicks in. Useful for long-running research or coding sessions where context would otherwise overflow.

Database Write Access is off by default. When disabled, the SQL tool only permits SELECT, SHOW, and DESCRIBE queries. Enable this only for agents that need to write data.

Code Repository Indexing enables semantic code search. Toggling it on reveals a PostgreSQL connection form — fill in Host, Port, Username, Password, and Database Name. Synapse uses pgvector to store embeddings of your indexed code files. You also need at least one repo configured under Settings → Repos.

Bash Command Directories is a list of filesystem paths the bash tool is allowed to operate in. Add directories with the + button and remove them with the trash icon. The vault and any configured repo paths are always permitted regardless of this list.

Login & Security lets you gate the UI behind a username and password. Toggle it on, enter a username, and set a password (minimum 8 characters). The password is stored as a bcrypt hash — never the plaintext value. You can change the password at any time from this same section.

Models​

The Models tab is where you connect Synapse to your LLM providers. Each provider has its own card.

Ollama (Local)​

Ollama runs models locally on your machine. No API key is required. Synapse connects to Ollama at the URL configured in your .env file (OLLAMA_BASE_URL, default http://127.0.0.1:11434). Once Ollama is running and you have models pulled, they appear in Synapse's model selector prefixed with ollama. — for example ollama.llama3.2.

Google Gemini​

Enter your Gemini API key. You can find it in Google AI Studio. Models are prefixed with gemini. in Synapse — for example gemini.gemini-1.5-pro.

Anthropic Claude​

Enter your Anthropic API key (starts with sk-ant-). Models are prefixed with claude- — for example claude-3-5-sonnet-20241022.

OpenAI​

Enter your OpenAI API key (starts with sk-). Models are prefixed with openai. — for example openai.gpt-4o.

xAI Grok​

Enter your xAI API key (starts with xai-). Models are prefixed with grok..

DeepSeek​

Enter your DeepSeek API key. Models are prefixed with deepseek..

AWS Bedrock​

Bedrock requires more fields:

  • API Key — your Amazon Bedrock access key
  • Inference Profile — the inference profile ID or ARN (required for cross-region inference)
  • Region — AWS region, defaults to us-east-1
  • AWS Access Key ID and Secret Access Key — standard AWS credentials
  • Session Token — only needed for temporary (STS) credentials
  • Embedding Model — the embedding model used for long-term agent memory in Bedrock mode

OpenAI-Compatible (Cloud)​

For third-party providers that expose an OpenAI-compatible API — OpenRouter, Together AI, Fireworks, and others.

  • API Key — the key for the provider
  • Base URL — the provider's API base URL (e.g. https://openrouter.ai/api/v1)
  • Model Names — comma-separated list of model identifiers to make available
  • Embedding Model Names — comma-separated embedding models (optional)

Models are prefixed with oaic. in Synapse.

Local v1-Compatible​

For locally hosted OpenAI-compatible servers: vLLM, LM Studio, Ollama's /v1 endpoint, and similar.

  • Base URL — the local server address (e.g. http://localhost:8080/v1)
  • API Key — optional; some local servers require a placeholder value
  • Model Names — comma-separated list of model names to register
  • Embedding Model Names — comma-separated embedding models (optional)

Models are prefixed with locv1. in Synapse.

API Keys​

The API Keys tab manages programmatic access to the Synapse API.

Enter a name for the key (e.g. production, n8n-integration) and click Generate API Key. The full key is shown once — copy it immediately. After that, only the prefix is displayed.

Each key in the list shows its name, prefix, when it was created, when it was last used, and whether it is active. You can delete a key at any time from this list.

Use these keys as Bearer tokens in all API v1 requests. See API Reference for usage details.

n8n Integration​

n8n settings appear under Settings → Integrations.

  • n8n URL — your n8n instance address. Defaults to http://localhost:5678.
  • n8n API Key — the API key from your n8n instance (Settings → API Keys in n8n).
  • Default Workflow ID — optional default workflow used when no specific workflow is selected in a custom tool.

See n8n Integration for the full setup walkthrough.

Global Config​

Global config is a set of key-value pairs injected into every agent's system prompt as environment context. Configure it in Settings → General under the advanced section.

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

These values are available to agents as named context — useful for shared configuration like API base URLs or environment identifiers that all agents should know about.

Example settings.json​

If you prefer to edit the file directly instead of using the UI:

{
  "agent_name": "Synapse",
  "model": "claude-3-5-sonnet-20241022",
  "anthropic_key": "sk-ant-...",
  "vault_enabled": true,
  "vault_threshold": 100000,
  "auto_compact_enabled": false,
  "auto_compact_threshold": 100000,
  "allow_db_write": false,
  "embed_code": false,
  "sql_connection_string": "postgresql://user:pass@localhost:5432/synapse",
  "login_enabled": true,
  "login_username": "admin",
  "bash_allowed_dirs": ["/home/user/projects"],
  "n8n_url": "http://localhost:5678",
  "n8n_api_key": "n8n_...",
  "global_config": {
    "COMPANY_NAME": "Acme Corp",
    "ENV": "production"
  }
}
Last updated on