Global Settings
Global settings control platform-wide scheduling, model jobs, worker admission, safety controls, branding, and budgets.
The Settings area exposes platform-wide configuration that is not tied to a single workspace. These values affect every workspace, every session, and every queue. Permissions: settings.view to read, settings.manage to change (admins always have access).
Where to Find It
Sidebar → Settings → Global. All values are persisted in the database (or in appsettings.json where noted) and take effect immediately, without restarting the API.
Tickets Queue
| Setting | Default | Description |
|---|---|---|
| Low Priority Execution Hour | 2 | Hour of the day (0–23, server local time) when low-priority ticket work is eligible to run, including starts, rejection resumes, hooks, reports, and follow-up messages. Low work runs after High and Normal work. |
AI ticket concurrency is configured per host: each session host has its own Max Concurrent Tickets value, set on the Hosts page. For each queued ticket the gate looks for a host that can actually run it — workspace-allowlist-compatible, able to run the selected model, online, with at least one free slot under its own cap. If no host fits, the ticket waits. To raise overall throughput, enable more hosts or raise individual host caps; to dedicate a host to specific workspaces, set its allowlist.
Polygent Code Models
Backend connection API keys configured for Polygent Code are write-only in the UI, masked after saving, and protected at rest in the settings file.
Default Model
| Setting | Default | Description |
|---|---|---|
| Default Model | First available model | System-wide default model and, when supported, reasoning effort. |
Pick a Default Model to have it automatically selected everywhere a model is chosen — Create Session, Bots, Plans, Round Tables, Automations, Start Ticket templates, and more. Models with configurable reasoning expose their available effort levels; the selected model and effort are saved together. Models without configurable effort remain directly selectable.
Several selectors also offer an explicit "Default" choice in the model dropdown (for example the Bot form and Start Ticket templates). Picking "Default" means follow the system-wide model and reasoning effort rather than pinning a specific combination.
If a saved model or effort is no longer available because the model was hidden, removed, or filtered by free-model visibility, settings require an available default and normalize stale values to the first available model. Job-specific model settings below override the global default when set; when left as Default, they inherit the system-wide model and effort.
Insights
| Setting | Default | Description |
|---|---|---|
| Insights Enabled | true | Master switch for auto-extraction of insights from completed Develop sessions. |
| Insights Model | default | Model used to extract Insights. Pick a low-cost, fast model — extraction is short and high-volume. |
Merge Conflicts
| Setting | Default | Description |
|---|---|---|
| Merge Conflicts Model | default | Model used for AI-assisted merge conflict resolution. Pick one strong at code reasoning. |
| Manual Merge Conflicts | false | When true, AI resolution is skipped and every conflict goes straight to the review diff editor. |
| Tools | Defaults | Restrict MCP servers, Polygent MCP tools, custom subagents, skills, and agent tools for AI conflict resolution. Hidden when manual mode is on. |
Code Review
| Setting | Default | Description |
|---|---|---|
| Code Review Enabled | false | Run an automated code review pass on completed sessions. |
| Code Review Model | default | Model used for code review. Defaults to the workspace's session model when unset. |
| Tools | Read, Glob, Grep | Restrict MCP servers, Polygent MCP tools, custom subagents, skills, and agent tools for separate code review runs. |
When Code Review is enabled, two always-on deterministic scans run alongside the AI pass and are not configurable: a secret scan for committed credentials and a duplicate-code scan for functions copied from elsewhere in the codebase. Their findings are always included regardless of the model chosen. See Code Review for details.
Verification
| Setting | Default | Description |
|---|---|---|
| Verification Enabled | false | Run an automated verification pass when the agent finishes (before Code Review). |
| Verification Model | default | Model used for verification. |
| Tools | Read, Glob, Grep | Restrict MCP servers, Polygent MCP tools, custom subagents, skills, and agent tools for separate verification runs. |
Round Table
| Setting | Default | Description |
|---|---|---|
| Tools | Built-in defaults | Restrict MCP servers, Polygent MCP tools, custom subagents, skills, and agent tools for round tables. |
Plan
| Setting | Default | Description |
|---|---|---|
| Tools | Provider defaults | Restrict MCP servers, Polygent MCP tools, custom subagents, skills, and provider tools for plans. |
Hosts Settings
The following settings live on the Hosts page, not on the global Settings page. They control host-related behavior, capacity, agent approval, worktree pooling, and network allow-lists.
Per-Host Concurrency
Open a session host's Manage → Concurrency editor to set its maximum concurrent tickets, sessions, merge-AI processes, and hook tasks. Each value must be a whole number of at least 1. Saving applies all four values together, so a failed request leaves the previous configuration unchanged. Changes apply to subsequent work immediately without restarting the API; work already admitted continues under its previous capacity.
Agent Approval
| Setting | Default | Description |
|---|---|---|
| Require Admin Approval for Agents | true | When enabled, newly registered Deploy and Session Workers must be approved by an admin on the Hosts page before they can pick up work. |
Worktree Pool
| Setting | Default | Description |
|---|---|---|
| Enable Idle Worktree Reuse Pool | false | Keep idle worktrees around so new sessions can grab a pre-cloned tree instead of cloning fresh. |
| Idle Worktree Pool Size | 3 | How many idle worktrees to keep per workspace when the pool is enabled. |
| Idle Worktree Max Age | none | If set, idle worktrees older than this duration are evicted from the pool. |
IP Restrictions
| Setting | Default | Description |
|---|---|---|
| Session Workers | empty | Allowed IPs / wildcard patterns (e.g. 192.168.*.*) that can connect to the session-worker hub. Empty = allow all. |
| Deployment Workers | empty | Same, but for the deployment-worker hub. |
Bash Permissions
The global blocked-bash-command rules live on the Polygent Code → Permissions tab (Sidebar → Dev Tools → Polygent Code) and let administrators block dangerous shell commands across every Polygent Code session. Each rule is a pattern plus an optional reason; when a session's shell-tool call matches a rule, the command is rejected before it runs and the agent receives the reason so it can adapt.
| Pattern form | Example | Matches |
|---|---|---|
| Substring | git push | Any command containing git push (case-insensitive). |
Glob (* / ?) | git push* | git push, cd x && git push --force, etc. |
Regex (/.../) | /^rm\s+-rf/ | A command starting with rm -rf. |
Rules defined here are global — they apply to all workspaces and every Polygent Code session. Requires the Manage Settings permission.
Read-Only (from appsettings.json)
These show in the Settings UI for visibility but are configured in appsettings.json and require an API restart to change.
| Setting | Source | Description |
|---|---|---|
| Client URL | appsettings.json: ClientUrl (or env ClientUrl) | Base URL of the React client. Used for shared links, public bot URLs, and OAuth redirects. Falls back to the request URL if unset. |
| MCP URL | appsettings.json: McpUrl (or env McpUrl) | Public URL advertised for the MCP endpoint when generating agent MCP configurations. |
| Database Provider | appsettings.json: Database:Provider | Active database provider (read-only here — see Database). |
AI Cost Budgets
The global monthly spend cap and the warning threshold are configured under Settings → General → Global AI Cost Budget. When a global budget is set it is always enforced. These are documented in full in the AI Cost Budgets guide.
Branding
The custom logo and main accent color are configured under Settings → Branding. See the Branding guide.
Model Configuration
The model catalog appears in the Settings UI with model visibility toggles and custom models. See Models & Backends.
See Also
- Models & Backends — model catalog, backends, and custom models
- System Logs — runtime logging configuration
- Authentication — OAuth and JWT settings
- Environment Variables — workspace-level secrets and config