Storage

StoragePath is the persistent filesystem root for the API's keys, runtime settings, logs, repository clones, working copies, and attachments.

Storage path

StoragePath is a top-level key in appsettings.json (or the StoragePath environment variable):

{
  "StoragePath": "D:\\Polygent\\data"
}

When it is not set, the API uses %APPDATA%\Polygent of the service account (falling back to its local application-data folder, then the install folder). For a service running as LocalSystem that resolves to C:\Windows\System32\config\systemprofile\AppData\Roaming\Polygent, which is easy to miss in backups. Always set an absolute path in production.

Session Worker: the standalone Session Worker requires its own StoragePath and refuses to start when it is blank. Use a different path for each worker instance on the same machine. Deployment Worker: Agent:StoragePath falls back to the install folder when blank.

Layout

The API creates and uses these entries under StoragePath.

Path	Contents
polygent.db	SQLite database (when Database:Provider is Sqlite and no connection string is set).
settings.json	Runtime application settings (models, backend connections, AI jobs, budgets, hosts, Bash policy, branding). Secrets inside are encrypted.
signing-key.xml	RSA key that signs sign-in tokens; generated on first start.
DataProtection-Keys/	Key ring that encrypts stored secrets; generated on first start.
logs/, logs/errors/	Daily application log files and error-only log files. See System Logs.
repositories/	Shared repository clones used to create working copies.
workspaces/	Per-workspace working copies: sessions, persistent Chat copies, merge-conflict copies, and deployment files.
MessageAttachments/	Ticket, comment, message, and approval attachments.
Attachments/	Transient staging for files handed to a session host.
Skills/	Skill definitions and resource files.
Branding/	Uploaded custom logo.
plans/, temp/, and small state files	Plan documents, temporary files, and cleanup/recovery queues.

Data outside StoragePath

A few files are written elsewhere by default; include them in backups or move them under the storage volume.

Location	Contents	How to move
%USERPROFILE%\.polygent\harness (service account)	Agent conversation transcripts used to resume sessions.	Harness:DataDirectory or POLYGENT_HARNESS_DATA_DIR
<install folder>/crash.log	Written only when the process fails to start.	—
<install folder>/plugins/	Agent runtime plugin shipped with the release.	Keep with the installation.

Sensitive data protection keys

Polygent encrypts reversible secrets at rest — repository and TFS personal access tokens, model API keys, MCP credentials, secret environment variables, deploy-template secrets, and refresh tokens. The database and settings.json hold only encrypted values. The key ring that decrypts them is {StoragePath}/DataProtection-Keys/, generated on first start.

If the key ring is lost, every encrypted secret becomes permanently unreadable and must be re-entered.

Windows restore caveat: on Windows the key-ring files are additionally encrypted to the local machine, so a copy restored to a different Windows host cannot decrypt them. Restoring to the same machine works. To migrate to a new Windows machine, plan to re-enter protected secrets after the move, or keep the original host available until the new one is re-keyed. On Linux and in containers the key files are not machine-bound — protect the storage volume with filesystem permissions accordingly.

signing-key.xml is stored unencrypted on every platform; restrict it to the service account.

Backup and restore

A complete recovery set is the database plus the storage path plus the harness data directory, captured at the same point in time.

1. Stop the API (or quiesce writes) so the database and files are consistent. For SQLite, use a SQLite-consistent copy; never copy a live polygent.db alone.
2. Back up the database (see Database → Backups).
3. Back up StoragePath — at minimum settings.json, signing-key.xml, DataProtection-Keys/, MessageAttachments/, Skills/, and Branding/. Working copies (workspaces/, repositories/) can be recreated from Git but hold uncommitted agent work.
4. Back up the harness data directory.
5. Back up appsettings.json (and any appsettings.Production.json) and the service environment configuration.
6. Test a restore on a non-production host.

To restore, install the same release, restore the files and database to the same paths, start the API, and verify sign-in, workspaces, a session, and a stored credential (for example a repository fetch).

Sizing

Disk usage scales mainly with active working copies: each session, plan, round table, and merge holds a checkout of every workspace repository.

• Repository size × (concurrent sessions + plans + round tables + merges) per workspace.
• Persistent Chat working copies and the optional idle reuse pool keep copies after sessions end.
• Preserved working copies (kept after an abnormal stop) remain until their TTL expires — 7 days by default.
• Logs grow with activity and log level.
• Attachments are limited to 10 MB per file.

For a 500 MB repository with 10 concurrent sessions, expect about 5 GB for working copies alone.

Permissions

The service account of each process needs read, write, and delete access to its own storage path. On Windows Service installs this is the service account; in containers, the container user.

For SQLite, the storage path must support file locking. Network filesystems without reliable locking (some SMB or NFS configurations) are not supported for the database.

Recommendations

These practices keep storage predictable and recoverable.

• Use an absolute path on a dedicated volume.
• Place SQLite on local disk. Network volumes can corrupt the database under load.
• Mount a persistent volume in containers for StoragePath and the harness data directory.
• Monitor free space. When the volume fills, sessions fail mid-run, hooks abort, and the API can become unresponsive.
• Restrict interactive access to the storage path; it contains keys, credentials, and source code.

Cleanup

Polygent removes working copies automatically when they are no longer needed.

• Develop session working copies when the session reaches Done or Canceled — unless it holds uncommitted or unpushed work, in which case it is preserved and the owner is notified.
• Preserved working copies after the Preserved Worktree TTL (Hosts → Settings, 7 days by default).
• Plan working copies when plans complete or are canceled.
• Round table working copies when the round table is completed.
• Orphaned working copies and temporary files on API and Session Worker startup and periodically.

Persistent Chat working copies are shared by Chat sessions with the same branch selection and are the largest long-term contributor to disk growth.

See also

• Database — database backups and migrations
• System Logs — log file layout and retention
• Global Settings → Hosts settings — worktree pool and preserved-worktree TTL