Configuration Overview

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 (/settings/... in the app) — runtime configuration: provider paths, model visibility, global tickets concurrency, insights/merge-conflicts provider, 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.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning",
      "Serilog.AspNetCore.RequestLoggingMiddleware": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Login": {
    "AccessTokenMinutesLifetime": 15,
    "RefreshTokenDaysLifetime": 7,
    "ClientUrl": "https://localhost:5173",
    "ClientId": "",
    "ClientSecret": "",
    "LoginType": "Google",
    "TenantId": "",
    "Authority": "",
    "OidcDisplayName": "",
    "OidcScopes": "",
    "EnableSeamlessSso": false,
    "EnableTestLogin": false,
    "AllowNewUsers": true
  },
  "Database": {
    "Provider": "Sqlite",
    "ConnectionString": null
  },
  "ClientUrl": null,
  "McpUrl": null,
  "StoragePath": null,
  "Tickets": {
    "SyncIntervalMinutes": 15,
    "EnableReadyForQaSummary": false
  },
  "MergeWorktreePrefix": "merge",
  "MergeAiTimeoutSeconds": 1800,
  "LocalHost": {
    "Enabled": true,
    "MaxConcurrentSessions": 16
  }
}

Security: Login.EnableTestLogin bypasses OAuth entirely and must never be set to true in production. Keep it false (the default) in all production appsettings.json files. Use environment-variable overrides, not this setting, if you need test login for non-production environments.

Top-Level Keys

Key	Purpose
Logging:LogLevel	Minimum log levels per namespace (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 override for the public MCP endpoint URL advertised to provider configs
StoragePath	Root directory for keys, logs, SQLite DB, worktrees, attachments (see Storage)
Tickets	External ticket sync interval and ready-for-QA summary toggle
MergeWorktreePrefix	Prefix for temporary worktrees used by Merge Conflicts (default merge)
MergeAiTimeoutSeconds	Per-attempt timeout for AI-assisted conflict resolution (default: up to 30 minutes)
LocalHost	In-process session host: enable flag and per-host concurrent session cap

Configuration Sections

Section	What it covers
Database	Provider (SQLite / SQL Server / PostgreSQL), connection strings, migrations
Storage	StoragePath layout: keys, logs, worktrees, SQLite database
Agent Providers	Model visibility, custom models for all seven providers
Environment Variables	App-level (appsettings.json) and workspace-level secrets
Global Settings	Runtime UI settings: Client URL, insights/merge-conflicts provider, 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, providers, models, custom models)	Immediately, no restart
Hosts page per-host settings (Max Concurrent Tickets, allowed workspaces, enable/disable)	Immediately, no restart
Workspace settings (provider, env vars, hooks, tasks, members)	Immediately, no restart

Permissions

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