Configuration Overview

This page separates restart-required host configuration from runtime settings managed in the application.

Polygent is configured through two layers:

1. appsettings.json (and environment variable overrides) — boot-time configuration: database, storage, OAuth credentials, base URLs, log levels, ticket sync interval, local-host capacity.
2. The Settings UI — runtime configuration: model credentials, model visibility, global ticket concurrency, insights and merge-conflict settings, system logs viewer. Stored in the database; takes effect without restarting.

Most day-to-day configuration lives in the Settings UI. appsettings.json is touched only when you install, swap database providers, change OAuth credentials, or tune host-level limits.

appsettings.json

The primary configuration file is appsettings.json, located alongside the API executable. The following is the shipped control-plane configuration; keep release-supplied sections that are not shown in this operational excerpt unchanged unless Support directs a change.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "AllowedHosts": "*",
  "Login": {
    "AccessTokenMinutesLifetime": 15,
    "RefreshTokenDaysLifetime": 7,
    "ClientUrl": "https://localhost:5173",
    "ClientId": "",
    "ClientSecret": "",
    "LoginType": "Google",
    "TenantId": "",
    "Authority": "",
    "OidcDisplayName": "",
    "OidcScopes": "",
    "EnableSeamlessSso": false,
    "AllowNewUsers": true
  },
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": null
  },
  "ClientUrl": null,
  "McpUrl": null,
  "StoragePath": null,
  "ShowChatInNewMenu": false,
  "ShowDevelopInNewMenu": false,
  "Tickets": {
    "SyncIntervalMinutes": 15,
    "EnableReadyForQaSummary": false
  },
  "MergeWorktreePrefix": "merge",
  "MergeAiTimeoutSeconds": 1800,
  "LocalHost": {
    "Enabled": true
  },
  "HostProtocolVersion": {
    "MinSupported": 5,
    "Current": 5
  }
}

Top-Level Keys

These keys control process startup, public URLs, and feature exposure. Configure host concurrency limits on the Hosts page; changes apply without an API restart. Regular pending messages run before internal follow-up reports, and both run before new ticket starts. Internal follow-up work uses its active ticket's existing capacity when available; otherwise it uses Sessions capacity.

Key	Purpose
Logging:LogLevel	Minimum log levels per category (see System Logs)
AllowedHosts	ASP.NET Core host filter; * accepts any incoming Host header
Login	OAuth provider, JWT lifetimes (see Authentication)
Database	EF Core provider + connection string (see Database)
ClientUrl	Optional override for the React client URL used in shared links and notifications
McpUrl	Optional MCP endpoint override advertised to session hosts. Keep it behind HTTPS and reachable only from trusted worker networks.
StoragePath	Root directory for keys, logs, SQLite database, worktrees, and attachments (see Storage)
ShowChatInNewMenu	Show the built-in Chat item in the New menu; default false
ShowDevelopInNewMenu	Show the built-in Develop item in the New menu; default false
Tickets	External ticket sync interval and ready-for-QA summary toggle. The shipped configuration disables ready-for-QA summaries; if the key is omitted, they are enabled.
MergeWorktreePrefix	Prefix for temporary worktrees used by Merge Conflicts (default merge)
MergeAiTimeoutSeconds	Per-attempt timeout for AI-assisted conflict resolution, excluding time waiting for process capacity and time spent on merge hooks (queued, running, or retrying) (default: up to 30 minutes)
LocalHost	Local session host enable flag
HostProtocolVersion	Remote Session Worker compatibility gate; change only during coordinated upgrades

Configuration Sections

Section	What it covers
Database	Provider (SQLite / SQL Server / PostgreSQL), connection strings, migrations
Storage	StoragePath layout: keys, logs, worktrees, SQLite database
Models & Backends	Model visibility, custom models, and backend credentials
Environment Variables	App-level (appsettings.json) and workspace-level secrets
Global Settings	Runtime UI settings: Client URL, insights/merge-conflicts model, low-priority hour
Authentication	Google / Microsoft OAuth2 + generic OpenID Connect + JWT (Login section)
System Logs	Log levels, time filters, file layout

Environment Variable Overrides

Every value in appsettings.json can be overridden via environment variables using __ (double underscore) as the section separator:

# Override the database connection string
Database__ConnectionString="Host=localhost;Database=polygent;Username=polygent;Password=secret"

# Override the database provider
Database__Provider="PostgreSql"

# Override the storage path
StoragePath="/var/lib/polygent"

# Override the bind URL (multi-host comma-separated)
Urls="http://0.0.0.0:5000;https://0.0.0.0:5001"

# OAuth credentials via env (recommended over committing to appsettings.json)
Login__LoginType="Google"
Login__ClientId="..."
Login__ClientSecret="..."

Host authentication keys are not configured in appsettings.json. Issue and manage them at runtime through the Hosts → API Keys tab in the application.

Environment variables take precedence over appsettings.json. This is the recommended pattern for credentials, container deployments, and any secret you do not want in source control.

Configuration Reload Semantics

Change	Takes effect
appsettings.json (Database, Login, StoragePath, Tickets, LocalHost, Logging, …)	Restart the API
Settings UI values (client URL, model credentials, visibility, and custom models)	Immediately, no restart
Hosts page per-host settings (Max Concurrent Tickets, allowed workspaces, enable/disable)	Immediately, no restart
Workspace settings (model defaults, environment variables, hooks, tasks, and members)	Immediately, no restart

Permissions

Settings access requires settings.view (read) and settings.manage (write). Admins bypass these checks. See Permissions.