Skip to main content

Storage

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 Agent: the standalone Session Agent service requires StoragePath to be set explicitly — it fails fast at startup if blank. The path is the single source of truth for worktrees, attachments, and logs.

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
logs/Rolling daily API and Agent log files; per-session subdirectories
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.

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 log files (typically a few MB/day per active host)
  • 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 the API (and the Agent, if separate) 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 alongside your database backups. Signing keys, worktrees, and attachments 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​