Installation

This guide covers installing Polygent on a server (or your workstation for local trials).

Prerequisites

Requirement	Why
.NET 10 Runtime	Runs the API, Session Agent, and Deployment Agent
Git 2.20+	Worktree isolation per session

The built-in Polygent Code agent works out of the box — no agent CLI install is required to run your first session. Install an external provider CLI only when you want to use that provider instead.

Supported agent providers

The built-in Polygent Code agent needs no CLI. For the external providers, install only the ones your team plans to use.

Polygent Code — built-in, no CLI install needed
Claude Code
Gemini CLI
OpenCode
Kilo CLI
Codex
Qwen Code

Components

Polygent ships three deployable services:

Component	Description	Deployed As
System	.NET 10 web app — REST API, real-time hub, and client	Windows Service (recommended) or a long-running process
Session Agent	Worker service that executes AI sessions on remote machines (parallel session distribution)	Windows Service
Deployment Agent	Worker service that executes slot deployments on customer machines	Windows Service

Both agents are optional for single-machine setups — the API can host sessions and deployments itself. Add a Session Agent when you want to spread AI sessions across multiple machines, and a Deployment Agent when you need to run slot deployments on a separate host.

Installation methods

Windows Service (recommended)

The recommended deployment method for production Windows environments.

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\Polygent.Api.exe" start= auto
sc.exe description Polygent "Polygent Server"
sc.exe start Polygent

Session Agent Service

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

sc.exe create PolygentSessionAgent binPath= "C:\Polygent\Polygent.SessionAgent.exe" start= auto
sc.exe description PolygentSessionAgent "Polygent Session Agent Service"
sc.exe start PolygentSessionAgent

Deployment Agent Service

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

sc.exe create PolygentDeploymentAgent binPath= "C:\Polygent\Polygent.DeployAgent.exe" start= auto
sc.exe description PolygentDeploymentAgent "Polygent Deployment Agent Service"
sc.exe start PolygentDeploymentAgent

Place appsettings.json alongside the executable. See Configuration for all options.

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

Access Polygent at http://localhost:8080.

Security: never set Login__EnableTestLogin=true in a production deployment — it bypasses OAuth entirely. Leave it unset (defaults to false).

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 agents)

The same image ships three runtime targets: the API, the Session Agent, and the Deployment Agent. For a multi-machine setup, run the API on one host and point agent containers at it using their API base URL and an admin-issued Host API Key (minted from the Hosts → API Keys tab). Agents 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 your database, if external) to back up the whole installation.

Authentication setup

Polygent ships with three sign-in methods. 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 Agent (optional)

A Session Agent 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.

Each external provider CLI you intend to use must be installed on the worker machine with valid credentials — the Session Agent runs the agent locally on that host. Polygent Code needs no install.

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 Agent 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-agent-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`	Per-host session cap (default 8)
`DisplayHostname`	Friendly name shown on the Hosts page (defaults to the machine hostname when blank)

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

sc.exe create PolygentSessionAgent binPath= "C:\Polygent\Polygent.SessionAgent.exe" start= auto
sc.exe start PolygentSessionAgent

Confirm registration. The agent should report Online on the Hosts page within a minute. If Require Admin Approval for Agents 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 Agent (optional)

A Deployment Agent 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 Agent 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-agent-data"
  }
}

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

Install as a Windows Service:

sc.exe create PolygentDeploymentAgent binPath= "C:\Polygent\Polygent.DeployAgent.exe" start= auto
sc.exe start PolygentDeploymentAgent

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

Both agents connect outbound to the API over HTTPS and send periodic heartbeats — the API never opens inbound connections to a host. An agent is marked Offline after roughly a minute without a heartbeat.

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
Core Concepts — learn the Polygent vocabulary
Configuration → Agent Providers — wire up Claude Code, Gemini, etc.
System Requirements — hardware, software, and network details

Prerequisites​

Supported agent providers​

Components​

Installation methods​

Windows Service (recommended)​

API Server​

Session Agent Service​

Deployment Agent Service​

Managing the service​

Docker​

Single-machine (all-in-one)​

Volumes​

With PostgreSQL​

Split deployment (separate agents)​

Podman compatibility​

Storage layout​

Authentication setup​

Google OAuth2​

Microsoft OAuth2 (Microsoft 365 / Entra ID)​

Generic OpenID Connect (Okta / Auth0 / Keycloak)​

Add a Session Agent (optional)​

Add a Deployment Agent (optional)​

Reverse proxy notes​

Next steps​