Configuration

Configuration is resolved from, in increasing precedence:

1. ~/.polyglot/settings.json (global)
2. .polyglot/settings.json in the current project
3. environment variables
4. launch flags (a few settings can be tightened, never loosened, by a CLI flag)

Lists (models, permissions.allow, permissions.deny, mcpServers) are merged across the global and project files, not replaced.

settings.json

{
  "provider": "openai-compatible",
  "model": "qwen2.5-coder",
  "baseURL": "http://localhost:11434/v1",
  "apiKey": "",
  "structuredOutput": false,

  "permissions": {
    "mode": "manual",
    "allow": [],
    "deny": ["bash:rm -rf *"]
  },

  "persistTranscripts": true,
  "retentionDays": 30,

  "webSearch": {
    "provider": "duckduckgo",
    "apiKey": "",
    "baseURL": ""
  },

  "models": [
    { "provider": "anthropic", "model": "claude-sonnet-4-5", "label": "Claude Sonnet" }
  ],

  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/an/allowed/dir"]
    }
  },

  "autoUpdate": true
}

Key	Type	Default	Notes
provider	"anthropic" | "openai-compatible"	-	Required.
model	string	-	Required. The id the provider expects.
baseURL	string	http://localhost:11434/v1	openai-compatible only.
apiKey	string	-	Required for anthropic. Optional for local openai-compatible. Prefer env vars.
structuredOutput	boolean	false	openai-compatible only. What it does.
permissions.mode	"manual" | "auto" | "plan"	"manual"	Permission modes.
permissions.allow	string[]	[]	Rule syntax.
permissions.deny	string[]	[]	Checked before everything else.
persistTranscripts	boolean	true	false = ephemeral, nothing written to ~/.polyglot/.
retentionDays	positive integer	- (keep forever)	Delete transcripts & plans older than N days on startup.
webSearch.provider	"duckduckgo" | "searxng" | "tavily" | "brave"	"duckduckgo"	Web search.
webSearch.apiKey	string	-	Required for tavily / brave.
webSearch.baseURL	string	-	The SearXNG instance URL.
models	array	[]	Multiple models.
mcpServers	object	{}	MCP servers.
autoUpdate	boolean	- (asks on first run)	Global file only; never merged from a project file.

Environment variables

Variable	Overrides
POLYGLOT_PROVIDER	provider
POLYGLOT_MODEL	model
POLYGLOT_BASE_URL	baseURL
POLYGLOT_API_KEY	apiKey for openai-compatible
ANTHROPIC_API_KEY	apiKey for anthropic (the standard Anthropic variable)
POLYGLOT_STRUCTURED_OUTPUT	structuredOutput (true/1/false/0)
POLYGLOT_PERMISSION_MODE	permissions.mode
POLYGLOT_NO_PERSIST	forces persistTranscripts off (1/true)
POLYGLOT_RETENTION_DAYS	retentionDays
POLYGLOT_WEBSEARCH_PROVIDER	webSearch.provider
POLYGLOT_WEBSEARCH_API_KEY	webSearch.apiKey
POLYGLOT_WEBSEARCH_BASE_URL	webSearch.baseURL

Auto-update

On first run Polyglot asks whether it should update itself when a new version is published, and stores the answer as autoUpdate in the global settings file. From then on, every startup does a quick non-blocking npm-registry check:

• true → runs the appropriate global reinstall in the background (npm/pnpm/yarn/bun, auto-detected) and tells you to restart.
• false → prints a notice with the manual update command.
• Offline or a registry hiccup → fails silently, never blocks startup.

Change it any time by editing autoUpdate in ~/.polyglot/settings.json.