Skip to main content

Storage

StoragePath is the persistent filesystem boundary for runtime keys, file-backed data, worktrees, attachments, and logs.

Polygent uses a single configurable storage path for everything that lives on disk: signing keys, log files, the SQLite database (when SQLite is the provider), session worktrees, and uploaded attachments.

Storage Path​

StoragePath is a top-level key in appsettings.json:

{
  "StoragePath": "./storage"
}

When StoragePath is null (the default in shipping appsettings.json), the API uses a service-relative directory. Always set an absolute path in production.

Session Worker: the standalone Session Worker service requires StoragePath to be set explicitly — it fails fast at startup if blank. The worker path stores that worker's worktrees and runtime files and must be unique per worker instance on the same machine.

Override via environment variable:

StoragePath="/var/lib/polygent"

Layout​

All persistent data is stored under this directory:

PathContents
polygent.dbSQLite database (when Database:Provider=Sqlite)
signing-key.xmlRSA signing key for JWT — auto-generated 2048-bit key on first run
DataProtection-Keys/Key ring used to encrypt and decrypt reversible secrets — auto-generated on first run
logs/Rolling daily application log files and error-only files
workspaces/Per-workspace bare repository clone plus per-session, per-plan, and per-round-table Git worktrees
MessageAttachments/Persistent ticket, comment, and message attachments
Attachments/Transient staging area for files handed off to a session host
Branding/Uploaded custom branding assets (logo)

The exact subdirectory names may evolve, but everything stays under StoragePath. Restoring StoragePath plus the configured database is sufficient to restore the whole install.

Sensitive data protection keys​

Polygent protects reversible secrets — workspace Git PATs, personal TFS PATs, model API keys, and secret environment variables — by encrypting them at rest. The database or settings file stores only the encrypted value, for example polygent-protected:v1:<ciphertext>. The key ring that decrypts those values is stored at {StoragePath}/DataProtection-Keys/ and is auto-generated on first run.

Because the key ring lives under StoragePath, a single backup of StoragePath plus the database captures everything needed to restore an install — including the keys. If the key ring is lost, every encrypted secret becomes permanently undecryptable and must be re-entered by hand.

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

Sizing​

Disk usage scales primarily with active worktrees. Each session, plan, and round table holds a full checkout of the workspace repository. Plan for:

  • Repository size × (concurrent sessions + plans + round tables) per workspace
  • Plus logs, whose volume depends on activity and configured log level
  • Plus attachments (capped at 10 MB per file by default)

For a 500 MB repository running 10 concurrent sessions, expect ~5 GB just for worktrees. Rotate or archive old logs separately.

Permissions​

The OS account running Polygent, and each worker account for its own worker storage path, must have read/write/execute on StoragePath. On Windows Service installs, this typically means the service account; on Docker, the user inside the container.

For SQLite, the account also needs file-locking permissions — bind-mounting onto network filesystems that lack proper locking (some SMB / NFS configurations) is not supported.

Recommendations​

  • Use an absolute path in production. Relative paths resolve against the working directory of the service, which can shift unexpectedly.
  • Place on local disk for SQLite installs. Network-mounted volumes can corrupt the database under load.
  • Mount as a volume in Docker so worktrees, keys, and (for SQLite) the database survive container restarts.
  • Back up the directory and Data Protection key ring alongside your database backups. Signing keys, worktrees, attachments, and secret-decryption keys do not live in the database.
  • Plan free space. When StoragePath fills up, sessions fail mid-run, hooks abort, and the API can become unresponsive. Monitor disk-free at the OS level.

Cleanup​

Polygent automatically cleans up:

  • Develop session worktrees when sessions reach a terminal state (Done / Canceled)
  • Plan worktrees when plans are completed or cancelled
  • Round table worktrees during scheduled startup verification
  • Orphaned worktrees on API/Agent startup

Chat-mode session worktrees are persistent and only removed when the session is explicitly disposed (Hide / Cancel / Delete). Long-lived chat sessions are the largest single contributor to disk growth.

See Also​