Models & Backends

This page configures the model catalog and the credentials that the built-in Polygent Code agent uses to reach model providers.

Polygent Code is the only agent — there is no provider to install or select. Users pick a model from one list; operators decide which models appear and supply the credentials those models need.

Where to configure

All model configuration is on Developer Tools → PolygentCode → Settings. Viewing requires View Settings; saving requires Manage Settings. Changes apply immediately without a restart and are pushed to connected Session Workers.

Section	Purpose
Model Configuration	Built-in model visibility, the four default model tiers, and custom models.
Backend Connections	One row per model backend with an API Key and an optional Base URL override.

Model catalog

The catalog is the list of models users can select.

• Built-in Models — select the eye icon to hide or show a model in every model dropdown. A model assigned to a default tier cannot be hidden. Hidden models remain valid for existing sessions, tickets, and bots; only new selections are filtered.
• Default model tiers — Max (Challenges), High (Complex tasks), Default (Daily use), and Instant. Each tier stores a model and, where supported, a reasoning effort. Every model selector lists the tiers first. See Global Settings → Default Model Tiers.
• Free models — models with no usage charge are hidden unless the API setting ShowFreeModels is true (default false). Restart the API after changing it.

Custom models

Add a custom model when a model you need is not in the built-in catalog.

1. Open Model Configuration and add a custom model.
2. Enter a Display Name, choose the Backend, and enter the Model ID exactly as the provider publishes it. The ID is validated for the selected backend.
3. Optionally set:
   • Supports image input (vision) — turn off for text-only models so image attachments degrade to a text note.
   • Context window (tokens) — used for the context indicator and history trimming. Empty uses 200,000.
   • Effort levels — comma-separated values such as none,low,medium,high; an Effort selector appears when the model is used.
   • Cost classification and Pricing — per-token input, output, and cache prices, or Free / Unmetered.
4. Save. The model appears in selection dropdowns immediately.

A custom model left at Unknown cost is blocked whenever any AI cost budget applies, because its spend cannot be measured. Set pricing, or classify it as Free or Unmetered, before using it under a budget. Removing a custom model leaves running sessions untouched but prevents new selections.

Credentials

Credentials authorize model traffic from whichever host runs the session — the API host for local sessions, or a Session Worker.

A backend's credential is resolved in this order:

1. The API Key saved in Backend Connections. Saved keys are write-only, masked after saving, encrypted at rest, and distributed to Session Workers automatically.
2. The matching environment variable in the service environment of the host that runs the session.

Backend	Environment variable fallback
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
Gemini	GEMINI_API_KEY
OpenRouter	OPENROUTER_API_KEY

For OpenAI models, a signed-in ChatGPT/Codex subscription (codex login under the host's service account) is used before the OpenAI API key when it is valid.

Model credentials cannot be set as workspace environment variables — those names are reserved and rejected. Set only the credentials for the models you allow; Polygent does not write credential values to its logs, but commands and external tools can print their own environment.

AWS Bedrock

Bedrock models run in your own AWS account. Credentials come from static keys, a named AWS profile, or the AWS SDK default credential chain (including instance roles), with optional role assumption; the region must be configured explicitly. Bedrock configuration is not exposed in the UI — contact Polygent Support to enable it for your installation.

Endpoint and environment hardening

Base URLs and service environment variables decide where model credentials are sent, so treat them as part of the credential trust boundary.

Before running sessions against untrusted repositories or external content:

1. Review every Base URL in Backend Connections and keep it pointed only at the intended provider or an approved internal gateway.
2. Run the API and every Session Worker under a dedicated service account with a minimal, reviewed environment instead of an interactive user profile.
3. Set only the API keys that host is allowed to use.

Hosted model calls leave the host that runs the session directly, using your key. A wrong Base URL sends your key and prompts to that host.

Local command-line models

Some catalog entries run through a command-line coding tool installed on the session host, authenticated with that tool's own subscription login instead of a Polygent API key.

Tool	Install	Sign in (as the service account)
Claude Code	Install Claude Code	claude auth login
Codex	npm install -g @openai/codex	codex login
OpenCode	npm install -g opencode-ai	opencode auth login
Kimi Code	npm install -g @moonshot-ai/kimi-code	kimi login

1. Install the tool on every host allowed to run the model, on the service account's PATH.
2. Sign in while running as the service account of the API or Session Worker. An interactive login under another account is not visible to the service.
3. For Claude Code under a service account, you can point the API or worker at a specific configuration folder with Harness:ClaudeConfigDirectory (absolute path).
4. Restart the worker (or wait for the hourly capability refresh) and confirm the tool shows Ready under Backend readiness on the Hosts page. Other states: Missing, Unauthenticated, Expired, Subscription required, Incompatible, Probe error — each with remediation text.

A session is rejected before its working copy is created when no eligible host is ready for the selected command-line model. The local tool owns parts of execution, so tool restrictions, budgets, and guards can behave differently; see Where local command-line models differ.

Project memory files

Polygent Code loads standing instructions from repository files and from the host account's home folder at the start of each session.

Session mode	File looked for in each directory
Chat	AGENTS.chat.md → AGENTS.md → CLAUDE.md
Develop	AGENTS.dev.md → AGENTS.md → CLAUDE.md

The first matching file in each directory, from the repository root down to the session working directory, is loaded and combined (up to 1 MiB in total). Global memory files ~/.config/polygent/AGENTS.md and ~/.claude/CLAUDE.md are then added from the home folder of the account running the session host. Both sources can be turned off under User Settings → Context loading.

Where models are selected

Once models are configured, users pick one at these points.

Place	Purpose
Session start	Model for a new session; can be changed during a session unless locked.
Ticket start and templates	Implementation model and optional Plan model.
Workflow Message / Ralph Loop	Per-step override.
Bot configuration	Starting model; Lock Model prevents changes.
Automation	Per-automation model.
Subagent	A tier, a fixed model, or Inherit from parent.
Global settings	Insights, AI conflict resolution, code review, and verification models.

Troubleshooting

Symptom	Likely cause and fix
Model not in dropdown	Hidden in Built-in Models, a free model with ShowFreeModels off, or not added as a custom model.
API-key model fails to authenticate	No key in Backend Connections and no matching environment variable on the host that ran the session.
Workspace variable for a key is rejected	Model keys are reserved names; save the key in Backend Connections.
Custom model blocked by budget	Its cost is Unknown; set pricing or classify it as Free or Unmetered.
Command-line model rejected at start	No host reports the tool Ready; follow the remediation on Hosts and sign in as the service account.
Requests go to an unexpected endpoint	Review the Base URL override for that backend.