Installation

This guide installs the control plane and optional workers, persists their state, and prepares production authentication and TLS.

Prerequisites

Requirement	Why
.NET 10 Runtime	Runs Polygent and optional workers
Git 2.20+	Worktree isolation per session
`appsettings.production.json`	Production configuration placed alongside the executable
TLS certificate trusted by users and workers	Serves production access over HTTPS and protects authentication cookies and host credentials
Windows Service host	Runs the API and workers as managed services (`sc.exe`)
Git PAT (Personal Access Token)	Authenticates clone/fetch/push against your remote Git host

The built-in Polygent Code agent works out of the box — no agent CLI install is required to run your first session. You pick a model and supply its credentials.

Models

Polygent Code is the only agent — there is no separate provider to install. You pick a model from a single flat dropdown and supply its credentials:

Cloud API models — set the matching API key for the models you use
Subscription models — configure the subscription credential or local login required by that model
Local models via Ollama — no key, runs on the session host

See Models & Backends for the full model catalog and credential reference.

Components

Polygent ships one main application and two optional workers:

Component	Description	Deployed As
System	Web application, API, live updates, and static client	Windows Service (recommended) or a long-running process
Session Worker	Worker service that executes AI sessions on remote machines (parallel session distribution)	Windows Service
Deployment Worker	Worker service that executes slot deployments on target machines	Windows Service

The API can execute sessions locally, so Session Workers are optional. Add a Session Worker to isolate or scale session execution. Deployment slots always require a connected Deployment Worker, which can run on the control-plane machine or another trusted host.

Installation methods

Windows Service (recommended)

The recommended deployment method for production Windows environments. Use versioned release artifacts from your Polygent distribution channel, run services under dedicated service accounts, and grant write access only to the configured storage paths.

API Server

sc.exe syntax: a space is required after each = (binPath= "..."), and none before it. This is a quirk of sc.exe, not a typo.

sc.exe create Polygent binPath= "C:\Polygent\<server executable>" start= auto
sc.exe description Polygent "Polygent Server"
sc.exe start Polygent

Session Worker Service

The Session Worker is deployed separately on machines that will execute AI sessions:

sc.exe create PolygentSessionWorker binPath= "C:\Polygent\<session worker executable>" start= auto
sc.exe description PolygentSessionWorker "Polygent Session Worker Service"
sc.exe start PolygentSessionWorker

Deployment Worker Service

The Deployment Worker is deployed on machines that will execute slot deployments:

sc.exe create PolygentDeploymentWorker binPath= "C:\Polygent\<deployment worker executable>" start= auto
sc.exe description PolygentDeploymentWorker "Polygent Deployment Worker Service"
sc.exe start PolygentDeploymentWorker

Place the supplied appsettings.json alongside each executable and edit only that component's documented settings. Use an absolute, writable StoragePath; configure the API public URL, database, and production identity provider before starting services. See Configuration.

Managing the service

# Stop the service
sc.exe stop Polygent

# Start the service
sc.exe start Polygent

# Check status
sc.exe query Polygent

Service logs are written to the configured StoragePath/logs/ directory. Configure log levels in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Docker

Run Polygent in containers for cross-platform deployment. Contact your Polygent operator for the container registry URL and credentials needed to pull the images.

The container listens on port 8080. Configuration is supplied entirely through environment variables (the same keys as appsettings.json, with __ as the section separator).

Single-machine (all-in-one)

services:
  api:
    image: polygent-api:latest
    container_name: polygent-api
    ports:
      - "8080:8080"
    volumes:
      - polygent-data:/data
      - /path/to/your/repos:/repos
    environment:
      - StoragePath=/data
      - Database__Provider=Sqlite
      # - Database__ConnectionString=        # leave unset for SQLite under /data
      - Login__LoginType=Google
      # - Login__ClientId=
      # - Login__ClientSecret=
      # - Login__ClientUrl=https://polygent.example.com
      # - ClientUrl=https://polygent.example.com
    restart: unless-stopped

volumes:
  polygent-data:

Run with:

docker compose up -d

Validate locally at http://localhost:8080, then place the service behind the production HTTPS endpoint before user access.

Volumes

Mount	Purpose
`polygent-data`	Persistent `StoragePath`: database, keys, logs, and worktrees
`/repos`	Optional: local Git repositories for workspace access

With PostgreSQL

services:
  api:
    image: polygent-api:latest
    container_name: polygent-api
    ports:
      - "8080:8080"
    volumes:
      - polygent-data:/data
    environment:
      - StoragePath=/data
      - Database__Provider=PostgreSql
      - Database__ConnectionString=Host=db;Port=5432;Database=polygent;Username=polygent;Password=secret
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=polygent
      - POSTGRES_USER=polygent
      - POSTGRES_PASSWORD=secret

volumes:
  polygent-data:
  postgres-data:

Split deployment (separate workers)

For a multi-machine setup, run Polygent on one host and point worker containers at it using the public API base URL and an admin-issued Host API Key from Hosts → API Keys. Workers authenticate with that key — there is no shared secret to configure on the API side.

Podman compatibility

The provided container images run unchanged on Podman 4.4+ via podman compose up. Docker remains the primary supported runtime; Podman is offered for environments that require a rootless or daemonless runtime (e.g. RHEL/Fedora hosts, policies that forbid a root daemon, or sites avoiding Docker Desktop licensing).

Storage layout

The API writes to a single configurable StoragePath. It contains:

The SQLite database (when SQLite is the configured provider)
Signing keys (auto-generated RSA keys for JWT)
System logs
Per-session worktrees and uploads

Back up StoragePath and the configured database as one recovery set. For SQLite, use a SQLite-consistent backup while writes are stopped or quiesced; copying a live database file alone is not a reliable backup.

Authentication setup

Production authentication uses one external identity provider. Pick one and set it under the Login section of appsettings.json (or via environment variables). Only one provider is active at a time. The first user to sign in becomes the Admin.

For each provider, register the matching redirect URI at your identity provider, substituting your public client URL for {ClientUrl}.

Google OAuth2

{
  "Login": {
    "LoginType": "Google",
    "ClientId": "your-client-id.apps.googleusercontent.com",
    "ClientSecret": "your-client-secret",
    "ClientUrl": "https://polygent.example.com"
  }
}

Redirect URI to register: {ClientUrl}/signin-google

Microsoft OAuth2 (Microsoft 365 / Entra ID)

{
  "Login": {
    "LoginType": "Microsoft",
    "ClientId": "your-application-id",
    "ClientSecret": "your-client-secret",
    "TenantId": "common",
    "ClientUrl": "https://polygent.example.com"
  }
}

Redirect URI to register: {ClientUrl}/signin-microsoft. Use common as TenantId to allow any Microsoft account, or a specific tenant GUID to restrict sign-in to your organization.

Generic OpenID Connect (Okta / Auth0 / Keycloak)

Register an OIDC client at your identity provider, then point Polygent at the issuer URL — it discovers endpoints automatically:

{
  "Login": {
    "LoginType": "OpenIdConnect",
    "Authority": "https://your-tenant.okta.com/oauth2/default",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "OidcDisplayName": "Okta",
    "ClientUrl": "https://polygent.example.com"
  }
}

Redirect URI to register: {ClientUrl}/signin-oidc.

See Authentication for the full Login reference, including all OIDC options.

JWT signing keys (RS256) are auto-generated under StoragePath on first run. Access tokens are valid for 15 minutes; refresh tokens last 7 days. Tokens use HttpOnly Secure SameSite=Lax cookies and rotate on each refresh.

Add a Session Worker (optional)

A Session Worker lets you run AI sessions on a separate machine, spreading load across hosts. The API can host sessions itself, so this is only needed when you want to scale out.

Polygent Code needs no install on the worker. Model 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.

Mint a host API key. In the app, open Hosts → API Keys → Create, choose host type Session, set an expiration, and copy the plaintext token (shown once).
Extract the Session Worker release onto the worker machine.

Configure appsettings.json next to the executable:

{
  "ApiUrl": "https://polygent.example.com",
  "ApiKey": "<the token from step 1>",
  "StoragePath": "C:\\Polygent\\session-worker-data",
  "MaxConcurrentSessions": 8,
  "DisplayHostname": "worker-01"
}

Key	Purpose
`ApiUrl`	Base URL of your Polygent API
`ApiKey`	Session-type host API key
`StoragePath`	Worktree/log directory — required, the agent refuses to start if blank
`MaxConcurrentSessions`	Initial cap seed used only on first registration (default 8); edit it later on Hosts
`DisplayHostname`	Friendly name shown on the Hosts page (defaults to the machine hostname when blank)

After the worker first registers, open Hosts → Manage → Concurrency to set its authoritative session, ticket, merge-AI, and hook-task limits.

Install as a Windows Service (same sc.exe pattern as the API):

sc.exe create PolygentSessionWorker binPath= "C:\Polygent\<session worker executable>" start= auto
sc.exe start PolygentSessionWorker

Confirm registration. The worker should report Online on the Hosts page within a minute. If Require Admin Approval for Workers is enabled (Hosts → Settings, default on), it appears disabled until an admin enables it.
Scope it (optional). Set the host's workspace allowlist to dedicate it to specific teams, and set its Max Concurrent Tickets to control how much queued ticket work it picks up.

Add a Deployment Worker (optional)

A Deployment Worker runs slot deployments (QA/demo/staging builds) on a target machine. Install it where the deployed app should run.

Mint a host API key. In Hosts → API Keys → Create, choose host type Deploy and copy the token.
Extract the Deployment Worker release onto the target machine.

Configure appsettings.json:

{
  "Agent": {
    "Name": "deploy-01",
    "MainServerUrl": "https://polygent.example.com",
    "ApiKey": "<the token from step 1>",
    "StoragePath": "C:\\Polygent\\deploy-worker-data",
    "DisableGitSslVerification": false
  }
}

Key	Purpose
`Agent:Name`	Friendly name shown on the Hosts page
`Agent:MainServerUrl`	Base URL of your Polygent API
`Agent:ApiKey`	Deploy-type host API key
`Agent:StoragePath`	Working directory for deployed slots and their logs
`Agent:DisableGitSslVerification`	Disables certificate verification only for worker-managed Git operations; defaults to `false`

Keep Agent:DisableGitSslVerification false or omit it whenever Git can validate the server certificate. Setting it to true covers worker-managed clone, fetch, pull, push, remote validation, branch listing, and remote branch checks for both new and existing checkouts. It does not affect Git commands in deployment templates or change browser or operating-system trust. Disabling verification permits interception of repository content and credentials; enable it only when you explicitly accept that risk for a known internal Git server. The worker logs a security warning at startup without logging repository credentials.

Install as a Windows Service:

sc.exe create PolygentDeploymentWorker binPath= "C:\Polygent\<deployment worker executable>" start= auto
sc.exe start PolygentDeploymentWorker

Confirm registration on the Hosts page, then add deployment slots on the host (workspace, initial/startup/shutdown commands, environment variables). See the Deployment Worker guide.

Both workers connect outbound to Polygent over HTTPS and report availability — Polygent never opens inbound connections to a worker host. A worker is marked Offline after a short period without contact.

Reverse proxy notes

If you front the API with IIS, Nginx, or another reverse proxy:

Forward Upgrade and Connection headers so live updates can negotiate WebSockets
Preserve the original host and scheme for OAuth return-URL validation
Allow large file uploads (workspace clones, ticket attachments up to 10 MB, IDE upload zips)

Next steps

Quick Start — create your first workspace and session
Operator hardening checklist — work through it before exposing the instance beyond a trusted network
Core Concepts — learn the Polygent vocabulary
Configuration → Models & Backends — configure model backends and API keys
System Requirements — hardware, software, and network details

Prerequisites​

Models​

Components​

Installation methods​

Windows Service (recommended)​

API Server​

Session Worker Service​

Deployment Worker Service​

Managing the service​

Docker​

Single-machine (all-in-one)​

Volumes​

With PostgreSQL​

Split deployment (separate workers)​

Podman compatibility​

Storage layout​

Authentication setup​

Google OAuth2​

Microsoft OAuth2 (Microsoft 365 / Entra ID)​

Generic OpenID Connect (Okta / Auth0 / Keycloak)​

Add a Session Worker (optional)​

Add a Deployment Worker (optional)​

Reverse proxy notes​

Next steps​