Models & Backends

This page configures the flat model catalog and credentials used by the built-in Polygent Code agent.

Polygent Code is the built-in AI coding agent that executes every session — there is no separate provider to install or select. Instead, you pick a model. Users choose a model per workspace, per session, per workflow, per ticket, or per bot from a single flat dropdown — there is no "choose a provider" step.

How models are selected

The model dropdown is one flat list. Operators configure the credentials required by the models they allow, and users pick from the visible model entries.

Model type	What operators configure
Cloud API models	The matching API key and, if needed, a custom base URL.
Subscription models	The subscription credential or local login required by that model.
Local models	The local runtime or command-line tool on the Session Worker host.

API keys entered in Settings are write-only after save and protected at rest. Polygent does not intentionally write raw credential values to application logs; operators must still prevent commands and external tools from printing secrets. Most Polygent Code controls apply consistently across directly hosted models; locally installed command-line models can have reduced control coverage depending on the local tool.

Where to Configure

Model configuration lives under Settings (the model catalog) and the Polygent Code page. Changes are persisted and take effect immediately — no API restart required. You can:

Setting	Purpose
Model Visibility Toggle	Hide unwanted models from selection dropdowns platform-wide
Custom Models	Add or remove model identifiers beyond the built-in catalog
Default Model	The system-wide model pre-selected in every model selector

Per-backend API keys and Base URLs are set on the Polygent Code Settings tab.

Model Visibility

The catalog ships with a default list of models. Toggle individual models off to hide them from the model dropdowns shown to users when starting sessions, configuring tickets, or running workflows. Hidden models stay configured for any existing references; only new selections are filtered.

Custom Models

If you need a model that isn't in the built-in catalog (e.g., a new release, a regional alias, or an internal proxy), add it under Custom Models:

1. Open the model configuration under Settings
2. Add the model identifier shown by your model vendor or internal gateway
3. Optionally set:
   • Supports image input (vision) — turn off for text-only models so image attachments degrade to a text note instead of being rejected.
   • Context window (tokens) — the model's context window size, used for the session context-usage indicator. Leave empty to use the built-in default of 200,000 tokens.
   • Effort levels — enter comma-separated values such as none,low,medium,high. Models with configured effort levels show an Effort selector when they are used.
4. The model appears in selection dropdowns immediately

Remove custom models the same way. Removing a model in active use leaves running sessions untouched but prevents new selections.

Polygent Code: project memory files

When a Polygent Code session starts, it can load one project memory file from the session worktree or the nearest parent directory. The file order depends on the session mode:

Session mode	Project memory order
Chat	AGENTS.chat.md → AGENTS.md → CLAUDE.md
Develop	AGENTS.dev.md → AGENTS.md → CLAUDE.md

Only the first matching project file is loaded. Polygent then adds global memory, if present, from ~/.config/polygent/AGENTS.md and ~/.claude/CLAUDE.md. Use mode-specific files when chat sessions and development sessions need different standing instructions; use CLAUDE.md or AGENTS.md as shared fallbacks.

Where Models Are Selected

Once models are configured, users pick one at:

Place	Purpose
Workspace defaults	Default model for the whole workspace
Session start	Override per session at creation time
Ticket configuration	Per-ticket model for the implementation step
Workflow steps	Override per Message / Ralph Loop step
Bot configuration	Bots are pinned to one model
Automation	Per-automation override
Insights (global setting)	Model used to extract insights
Merge Conflicts (global setting)	Model used for AI-assisted conflict resolution

Credentials

Credentials authorize model traffic from the session host; scope and distribute them only to hosts and workspaces that need them.

Polygent Code itself requires no separate provider installation. Direct API models authenticate with an API key supplied per host or workspace; models backed by local tools require those tools on each eligible session host. Set host credentials in the service account's environment, or workspace credentials under Environment Variables:

Credential	Authenticates
ANTHROPIC_API_KEY	Anthropic models
OPENAI_API_KEY	OpenAI models
GEMINI_API_KEY	Google Gemini models
OPENROUTER_API_KEY	OpenRouter models
GROQ_API_KEY	Groq models
CEREBRAS_API_KEY	Cerebras models

Set only the credentials for the models you actually use. Polygent does not intentionally log credential values. Commands, local tools, and external integrations can still print their environment, so review them before production use.

Endpoint and environment hardening

Provider endpoints and environment variables control where model credentials are sent. Treat any base URL override, inherited service environment variable, workspace environment variable, or local CLI configuration as part of the credential trust boundary.

Before running sessions against untrusted repositories or external content:

1. Review each configured Base URL and keep it pointed only at the intended model provider or an approved internal proxy.
2. Remove untrusted provider endpoint overrides from the service account, Session Worker host, workspace environment, and local CLI environment.
3. Run workers under a dedicated service account with a minimal, reviewed environment instead of inheriting an interactive user shell.
4. Set only the API keys required by the models that worker is allowed to run.

In Polygent's bring-your-own-key model, hosted model calls leave the Session Worker directly. If an endpoint override points a provider to the wrong host, your API key and model requests can be sent there before the model provider receives them. Credentials should only be sent to the providers or internal gateways you intended to trust.

Local command-line models

Some model entries use a locally installed command-line tool on the host that runs the session. Use this when your organization authenticates through a local subscription or an approved local runtime instead of a Polygent-managed API key.

Requirements and behavior:

• Install and sign in to the required command-line tool on every Session Worker host allowed to run that model.
• Verify tool restrictions, MCP access, budget behavior, and structured-output tasks before enabling the model for production workflows.
• Session output is shown in the normal Session view, but capabilities depend on the local tool.
• Kimi Code currently ignores MCP servers supplied through ACP. Configure required MCP servers in Kimi itself.

Polygent Code: local models (Ollama)

Polygent Code can drive a model running locally on your own machine through Ollama — no API key and no external service. The model runs on the host that executes the session (the API host, or the Session Worker host if the session is dispatched to a remote worker), and Polygent connects to Ollama on that machine at its default local address (http://localhost:11434).

Use this for offline, air-gapped, or zero-cost setups, or to keep code from leaving your network. Quality and tool-calling reliability depend entirely on the local model — smaller models may struggle with agentic (multi-tool) sessions and are more reliable in Chat mode.

Setup

Install and validate Ollama on every session host eligible to run the local model.

1. Install Ollama on the host that runs sessions and start its service.

2. Pull the model you want, e.g.:

   ollama pull gemma3:12b

   Confirm it is available with ollama list and that ollama run gemma3:12b responds.

3. Add the model under Custom Models, using the local model identifier required by your Ollama setup. The model tag must exactly match the tag from ollama list:

   Field	Value
   Model identifier	Your configured Ollama model identifier
   Supports image input	Off (unless the local model accepts images)
   Context window (tokens)	Set to the model's real window (leave empty for 200K)

4. The model appears in selection dropdowns immediately. Pick it when starting a session or configuring a bot.

Notes

• No credential is required — local Ollama needs no API key.
• The model identifier is passed through verbatim, so if ollama run {model-tag} fails on the host, the session will fail too. Always copy the tag exactly from ollama list.
• For remote sessions, Ollama and the pulled model must be installed on the Session Worker host, not on the machine running your browser.

Distributed Hosts

Polygent Code needs no install on a Session Worker. API keys must be present in the worker's environment for cloud models it will run. Local command-line tools and Ollama models must be installed and authenticated on each worker host allowed to run those models.

Troubleshooting

Symptom	Likely Cause
Model not in dropdown	Hidden via Model Visibility, or not in Custom Models — add it
API-key model fails	The matching API key is missing from the host/workspace environment
Local command-line model fails	The required local tool is not installed or not logged in on the host that runs the session
Ollama model fails	Ollama or the pulled model tag is missing on the session host — copy the tag from ollama list