Environment Variables

Environment variables exist at two levels: process variables that configure the API and workers at startup, and workspace variables that Polygent injects into session commands and tasks.

1. Process level — set in the operating-system or service environment of the API, Session Worker, or Deployment Worker. They override appsettings.json keys and take effect after a restart.
2. Workspace level — managed on the workspace Environment Variables tab and injected into that workspace's sessions, hooks, and tasks on every host.

Process level

Process variables override matching appsettings.json keys, using __ (double underscore) as the section separator — Database:Provider becomes Database__Provider. They take precedence over the file and are the recommended place for secrets.

# Windows Service: set variables for one service in its registry Environment value
reg add "HKLM\SYSTEM\CurrentControlSet\Services\Polygent" /v Environment /t REG_MULTI_SZ `
  /d "Database__Provider=PostgreSql\0Database__ConnectionString=Host=db;Database=polygent;Username=polygent;Password=secret\0Login__ClientSecret=..." /f
sc.exe stop Polygent
sc.exe start Polygent

# Linux / container
Database__Provider=PostgreSql
Database__ConnectionString="Host=db;Database=polygent;Username=polygent;Password=secret"
Login__ClientSecret=...
ASPNETCORE_FORWARDEDHEADERS_ENABLED=true

Restrict the service registry key, container definition, and appsettings.json to administrators and the service account.

App-level reference

These variables configure the API process. Defaults are the values used when the variable and the appsettings.json key are both absent.

Env var	appsettings.json path	Default	Purpose
Database__Provider	Database:Provider	Sqlite (shipped)	Sqlite, SqlServer, or PostgreSql. Blank or invalid prevents startup.
Database__ConnectionString	Database:ConnectionString	{StoragePath}/polygent.db	Provider-specific connection string.
StoragePath	StoragePath	service account's %APPDATA%\Polygent	Root directory for keys, logs, database, working copies. Set an absolute path.
ClientUrl	ClientUrl	https://localhost:5173	Public base URL used in links and MCP OAuth callbacks.
McpUrl	McpUrl	{ClientUrl}/mcp	MCP endpoint URL given to agents; must be reachable from every session host.
Login__LoginType	Login:LoginType	Google	Google, Microsoft, or OpenIdConnect.
Login__ClientId / Login__ClientSecret	Login:ClientId / Login:ClientSecret	empty	Identity-provider client credentials.
Login__ClientUrl	Login:ClientUrl	https://localhost:5173	Public URL users return to after sign-in.
Login__TenantId	Login:TenantId	empty	Microsoft tenant (common or a tenant ID).
Login__Authority	Login:Authority	empty	OpenID Connect issuer URL.
Login__OidcDisplayName / Login__OidcScopes	Login:OidcDisplayName / Login:OidcScopes	empty	OpenID Connect button label and extra scopes.
Login__EnableSeamlessSso	Login:EnableSeamlessSso	false	Microsoft only: skip the account picker.
Login__AllowNewUsers	Login:AllowNewUsers	true	Auto-register new users on first sign-in.
Login__AccessTokenMinutesLifetime	Login:AccessTokenMinutesLifetime	15	Access token lifetime (minutes).
Login__RefreshTokenDaysLifetime	Login:RefreshTokenDaysLifetime	7	Refresh token lifetime (days).
Login__EnableTestLogin	Login:EnableTestLogin	false	Evaluation-only email sign-in. Never enable in production — anyone can sign in as any user.
ShowChatInNewMenu / ShowDevelopInNewMenu	same	false	Show the built-in Chat / Develop cards in the sidebar New picker.
Tickets__SyncIntervalMinutes	Tickets:SyncIntervalMinutes	15	External ticket sync poll interval.
Tickets__EnableReadyForQaSummary	Tickets:EnableReadyForQaSummary	true (shipped false)	Generate an AI summary when a ticket enters QA.
ContentAssist__DefaultLanguage	ContentAssist:DefaultLanguage	Hebrew	Default Translate and Explain language (Arabic, English, Hebrew, Russian).
LocalHost__Enabled	LocalHost:Enabled	true	Run sessions inside the API process.
MergeWorktreePrefix	MergeWorktreePrefix	merge	Folder prefix for merge-conflict working copies.
MergeAiTimeoutSeconds	MergeAiTimeoutSeconds	1800	Per-attempt limit for AI conflict resolution, excluding capacity wait and merge hooks.
Git__LongRunningTimeoutSeconds	Git:LongRunningTimeoutSeconds	300	Timeout for clone, fetch, pull, push, staging, and working-copy operations.
Mcp__OAuth__AllowedPrivateHosts__0, __1, …	Mcp:OAuth:AllowedPrivateHosts	empty	Private-network hostnames that MCP servers may use.
Harness__DataDirectory or POLYGENT_HARNESS_DATA_DIR	Harness:DataDirectory	%USERPROFILE%\.polygent\harness	Agent transcript storage (outside StoragePath by default).
Harness__ClaudeConfigDirectory	Harness:ClaudeConfigDirectory	unset	Claude Code configuration folder for command-line models under a service account.
Logging__LogLevel__Default	Logging:LogLevel:Default	Information	Minimum log level. Other category keys are ignored.
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY	—	unset	Fallback model credentials when no key is saved in Backend Connections. See Models & Backends.
Urls / ASPNETCORE_URLS	Urls	http://localhost:5000	Listen addresses, separated by ;. The container image uses http://+:8080.
ASPNETCORE_FORWARDEDHEADERS_ENABLED	—	unset	Set to true behind a TLS-terminating reverse proxy so OAuth redirects use https.
ASPNETCORE_ENVIRONMENT	—	Production	Keep Production. Development disables HSTS and shows detailed error pages.

Session Worker variables

These configure a standalone Session Worker; they are top-level keys in its appsettings.json and take effect after restarting the worker.

Env var	Default	Purpose
ApiUrl	empty	Public base URL of the Polygent API.
ApiKey	empty	Session Worker host API key.
StoragePath	none — required	Worker data directory. The worker writes crash.log beside its executable and exits when this is blank. Must be unique per worker instance.
MaxConcurrentSessions	8	Seeds the host's session limit on first registration only; later changes are made on the Hosts page.
DisplayHostname	machine name	Name shown on the Hosts page.
ShutdownDrainTimeoutSeconds	600	How long a service stop waits for running sessions and hook tasks to finish. 0 stops immediately.
MergeWorktreePrefix	merge	Folder prefix for merge-conflict working copies on this worker.
Git__LongRunningTimeoutSeconds	300	Timeout for long Git operations.
Mcp__OAuth__AllowedPrivateHosts__0, …	empty	Private-network hostnames that MCP servers may use; keep in step with the API.
Harness__DataDirectory / Harness__ClaudeConfigDirectory	see above	Same as the API keys, for sessions on this worker.
Logging__LogLevel__Default	Information	Minimum log level.
Model provider keys	unset	Fallback only; keys saved in Backend Connections are delivered to workers automatically.

Deployment Worker variables

These configure a Deployment Worker; they live in the Agent section of its appsettings.json and take effect after restarting the worker.

Env var	Default	Purpose
Agent__Name	empty	Name shown on the Hosts page.
Agent__ServerId	empty (IP fallback)	Stable, unique worker identity.
Agent__MainServerUrl	empty	Public base URL of the Polygent API.
Agent__ApiKey	empty	Deploy Worker host API key.
Agent__StoragePath	worker install folder	Where slots are checked out and run.
Agent__DisableGitSslVerification	false	Disable Git certificate verification for worker-managed Git operations. Keep false.
Agent__HeartbeatIntervalSeconds	30	Keep the default; values near 60 make the host appear offline intermittently.
Agent__ReconnectDelaySeconds__0, …	1, 2, 5, 10, 30	Reconnect backoff sequence.
Logging__LogLevel__Default	Debug (shipped)	Set Information for production.

See Deployment Worker for details.

Workspace level

Workspace variables are managed in the application and injected into every session, hook, task, and agent command in the workspace, on local and remote hosts.

Configure

1. Open the workspace.
2. Open the Environment Variables tab (requires Edit Workspaces).
3. Add name/value pairs; mark sensitive values Secret.
4. Choose whether each variable is available to agent shell commands (Bash, on by default) and to agent web requests (WebFetch header, off by default).
5. Use Import / Export to move sets of variables (.env, appsettings.json, or YAML). Imported variables are not marked secret.

Reserved names

Names that control credentials, profiles, and trust are reserved and rejected for workspaces: home and profile folders (HOME, USERPROFILE, APPDATA, LOCALAPPDATA, XDG_*), agent tool configuration folders, model provider keys and base URLs (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, GEMINI_API_KEY, OPENROUTER_API_KEY, and similar), and TLS/CA controls (NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR, CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE). Configure model credentials in Models & Backends.

Security

Workspace variables are a secret and command-execution boundary.

• Variables are injected only into sessions of their own workspace.
• Secret values are encrypted at rest, masked in the UI, and never returned to the browser after saving.
• Polygent does not log variable values, but any command or agent can print them; treat printed values as disclosed.
• Prefer variables (or per-user tokens) over secrets in prompts, scripts, or commit messages.

Resolution order

When a session command or task starts, variables resolve in this order (later wins):

1. The host service's own environment.
2. Workspace environment variables.
3. Variables Polygent requires for the run; these cannot be overridden.

Workflow parameters that reference $env:VAR_NAME resolve against the workspace variables when the step runs and are written into the prompt text.

Per-user tokens (TFS PAT)

Azure DevOps / TFS can use a per-user, per-workspace personal access token saved under Profile → TFS Tokens. It is encrypted, not visible to other members, and never written to logs. See Ticket Sync.

See also

• Configuration Overview — appsettings.json keys
• Authentication — Login section keys
• Database — provider and connection string
• Storage — StoragePath