Deployment Agent

The Deployment Agent is a separate worker service deployed on customer machines that registers with the Polygent API, sends periodic heartbeats, and runs slots — long-lived deployments that QA, demo, or staging traffic can reach. Use slots to push a session (or merge multiple ticket branches into one slot) onto a real machine before the PR exists.

Architecture

┌─────────────────┐                         ┌─────────────────┐
│   Polygent API  │ ◄─── HTTPS ──────────►  │ Deployment Agent│
│ (orchestration) │   (persistent outbound) │  (your machine) │
└─────────────────┘                         └─────────────────┘
                                              │
                                              ▼
                                     ┌────────────────┐
                                     │  Slots         │
                                     │  (deployments) │
                                     └────────────────┘

The agent connects outbound to the Polygent API over HTTPS using an API key. The API never initiates inbound connections to the host — all commands flow through the persistent agent connection.

Hosts

A host is a machine running the Deployment Agent.

Setting	Description
Name	Display name for the host
API Key	Used to authenticate the agent on connect
IP Address	Tracked automatically on heartbeat
Workspace Allowlist	Restrict which workspaces' slots this host may run (leave empty for all)

Agent configuration

The agent reads its settings from appsettings.json next to the executable. This is the entire configuration the agent needs — there is no slot, workspace, or command configuration on the agent. Everything else (workspaces, slots, deploy scripts, environment variables, variables, and the Git token) is configured in the Polygent UI and sent to the agent on each action.

{
  "Agent": {
    "Name": "deploy-01",
    "MainServerUrl": "https://polygent.example.com",
    "ApiKey": "<deploy-type host API key>",
    "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	A Deploy-type host API key (Hosts → API Keys → Create)
Agent:StoragePath	Working directory where deployed slots are checked out and run

Mint the API key in the app first, then paste it into ApiKey. See Installation → Add a Deployment Agent for the full service-install steps.

:::note Upgrading from an earlier version Earlier agents kept a Workspaces array (with slots and commands) in appsettings.json. That model is gone — slots and deploy templates are now configured in the UI. After upgrading, recreate your slots and deploy templates in the app (there is no automatic migration of on-disk agent config) and delete the Workspaces block from appsettings.json. :::

Deploy templates

A deploy template is a reusable deploy method — the command lifecycle, environment variables, and variables — defined once per workspace and shared across slots. Create and edit templates in Workspace → Deploy Templates.

A template has three command phases plus a set of variables:

Setting	Description
Working Directory	Default checkout/run directory for the template's commands (optional)
Initial Commands	Run once the first time a slot is deployed (e.g., install dependencies)
Startup Commands	Run on every deploy/restart (e.g., publish and start the app)
Startup Execution	Sequential or Parallel
Shutdown Commands	Run when the slot is stopped
Variables	Named values (with optional defaults) that commands reference as {Name}

Command object

Every command in a phase has this shape:

Field	Required	Description
Type	yes	Script runtime: Bash, PowerShell, Cmd, Node.js, or Python
Arguments	yes	The command line / script body to run with that runtime
Name	no	Label shown in the deploy log and progress (defaults to a generated name)
Working Directory	no	Overrides the template/slot working directory for this one command
Environment Variables	no	Extra env vars merged in for this one command

The Type selects how Arguments is executed:

Type	Runs as
Bash	Bash shell command
PowerShell	PowerShell command
Cmd	Windows Command Prompt command
Node.js	Node.js script
Python	Python script

Variables and tokens

Templates declare variables — named values with optional defaults. A command's Arguments, Working Directory, and environment-variable values can reference them as {Name}, and the agent substitutes the resolved value at run time. Each slot can override a variable's default with its own value (set in the slot editor), so one template serves many slots that differ only by a target path, port, or hostname.

Built-in tokens are always available without being declared:

Token	Resolves to
{WorkspaceName}	The workspace name
{SlotName}	The slot name
{WorkingDirectory}	The resolved working directory for the slot
{StoragePath}	The agent's configured storage path
{GitBranch}	The branch being deployed
{StarterBranch}	The starter/base branch, when one is used

Mark a variable Secret to redact its value: the live process still receives the real value, but it is replaced with *** in deploy-error logs and status messages.

Slots

A slot is a deployment target on a host. Create slots from the Hosts page — open a host, click New Slot, give it a name and public URL, pick the workspace and a deploy template, and set any per-slot variable overrides. Edit an existing slot from its Edit action on the slot card. A slot without a deploy template is created but cannot deploy or start until you assign one.

Setting	Description
Name / URL	Slot identity and the address QA/demo traffic reaches it on
Workspace	The workspace whose repository (and Git token) the slot uses
Deploy Template	The reusable deploy method this slot runs
Variable Overrides	Per-slot values that replace the template's variable defaults

The slot's working directory defaults to a path under the agent's storage path ({StoragePath}/slots/{WorkspaceName}/{SlotName}) unless the template sets one explicitly.

Because the server resolves the template and overrides and pushes them to the agent on every Deploy / Start / Stop, editing a template or a slot's overrides takes effect on the next action — no redeploy of unchanged slots is required.

Slot lifecycle

Status	Meaning
Available	No active deployment
Deploying	Initial/Startup commands running
Running	Deployment is up
Stopping	Shutdown commands running
Error	Deployment failed

Deploy from session

From a session, click Deploy to Slot, pick a slot, and Polygent:

1. Snapshots the session's worktree branch
2. Asks the agent to check out that branch in the slot
3. Runs the slot's startup commands

The slot now serves the session's code. QA can hit it, the PM can demo it.

Batch Deploy (multiple tickets)

When you want QA to test multiple tickets together as one build, Batch Deploy:

1. Select 2+ tickets
2. Pick a target slot
3. Polygent starts from the starter branch as the merge base
4. Sequentially merges each selected ticket's branch
5. Reports progress per branch
6. Skipped tickets (e.g., merge conflicts) are unlinked
7. Final result reported

The result is one slot running a Frankenstein build of multiple tickets — perfect for integration testing.

Host API keys

Both Session Agents and Deployment Agents authenticate with an API key issued from the Hosts → API Keys tab (requires the host-API-key management permission, or admin). Keys are named, individually revokable, and can carry an expiration — there is no single shared secret.

Lifecycle

Action	What it does
Create	Mint a new key. Pick a name, host type, and expiration (Never, 30 days, 90 days, or 1 year). The plaintext token is shown once — copy it immediately, it is never retrievable again.
Rotate	Replace a key's token. The previous value stops working at once; update every host that used it.
Revoke	Disable a key immediately. Any open agent connection authenticated by it is dropped on its next call.
Edit	Change the name, expiration, or notes without changing the token.
Delete	Permanently remove a revoked or expired key. The audit record is preserved.

Each key tracks which hosts have used it, with first/last-seen timestamps and success/failure counts, plus a full audit log of every create/rotate/revoke/edit action.

Notifications

Admins (and anyone with host-API-key management permission) receive an inbox notification when a key is expiring soon (within 7 days), has expired, is revoked or rotated, or when a key sees a burst of failed authentication attempts — an early signal of a stale or leaked token. See Notifications.

Rotating without downtime

To rotate a key with no interruption: create a second key, point your hosts at it one by one, then revoke the original once every host has migrated.

Setting up a host

Install the agent

Deploy the agent binary as a Windows Service on the target machine. See Installation → Windows Service for installation steps.

Register with the API

1. In the Polygent UI, register a new host to mint an API key
2. Configure the agent with:
   • API base URL (your Polygent server)
   • API key from step 1
3. Start the service — the host should appear Online within a minute

Create a deploy template

1. Open the workspace and go to the Deploy Templates tab
2. Create a template with its Initial / Startup / Shutdown commands, environment variables, and any variables (with defaults)

Create slots

1. On the Hosts page, open the host and click New Slot
2. Set the slot's name and public URL, pick the workspace and the deploy template, and set any per-slot variable overrides

Slots are now ready to receive deployments from sessions or batch deploys.

Inspecting a failed deploy

When a slot fails, the Hosts page shows a short error summary inline. Click Show details on the failed slot card to open the full deploy log — this is the complete stdout+stderr of the failing command, served from the agent on demand.

The full log is stored on the agent host (under its configured storage path), kept as a single file per slot, overwritten on the next deploy attempt, and deleted when the slot next reaches Running. There is no log history — only the most recent failure is retained.

Troubleshooting

• Host stays offline — Check the agent service is running and the API URL is reachable from the host
• Slot fails on Initial Commands — Click Show details on the slot to see the full output, then run the commands manually on the host to reproduce
• "Show details" returns "Log not available" — Either the host went offline since the failure (the log lives on the agent, not the server), or a newer deploy already replaced the file
• Batch deploy reports skipped tickets — One or more ticket branches couldn't merge cleanly into the running set; resolve conflicts on those tickets first

Examples

Give QA a live preview before the PR exists Create a slot for the web app with Initial Commands that install dependencies and Startup Commands that launch the dev server. From a Develop session, Deploy to Slot — QA gets a running build of the in-progress branch to click through, days before any pull request.

Demo a feature to a stakeholder Point a slot at a staging host, deploy the feature branch's session, and share the slot's URL. The product owner sees the actual working feature instead of a screenshot — and you redeploy the latest branch in one click as the agent iterates.

Integration-test several tickets together Three related tickets are ready for QA. Select them and Batch Deploy to Slot: Polygent starts from the starter branch and merges each ticket's branch in turn onto one slot. QA validates the combined build; any ticket that won't merge cleanly is reported and skipped so the rest still deploy.

Dedicate a host to one team Set a host's workspace allowlist to a single workspace so its slots only ever serve that team's deployments — useful when a host has team-specific tooling or network access.

Permissions

Permission	Capability
hosts.view	View hosts and slots
hosts.manage	Create / configure hosts and slots
workspaces.edit	Create / edit deploy templates