Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Emanuele-web04/synara/llms.txt

Use this file to discover all available pages before exploring further.

Synara’s server reads all of its runtime preferences from a single JSON file on disk. You can tune which AI providers are enabled, what binary paths they use, which skills are disabled, and how new threads are opened — all without touching environment variables or restarting your machine. This page documents every supported field, its type, and its default value.

​
File Location

Synara resolves its configuration directory from the SYNARA_HOME environment variable. When that variable is not set it defaults to ~/.synara. 
~/.synara/userdata/settings.json
If you override the home directory at startup with --home-dir or SYNARA_HOME, the file lives at: 
$SYNARA_HOME/userdata/settings.json
The userdata/ sub-directory is used for normal (non-dev) runs. In dev mode Synara writes to a dev/ directory instead, keeping development state separate from your production data.

​
Top-Level Fields

​
enableAssistantStreaming
boolean
default:"false"
When true, the server streams assistant responses token-by-token to the client as they are generated. When false, the full response is buffered and sent at once.
​
defaultThreadEnvMode
"local" | "worktree"
default:"\"local\""
Controls the default workspace environment created for new threads.
  • "local" — the thread runs against the project directory directly.
  • "worktree" — the thread gets its own Git worktree, isolating changes from the main branch.
​
addProjectBaseDirectory
string
default:"\"\""
An absolute path to a directory that Synara should auto-scan for projects on startup. Sub-directories that look like Git repositories are added to your project list automatically. Leave empty to disable.
​
textGenerationModelSelection
object
The model used for lightweight text-generation tasks such as writing commit messages. Accepts a provider string and a model string. The full list of available providers matches the keys under providers below.
​
skills
object
User-level skill toggles. See Skills below.
​
providers
object
Provider-specific settings keyed by provider name. See Providers below.

​
Skills

​
skills.disabled
string[]
default:"[]"
An array of skill names (lowercase) that should be disabled globally across all providers. Skills are identified by their lowercase unified-catalog name.
{
  "skills": {
    "disabled": ["web-search", "code-review"]
  }
}

​
Providers

Every provider block shares a common base set of fields, then adds its own extras.

​
Common Provider Fields

​
providers.<name>.enabled
boolean
default:"true"
Set to false to hide the provider from the UI and prevent it from being launched.
​
providers.<name>.binaryPath
string
Path to the provider’s CLI binary. Accepts a bare executable name (resolved via PATH) or an absolute path. Each provider has its own compiled-in default shown in the table below.
​
providers.<name>.customModels
string[]
default:"[]"
Extra model identifiers to surface in the model picker for this provider. Each string must be 256 characters or fewer.

​
Provider Reference

Provider keyDefault binaryPathExtra fields
codexcodexhomePath
claudeAgentclaudelaunchArgs
cursorcursor-agentapiEndpoint
geminigemini—
grokgrok—
opencodeopencodeserverUrl, serverPassword, experimentalWebSockets
kilokiloserverUrl, serverPassword
pipiagentDir

​
Provider-Specific Extra Fields

​
providers.codex.homePath
string
default:"\"\""
Path to an alternate Codex home directory. Leave empty to use the provider’s built-in default.
​
providers.claudeAgent.launchArgs
string
default:"\"\""
Additional command-line arguments passed verbatim to the claude binary at launch. For example "--verbose". Maximum 4096 characters.
​
providers.cursor.apiEndpoint
string
default:"\"\""
Custom API endpoint URL for the Cursor agent. Leave empty to use the provider’s built-in endpoint.
​
providers.opencode.serverUrl
string
default:"\"\""
URL of a remote OpenCode server. Leave empty to use a locally launched process.
​
providers.opencode.serverPassword
string
default:"\"\""
Password for the remote OpenCode server specified by serverUrl.
​
providers.opencode.experimentalWebSockets
boolean
default:"false"
Enable the experimental WebSocket transport for OpenCode communication. This is off by default; enable only if you are testing the new transport.
​
providers.kilo.serverUrl
string
default:"\"\""
URL of a remote Kilo server. Leave empty to use a locally launched process.
​
providers.kilo.serverPassword
string
default:"\"\""
Password for the remote Kilo server specified by serverUrl.
​
providers.pi.agentDir
string
default:"\"\""
Path to the Pi agent’s working directory. Leave empty to use the provider’s built-in default.

​
Example settings.json

The following snippet enables Claude with a custom binary path, disables Grok, configures OpenCode to connect to a remote server, and turns off a skill globally: 
{
  "enableAssistantStreaming": true,
  "defaultThreadEnvMode": "worktree",
  "addProjectBaseDirectory": "/Users/alice/projects",
  "textGenerationModelSelection": {
    "provider": "codex",
    "model": "o4-mini"
  },
  "providers": {
    "claudeAgent": {
      "enabled": true,
      "binaryPath": "/usr/local/bin/claude",
      "launchArgs": "--verbose"
    },
    "grok": {
      "enabled": false
    },
    "opencode": {
      "enabled": true,
      "serverUrl": "https://opencode.internal.example.com",
      "serverPassword": "s3cr3t"
    }
  },
  "skills": {
    "disabled": ["web-search"]
  }
}
Changes to settings.json are not hot-reloaded. Restart the Synara server after editing the file for them to take effect.

Build docs developers (and LLMs) love

Get started for freeTalk to us