Skip to main content

Environment Variables

Environment variables provide restart-time overrides for services and runtime values for workspace jobs; treat both as part of the secret and command-execution boundary.

Polygent has two levels of environment variables:

  1. App-level — passed to the control-plane or worker process. 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 or service environment that hosts the control plane or worker. 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"

# Feature exposure (disabled by default)
ShowChatInNewMenu="false"
ShowDevelopInNewMenu="false"

# Local session host
LocalHost__Enabled="true"

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

# Merge conflict tuning
MergeWorktreePrefix="merge"
MergeAiTimeoutSeconds="<seconds>"

# Long-running Git operations, including staging (default: 300 seconds)
Git__LongRunningTimeoutSeconds="300"

# Remote Session Worker compatibility; change only during coordinated upgrades
HostProtocolVersion__MinSupported="6"
HostProtocolVersion__Current="6"

# 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
Git__LongRunningTimeoutSecondsGit:LongRunningTimeoutSecondsTimeout for staging, clone, fetch, pull, push, and worktree operations (default: 300 seconds)
ClientUrlClientUrlPublic client URL (overrides Settings UI value)
McpUrlMcpUrlMCP endpoint URL. use HTTPS and restrict reachability to trusted worker networks.
ShowChatInNewMenuShowChatInNewMenuShow the built-in Chat card in the sidebar "New" picker. Hidden by default (false).
ShowDevelopInNewMenuShowDevelopInNewMenuShow the built-in Develop card in the sidebar "New" picker. Hidden by default (false).
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__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 an AI summary when a ticket enters QA. Shipped config sets this to false; if omitted, the application default is true.
HostProtocolVersion__MinSupportedHostProtocolVersion:MinSupportedMinimum remote Session Worker protocol version accepted by the API; change only during coordinated upgrades.
HostProtocolVersion__CurrentHostProtocolVersion:CurrentAPI protocol version advertised to remote Session Workers; change only during coordinated upgrades.
LocalHost__EnabledLocalHost:EnabledLocal session host on/off
MergeWorktreePrefixMergeWorktreePrefixMerge worktree directory prefix
MergeAiTimeoutSecondsMergeAiTimeoutSecondsAI conflict resolution timeout, excluding capacity wait
Logging__LogLevel__DefaultLogging:LogLevel:DefaultMinimum log level (only this key is applied at runtime)

Session Worker Variables​

These variables configure a standalone host that executes sessions; restart the worker after changing them.

Session Worker configuration can also be supplied through environment variables on the worker host.

Env varPurpose
ApiUrlBase URL of the Polygent API.
ApiKeySession-type host API key.
StoragePathWorker data directory for session workspaces and local runtime data.
MaxConcurrentSessionsInitial seed for a newly registered host; subsequent changes are made on the Hosts page.
DisplayHostnameOptional friendly worker name shown in the app.

Deployment Worker Variables​

These variables configure a standalone host that runs deployment slots; restart the worker after changing them.

Deployment Worker configuration can also be supplied through environment variables on the deployment host.

Env varPurpose
Agent__NameFriendly name shown on the Hosts page.
Agent__ServerIdUnique per-worker identity; falls back to the IP address when unset.
Agent__MainServerUrlBase URL of the Polygent API.
Agent__ApiKeyDeploy-type host API key.
Agent__StoragePathWorking directory where deployed slots are checked out and run.
Agent__HeartbeatIntervalSecondsWorker heartbeat interval. Keep the shipped value unless Support directs a change.
Agent__ReconnectDelaySeconds__NIndexed reconnect backoff values. Keep the shipped sequence unless Support directs a change.

Workspace-Level​

Workspace environment variables are managed in the Settings UI and injected into every session, hook, task, and agent invocation that runs inside the workspace. They apply uniformly to local and remote session hosts.

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 Anthropic models
GEMINI_API_KEYAPI key for Google Gemini models
OPENAI_API_KEYAPI key for OpenAI models
Project secrets (DB URL, build flags, etc.)Passed to scripts and tasks during sessions

The agent reads model 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. Never returned to other users or written to logs. See the Tickets sync guide.

Security​

  • Variables are scoped to the workspace they belong to and never injected into sessions in other workspaces
  • Values flagged secret are masked in the UI and never returned in plaintext to the browser after saving
  • 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-worker runs)
  2. App-level overrides from appsettings.json / launch environment
  3. Agent defaults applied for the selected model backend
  4. Workspace environment variables (override any of the above)
  5. Required agent runtime variables — reserved values take precedence and cannot be overridden by a workspace

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​