Configuration Overview

Polygent is configured in two layers: restart-required host configuration in appsettings.json or environment variables, and runtime settings changed in the application.

1. appsettings.json / environment variables — boot-time configuration: database, storage path, identity provider, public URLs, log level, ticket sync interval, and the local session host. Changes require an API restart.
2. Application settings — runtime configuration: model credentials and catalog, global ticket execution, AI job settings, budgets, host limits, and Bash policy. Stored in {StoragePath}/settings.json (and the database for workspace data); changes apply without a restart.

appsettings.json is changed when you install, swap database providers, change identity-provider credentials, or move storage. Day-to-day configuration happens in the UI.

appsettings.json

The primary configuration file is appsettings.json beside the API executable. This is the operational part of the shipped file; keep release-supplied sections that are not shown here 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": "https://localhost:5173",
  "McpUrl": null,
  "StoragePath": null,
  "ShowChatInNewMenu": false,
  "ShowDevelopInNewMenu": false,
  "Tickets": {
    "SyncIntervalMinutes": 15,
    "EnableReadyForQaSummary": false
  },
  "ContentAssist": {
    "DefaultLanguage": "Hebrew"
  },
  "MergeWorktreePrefix": "merge",
  "MergeAiTimeoutSeconds": 1800,
  "LocalHost": {
    "Enabled": true
  }
}

For production, replace both https://localhost:5173 values with your public HTTPS URL and set an absolute StoragePath.

The API, Session Worker, and Deployment Worker also load appsettings.Production.json from the same folder when present (the environment defaults to Production); its values override appsettings.json. Put your settings there and leave appsettings.json as shipped: an upgrade replaces appsettings.json so new defaults take effect, and keeps appsettings.Production.json. The file name is case-sensitive on Linux.

Top-level keys

These keys control process startup, public URLs, and feature exposure.

Key	Default	Purpose
Logging:LogLevel:Default	Information	Minimum log level. See System Logs.
AllowedHosts	*	Host-header filter; set to your public hostname(s), separated by ;, to reject other Host values.
Login	—	Identity provider and token lifetimes. See Authentication.
Database	Sqlite	Provider and connection string. See Database.
ClientUrl	https://localhost:5173	Public base URL used in links (pull requests, notifications, automations, ticket back-links) and MCP OAuth callbacks. Not editable in the UI.
McpUrl	{ClientUrl}/mcp	MCP endpoint URL given to agents. An invalid value silently removes Polygent MCP tools from sessions. See MCP Server.
StoragePath	service account's %APPDATA%\Polygent	Root directory for keys, logs, SQLite database, working copies, and attachments. See Storage.
ShowChatInNewMenu	false	Show the built-in Chat card in the sidebar New picker.
ShowDevelopInNewMenu	false	Show the built-in Develop card in the sidebar New picker.
Tickets:SyncIntervalMinutes	15	External ticket sync poll interval.
Tickets:EnableReadyForQaSummary	true (shipped false)	Generate an AI summary when a ticket enters QA.
ContentAssist:DefaultLanguage	Hebrew	Default Translate and Explain language: Arabic, English, Hebrew, or Russian. Any other value prevents startup.
MergeWorktreePrefix	merge	Folder prefix for temporary merge-conflict working copies.
MergeAiTimeoutSeconds	1800 (30 minutes)	Per-attempt limit for AI conflict resolution, excluding time waiting for capacity and time spent in merge hooks.
LocalHost:Enabled	true	Run sessions inside the API process. Set false to run sessions only on Session Workers.
Git:LongRunningTimeoutSeconds	300	Timeout for clone, fetch, pull, push, staging, and working-copy operations on large repositories.
Mcp:OAuth:AllowedPrivateHosts	[]	Hostnames on private networks that MCP servers and their OAuth endpoints may use. Outbound MCP calls to non-public addresses are blocked otherwise. Set the same list on Session Workers.
Agent:DisableGitSslVerification	false	Disables Git certificate verification for Git operations run by this process. Leave false; see the security note in Deployment Worker.
HostProtocolVersion	release value	Remote Session Worker compatibility gate. Do not set it; the release default matches the shipped workers.

Harness keys

These keys under Harness configure the built-in agent runtime on the API host (and, in the Session Worker's own file, on each worker).

Key	Default	Purpose
Harness:DataDirectory	%USERPROFILE%\.polygent\harness of the service account	Agent conversation transcripts used to resume sessions. Lies outside StoragePath; include it in backups or move it under the storage volume. Also settable as POLYGENT_HARNESS_DATA_DIR.
Harness:ClaudeConfigDirectory	unset	Absolute path of the Claude Code configuration folder used for Claude Code models under a service account.
Harness:RepositorySkillExternalRoots	[]	Folders outside the working copy that repository skill links may point to. See Skills.
Harness:CompactionModel	unset	Optional lower-cost model used to summarize history when the context fills.
Harness:DenialEscalationMaxConsecutive	3	Consecutive blocked agent actions before the session stops and asks a human. 0 disables.
Harness:DenialEscalationMaxTotal	20	Total blocked agent actions in a run before the session stops and asks a human. 0 disables.

Leave other Harness values at the release defaults unless Support directs a change.

Reverse proxy and TLS

The API serves plain HTTP; TLS is expected to terminate at a reverse proxy or be configured on the ASP.NET Core server.

• Authentication cookies are always marked Secure, so browsers must reach Polygent over HTTPS (localhost is the only exception).
• Behind a TLS-terminating proxy, set ASPNETCORE_FORWARDEDHEADERS_ENABLED=true so Polygent honors X-Forwarded-Proto and X-Forwarded-For. Without it, OAuth redirect URIs are built as http:// and sign-in fails at the identity provider.
• A bare process or Windows Service listens on http://localhost:5000 (loopback only). Set Urls (or ASPNETCORE_URLS) to bind other addresses, separated by ; — for example http://0.0.0.0:5000. The container image listens on port 8080.
• Run a single API instance per database. Multiple API instances behind a load balancer are not a supported topology.

See Installation → Reverse proxy notes for WebSocket and upload-size requirements.

Environment variable overrides

Every appsettings.json value can be overridden with an environment variable, using __ (double underscore) as the section separator. Environment variables win over the file and are the recommended place for secrets.

# PowerShell (current process / container) examples
$env:Database__Provider = "PostgreSql"
$env:Database__ConnectionString = "Host=db;Database=polygent;Username=polygent;Password=secret"
$env:StoragePath = "D:\Polygent\data"
$env:Login__ClientSecret = "..."
$env:ASPNETCORE_FORWARDEDHEADERS_ENABLED = "true"

For a Windows Service, set variables for that service only in its registry Environment value, then restart the service:

reg add "HKLM\SYSTEM\CurrentControlSet\Services\Polygent" /v Environment /t REG_MULTI_SZ /d "Login__ClientSecret=...\0ASPNETCORE_FORWARDEDHEADERS_ENABLED=true" /f
sc.exe stop Polygent
sc.exe start Polygent

Protect the service registry key and the appsettings.json file with ACLs that allow only administrators and the service account. Host authentication keys are not configured here — issue them under Hosts → API Keys. See Environment Variables for the full list.

Configuration sections

Each configuration area has its own reference page.

Section	What it covers
Authentication	Google, Microsoft, and OpenID Connect sign-in; tokens; user registration
Global Settings	Runtime settings: ticket execution, AI jobs, budgets, hosts, Bash policy
Environment Variables	Process-level overrides and workspace-level variables
Models & Backends	Model catalog, custom models, backend credentials, command-line models
Database	Provider (SQLite / SQL Server / PostgreSQL), connection strings, migrations, backup
Storage	StoragePath layout, protection keys, sizing, backup
System Logs	Log viewer, log files, levels, retention

Reload semantics

Where a value is set determines whether a restart is required.

Change	Takes effect
appsettings.Production.json or process environment variables	After restarting the API or worker
Application settings (models, credentials, AI jobs, budgets, Bash policy, branding)	Immediately; pushed to Session Workers
Hosts page settings (concurrency, allowed workspaces, approval, IP restrictions)	Immediately
Workspace settings (repositories, variables, hooks, tasks, members, ticket configuration)	Immediately for new work

Permissions

Reading application settings requires View Settings; changing them requires Manage Settings. Administrators bypass these checks. See Permissions.