Skip to main content

Environment Variables

Polygent has two levels of environment variables:

  1. App-level — passed to the API/Agent processes themselves. Used to override appsettings.json values.
  2. Workspace-level — managed in the Settings UI and injected into every session that runs in a workspace.

App-Level​

App-level variables come from the operating system / service environment that hosts the API or Agent. They override matching keys in appsettings.json using __ (double underscore) as the section separator.

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

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

# Override the bind URL (ASP.NET Core convention)
Urls="http://0.0.0.0:5000"

# OAuth credentials (recommended over committing to appsettings.json)
Login__LoginType="Google"
Login__ClientId="..."
Login__ClientSecret="..."
Login__ClientUrl="https://polygent.example.com"

# Microsoft tenant (Microsoft only)
Login__TenantId="common"

# Public URLs advertised to clients / MCP consumers
ClientUrl="https://polygent.example.com"
McpUrl="https://polygent.example.com/mcp"

# Local in-process session host
LocalHost__Enabled="true"
LocalHost__MaxConcurrentSessions="16"

# Ticket sync interval (minutes) and ready-for-QA summary toggle
Tickets__SyncIntervalMinutes="15"
Tickets__EnableReadyForQaSummary="false"

# Merge conflict tuning
MergeWorktreePrefix="merge"
MergeAiTimeoutSeconds="1800"

# Log level (only the Default key is applied at runtime)
Logging__LogLevel__Default="Information"

This is the recommended path for secrets in container and Windows-Service deployments — keep appsettings.json checked-in-safe and inject credentials via the environment.

App-Level Reference​

Env varappsettings.json pathPurpose
Database__ProviderDatabase:ProviderSqlite / SqlServer / PostgreSql
Database__ConnectionStringDatabase:ConnectionStringProvider-specific connection string
StoragePathStoragePathRoot directory for keys, logs, worktrees, DB
ClientUrlClientUrlPublic client URL (overrides Settings UI value)
McpUrlMcpUrlPublic MCP endpoint URL
Login__LoginTypeLogin:LoginTypeGoogle, Microsoft, or OpenIdConnect
Login__ClientId / ClientSecretLogin:ClientId / Login:ClientSecretOAuth provider credentials
Login__TenantIdLogin:TenantIdMicrosoft tenant (common or specific GUID)
Login__ClientUrlLogin:ClientUrlOAuth redirect base URL
Login__EnableTestLoginLogin:EnableTestLoginBypass OAuth for testing — never enable in production
Login__EnableSeamlessSsoLogin:EnableSeamlessSsoSuppress OAuth account picker
Login__AllowNewUsersLogin:AllowNewUsersAllow first-time users to auto-register
Login__AccessTokenMinutesLifetimeLogin:AccessTokenMinutesLifetimeJWT TTL (minutes)
Login__RefreshTokenDaysLifetimeLogin:RefreshTokenDaysLifetimeRefresh token TTL (days)
Tickets__SyncIntervalMinutesTickets:SyncIntervalMinutesExternal ticket sync poll interval
Tickets__EnableReadyForQaSummaryTickets:EnableReadyForQaSummaryGenerate AI summary when entering QA stage
LocalHost__EnabledLocalHost:EnabledIn-process session host on/off
LocalHost__MaxConcurrentSessionsLocalHost:MaxConcurrentSessionsPer-host concurrent session cap (default 16)
MergeWorktreePrefixMergeWorktreePrefixMerge worktree directory prefix
MergeAiTimeoutSecondsMergeAiTimeoutSecondsAI conflict resolution timeout
Logging__LogLevel__DefaultLogging:LogLevel:DefaultMinimum log level (only this key is applied at runtime)

Workspace-Level​

Workspace environment variables are managed in the Settings UI and injected into every session, hook, task, and provider CLI invocation that runs inside the workspace. They apply uniformly to both local and remote session agents — the variables travel with each user message over the same channel that carries the message itself, so a remote agent worker sees the same environment as an in-process one.

Configure​

  1. Open your workspace
  2. Open Settings → Environment Variables
  3. Add key-value pairs
  4. Use Import / Export to move sets of variables between workspaces or dump them to JSON for backup

Common Workspace Variables​

VariablePurpose
ANTHROPIC_API_KEYAPI key for Claude Code
GEMINI_API_KEYAPI key for Gemini CLI
OPENAI_API_KEYAPI key for Codex / OpenCode (when using OpenAI)
QWEN_API_KEYAPI key for Qwen Code
Project secrets (DB URL, build flags, etc.)Passed to scripts and tasks during sessions

Provider CLIs read their own credentials from the environment; setting them at the workspace level is the cleanest way to scope keys per project.

Per-User Environment Values (TFS PAT)​

Azure DevOps / TFS access uses a per-user, per-workspace PAT stored under the user's Profile. Unlike workspace env vars, these are not visible to other workspace members. Encrypted at rest, max 500 chars. See the Tickets sync guide.

Security​

  • Workspace env vars are encrypted at rest
  • Variables are scoped to the workspace they belong to and never injected into sessions in other workspaces
  • Polygent never logs variable values
  • Prefer environment variables (or per-user PATs) over inline secrets in prompts, scripts, or commit messages

Variable Resolution Order​

When an agent process starts, environment variables resolve in this order (later wins):

  1. The host's OS environment (where the API or session-agent worker runs)
  2. App-level overrides from appsettings.json / launch environment
  3. Provider defaults applied for the selected agent
  4. Workspace environment variables (override any of the above)
  5. Provider-managed internal variables — these always win so each provider's configuration contract with its CLI is preserved

Workflow init parameters that reference $env:VAR_NAME resolve against the merged workspace environment at workflow-build time and are baked into the resulting prompt, separately from the process-level injection above.

See Also​