Installation

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

Prerequisites

Prepare these items before installing on a production host.

Requirement	Why
.NET 10 Runtime (ASP.NET Core)	Runs the server and workers. The install script installs it when missing
Git 2.29 or later on every session host	Repository clones and per-session working copies. The install script installs it when missing
TLS certificate trusted by users and workers	HTTPS is required: sign-in cookies are always Secure
An OAuth2 / OpenID Connect application at your identity provider	Production sign-in (Google, Microsoft Entra ID, or any OIDC provider)
Git personal access token per repository	Clone, fetch, push, and pull-request operations
Credentials for at least one model backend	The agent's model provider API key or command-line tool login

The built-in Polygent Code agent needs no separate install. Pick a model and supply its credentials under Developer Tools → PolygentCode → Settings — see Models & Backends. Command-line coding tools are needed only for the models that use them.

Components

Polygent ships one server and two optional workers.

Component	Description	Deployed as
Server (API)	Web application, API, live updates, and the web client; can also run sessions itself	Windows Service or container
Session Worker	Runs agent sessions on additional machines to add capacity or isolation	Windows Service or container
Deployment Worker	Runs preview deployment slots on target machines	Windows Service or container

The server runs sessions in-process by default (LocalHost:Enabled), so Session Workers are optional. Deployment slots always require a connected Deployment Worker, which can run on the server machine or another trusted host.

Windows Service (recommended)

Install, upgrade, and uninstall every component with the install script, which runs each one as a Windows Service.

Install script

The install script installs, upgrades, or uninstalls any combination of the Server, Session Worker, and Deployment Worker on one machine.

1. Run this in PowerShell (Windows PowerShell 5.1 or PowerShell 7). It downloads and starts the script; without administrator rights, the script asks for them through a UAC prompt and continues in a new elevated window:

   irm https://raw.githubusercontent.com/roeibajayo/polygent-official/main/install-polygent.ps1 | iex

   To keep a copy, download install-polygent.ps1 and run powershell -ExecutionPolicy Bypass -File .\install-polygent.ps1 instead.

2. The script lists each component with its status (running, stopped, or not installed), installed version, and folder, and the latest available release. Choose the components. A component that is not installed is installed; for an installed one, choose Upgrade or Uninstall.

3. Answer the prompts. Every prompt suggests a default; press Enter to accept it. The script shows the full plan and asks for confirmation before changing anything.

Step	What the script does
Requirements	Checks the Windows version, CPU, RAM, free disk for each StoragePath, whether port 5000 is free, and whether a worker can reach the server. Installs the .NET 10 Hosting Bundle and Git for Windows when missing or too old.
Downloads	Downloads each component package and each prerequisite installer from its publisher, and verifies its published SHA-256 or SHA-512 hash before use.
Folders	Suggests C:\Program Files\Polygent\<component> for program files and a StoragePath per component on the local drive with the most free space. New folders are restricted to Administrators and SYSTEM.
Configuration	Writes StoragePath, the public URL (ClientUrl, Login:ClientUrl), the worker's server URL, host API key, and worker name to each component's appsettings.Production.json, leaving the shipped appsettings.json unchanged.
Command-line models	Detects your own Claude Code login and ChatGPT/Codex subscription and offers to share them with the Server and Session Worker (Harness:ClaudeConfigDirectory and the service's CODEX_HOME). Sessions then use your subscription.
Service	Registers an automatic-start service running as LocalSystem, with restart on failure, starts it, and checks it is healthy.

Component	Service name
Server	Polygent
Session Worker	PolygentSessionWorker
Deployment Worker	PolygentDeploymentWorker

Create the host API key on the server before installing a worker (Hosts → API Keys → New API Key). A worker must run the same release as its server; a server rejects workers from an older release, so the script reads the server's version and installs that release. After the script finishes, complete the Server's Login and Database settings (see Authentication setup), publish it through your HTTPS reverse proxy, and approve new workers on the Hosts page.

For unattended installs, pass the answers as parameters; any parameter left out is prompted for. Parameters need the script-block form of the one-line command, or a saved copy of the script.

Parameter	Purpose
-Components	Server, SessionWorker, DeployWorker (comma-separated).
-InstallRoot / -DataRoot	Parent folders for program files and for each component's StoragePath.
-Version	Release to install, for example 1.1.0. Default: for a worker, the release its server runs; otherwise the latest release.
-Repository	GitHub repository to download releases from. For a private repository, set GITHUB_TOKEN or sign in with the GitHub CLI.
-PublicUrl	Server: the HTTPS URL users browse to.
-ServerUrl	Workers: the server URL to connect to.
-SessionWorkerApiKey / -DeployWorkerApiKey	Host API keys. Omit them to be prompted without echoing the key; on upgrade, press Enter to keep the current key.
-WorkerName	Name shown on the Hosts page and the Deployment Worker's ServerId. Default: the computer name.
-ClaudeConfigDirectory / -CodexHome	Claude Code and Codex login folders to use for command-line models.
-SkipPrerequisites	Stop with an error instead of installing missing prerequisites.
-Action	Upgrade or Uninstall, for selected components that are already installed. Default: ask.
-RemoveData	With Uninstall, also delete each component's StoragePath. Default: ask, answering No.
-NoStart	Register and configure the services without starting them.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/roeibajayo/polygent-official/main/install-polygent.ps1))) -Components SessionWorker -ServerUrl https://polygent.example.com

Upgrade by running the script again and choosing Upgrade. For each component it stops the service, replaces the program files including appsettings.json (so new defaults take effect), keeps appsettings.Production.json, logs, and crash.log, and starts the service again. Settings an older install kept in appsettings.json are moved to appsettings.Production.json automatically. A Session Worker first waits for running sessions to finish, up to ShutdownDrainTimeoutSeconds. To roll back, run the script with -Version <previous version>.

Uninstall by running the script again and choosing Uninstall. It stops and deletes the service and removes the program folder, including appsettings.Production.json and logs. A component installed without the script only has its service removed; its files are kept. The StoragePath (database, working copies, logs) is kept unless you confirm deleting it or pass -RemoveData. After uninstalling a worker, delete its host on the Hosts page and revoke its host API key.

LocalSystem and shared logins The script runs each service as LocalSystem, which has full control of the machine; agent sessions and deploy commands run with the same rights. On shared or internet-facing hosts, switch each service to a dedicated account afterwards (Services → Properties → Log On) and give that account modify rights on the component's StoragePath and read rights on its install folder. A shared Claude Code or ChatGPT login bills every session on that host to the account that owns the login.

If the script installed .NET or Git, restart Windows at the next opportunity; running services only see the updated PATH after a restart.

First start of the Server

Finish these steps once after the script installs the Server, before giving users access.

1. Set the Login provider and Database in appsettings.Production.json in the Server's install folder, then restart the service. Put secrets in the service environment instead of the file — see Environment Variables.
2. Browse to http://localhost:5000/api/ping on the server; a 200 response confirms the service is running. Then publish it through your HTTPS reverse proxy (see Reverse proxy notes).
3. Sign in with the intended administrator account — the first user to sign in becomes Admin.
4. Install the license under the Activate Polygent screen. See Licensing.

The service listens on http://localhost:5000 (loopback only) by default. To listen on another address or port, set Urls in appsettings.Production.json (for example http://0.0.0.0:5000); separate multiple URLs with ;.

Managing the service

sc.exe stop Polygent
sc.exe start Polygent
sc.exe query Polygent

Application logs are written to {StoragePath}/logs/. If the service stops immediately after starting, read crash.log in the install folder. See System Logs.

Health checks

Use these unauthenticated endpoints for load-balancer and uptime monitoring.

Endpoint	Returns
GET /api/ping	200 whenever the server is running, even without a valid license. Use for liveness.
GET /api/version	The installed version; returns 503 when the license is missing, invalid, or expired.

Containers

Container images run the same components on Linux with Docker or Podman 4.4+. Contact your Polygent operator for the registry and credentials used to pull the images.

The server container listens on port 8080 and stores its data under /data. Configuration is supplied through environment variables (the appsettings.json keys with __ as the section separator).

services:
  api:
    image: polygent-api:latest
    ports:
      - "8080:8080"
    volumes:
      - polygent-data:/data # StoragePath
      - polygent-home:/root # agent transcripts and tool logins (home folder)
    environment:
      - StoragePath=/data
      - Database__Provider=PostgreSql
      - Database__ConnectionString=Host=db;Port=5432;Database=polygent;Username=polygent;Password=${POLYGENT_DB_PASSWORD}
      - Login__LoginType=Google
      - Login__ClientId=${POLYGENT_OAUTH_CLIENT_ID}
      - Login__ClientSecret=${POLYGENT_OAUTH_CLIENT_SECRET}
      - Login__ClientUrl=https://polygent.example.com
      - Login__EnableTestLogin=false
      - ClientUrl=https://polygent.example.com
      - ASPNETCORE_FORWARDEDHEADERS_ENABLED=true
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=polygent
      - POSTGRES_USER=polygent
      - POSTGRES_PASSWORD=${POLYGENT_DB_PASSWORD}
    restart: unless-stopped

volumes:
  polygent-data:
  polygent-home:
  postgres-data:

docker compose up -d
curl -fsS http://localhost:8080/api/ping

Put the container behind your HTTPS reverse proxy before giving users access.

:::danger Sample Compose file enables test login The sample Compose file distributed with the images sets Login__EnableTestLogin=true and LocalHost__Enabled=false for evaluation. Test login lets anyone sign in as any user without a password. Set Login__EnableTestLogin=false and configure a real identity provider before the container is reachable by anyone else. With LocalHost__Enabled=false, sessions run only on Session Worker containers. :::

Volume	Purpose
/data	StoragePath: settings, keys, logs, SQLite database (if used), working copies, attachments.
/root (container home)	Agent conversation transcripts and command-line tool logins. Persist it, or set Harness__DataDirectory under /data.

Session Worker and Deployment Worker containers are configured with the same variables as their Windows installs (ApiUrl, ApiKey, StoragePath for Session Workers; Agent__* for Deployment Workers) and each needs its own persistent volume.

Storage layout

The server writes to a single configurable StoragePath.

• Runtime settings (settings.json), signing key, and data-protection key ring
• The SQLite database (when SQLite is the configured provider)
• System logs
• Repository clones, per-session working copies, and uploads

Agent conversation transcripts are stored in the service account's home folder unless Harness:DataDirectory moves them. Back up StoragePath, the transcript folder, and the database as one recovery set; for SQLite, use a consistent copy while writes are stopped. See Storage → Backup and restore.

Authentication setup

Production authentication uses one external identity provider under the Login section. The first user to sign in becomes Admin.

Register the redirect URI for your provider, where <public-host> is the host users reach Polygent on:

Provider	Login:LoginType	Redirect URI
Google	Google	https://<public-host>/signin-google
Microsoft (Entra ID)	Microsoft	https://<public-host>/signin-microsoft
OpenID Connect (Okta, Auth0, Keycloak)	OpenIdConnect	https://<public-host>/signin-oidc

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

See Authentication for every Login key, provider-specific steps, and token settings. The token signing key is generated under StoragePath on first run.

Add a Session Worker (optional)

A Session Worker runs agent sessions on another machine to add capacity or isolate workloads.

1. Create a host API key. Open Hosts → API Keys → New API Key, choose Session Worker, set an expiration, and copy the token (shown once).

2. Run the install script on the worker machine and choose Session Worker. Enter the server URL and the token when asked. The script writes ApiUrl, ApiKey, StoragePath, and DisplayHostname to appsettings.Production.json; add other keys there and restart the service:

   Key	Default	Purpose
   ApiUrl	—	Public base URL of the Polygent server.
   ApiKey	—	Session Worker host API key.
   StoragePath	required	Working copies, logs, and worker identity. The worker exits (writing crash.log) if blank. Unique per instance.
   MaxConcurrentSessions	8	Seeds the session limit on first registration only; manage it on the Hosts page afterward.
   DisplayHostname	machine name	Name shown on the Hosts page.
   ShutdownDrainTimeoutSeconds	600	How long a service stop waits for running sessions and hook tasks. 0 stops immediately.

   Other keys (Git:LongRunningTimeoutSeconds, Mcp:OAuth:AllowedPrivateHosts, Harness:*) are listed in Environment Variables → Session Worker.

3. Approve the host. It appears on the Hosts page within a minute. With Require Admin Approval for Workers on (Hosts → Settings, default), it stays disabled until an administrator enables it.

4. Sign in command-line tools (only for command-line models). The install script offers to share your own Claude Code and ChatGPT/Codex logins with the worker; sign in to any other tool as the worker's service account, because a login under another account is not visible to the service. The host's Backend readiness list shows each tool as Ready, Missing, Unauthenticated, Expired, Subscription required, Incompatible, or Probe error, with remediation. Restart the worker, or wait for the hourly refresh, after changing a login.

5. Set limits and scope. Use the host's Concurrency action to set Max Concurrent Tickets (default 3), Sessions, Merge AI Processes (default 2), and Hook Tasks (default 2). Use Allowed workspaces to dedicate the host to specific workspaces; empty allows all. If the Hosts page reports Invalid workspace allowlist — save it again, the host receives no work until you save the allowlist again.

Model API keys saved in Backend Connections are delivered to workers automatically; environment variables on the worker are only a fallback. A session is rejected before its working copy is created when no eligible host is ready for the selected command-line model.

Stopping the worker service waits up to ShutdownDrainTimeoutSeconds for running sessions to finish; allow for this in patching windows.

Add a Deployment Worker (optional)

A Deployment Worker runs preview slots (QA, demo, or staging builds) on the machine where the deployed application should run.

1. Create a host API key. In Hosts → API Keys → New API Key, choose Deploy Worker and copy the token.

2. Run the install script on the target machine and choose Deployment Worker. Enter the server URL and the token when asked. The script writes the Agent settings to appsettings.Production.json, for example:

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

   Add other keys there and restart the service. The full key reference, including identity, heartbeat, and Git certificate options, is in the Deployment Worker guide.

3. Approve the host on the Hosts page, then create deploy templates and slots. See the Deployment Worker guide.

Both workers connect outbound to the server over HTTPS (WebSocket) — the server never opens connections to a worker. A worker is shown Offline after about a minute without contact. Restrict which addresses may connect under Hosts → Settings → IP Restrictions.

Reverse proxy notes

A reverse proxy must preserve the protocols used by browser live updates, worker connections, sign-in, and file transfers.

• Forward WebSocket upgrades (Upgrade and Connection headers) with idle timeouts of at least a few minutes.
• Forward X-Forwarded-Proto and X-Forwarded-For, preserve the original Host header, and set ASPNETCORE_FORWARDEDHEADERS_ENABLED=true on the server so OAuth redirect URIs and license domain checks use the public host and https.
• Forward the Authorization header unchanged (worker and agent credentials).
• Allow large request bodies: up to 512 MB for Session Worker file transfers, 150 MB for batched ticket attachments (10 MB per file), and about 28 MB for IDE uploads.
• Cloudflare: set Network → WebSockets to On, and make sure no Transform Rule, WAF rule, or Worker removes the upgrade headers.

Verify WebSocket passthrough

Verify the public path from outside the server's network after every proxy or CDN change.

1. Open the application, and in the browser developer tools confirm the live-updates connection returns 101 Switching Protocols and stays open. If WebSockets are blocked, the client silently falls back to slower transports (Server-Sent Events or long polling); treat that as a proxy misconfiguration.
2. Connect one Session Worker and one Deployment Worker through the public URL and confirm both stay Online without reconnect loops.
3. Repeat directly against the server origin when it is separately reachable. If the public path returns 200 for an upgrade request while the origin returns 101, the proxy is treating it as ordinary HTTP.

Next steps

• Quick Start — configure a model, workspace, and first session
• Operator hardening checklist — complete before exposing the instance beyond a trusted network
• Configuration Overview — every appsettings.json key
• System Requirements — sizing and network requirements