Skip to Content
OperateFilesystem SnapshotsFilesystem Snapshots

Filesystem Snapshots

Filesystem snapshots save a durable agent’s files to blob storage alongside its application snapshot. They preserve files when an agent recovers from a snapshot, performs a snapshot-based manual update, or uses a snapshot-assisted automatic update. For agent code and snapshotting policies, see Snapshotting.

The local macOS server enables filesystem snapshots by default. Standalone executors and local servers on other platforms disable them by default. Ephemeral agents do not take snapshots.

Choose a storage backend

Set the backend with [filesystem_storage.mode]:

BackendUseFilesystem snapshotsPer-agent disk limits and metering
ReflinkXfsProduction on Linux with XFS reflinkSupportedNot supported
ManagedXfsProduction on Linux with XFS reflink and project quotasSupportedSupported; requires xfs-quotad
ApfsLocal development and tests on macOSSupportedNot supported
DirectoryAgent directories under a configured rootNot supportedNot supported
TemporaryTemporary agent directories; the standalone defaultNot supportedNot supported

Production requires Linux 5.8 or later and a dedicated XFS filesystem for each executor. Use ReflinkXfs unless you also need per-agent disk quotas or filesystem metering. The executor needs no capabilities in either XFS mode; only the separate quota daemon needs CAP_SYS_ADMIN.

Enable filesystem snapshots

  1. Prepare XFS storage on each production executor. For local development, follow the macOS guide.
  2. Configure snapshots: retain an encryption key, configure blob storage, and enable the feature on every executor that can run the same agents.
  3. Enable a snapshotting policy on the agent. Enabling filesystem snapshots on an executor does not enable application snapshots. A policy of enabled uses [oplog.default_snapshotting], which defaults to Disabled.
  4. Verify a snapshot, then use the monitoring guide to watch uploads, restores, and storage growth.

All executors that can run the same agents must enable filesystem snapshots and use the same encryption key and blob storage. An agent whose recovery baseline requires a filesystem snapshot cannot start on an executor where the feature is disabled or the key is wrong.

Verify a snapshot

  • At startup, check the executor’s Using configuration: log. Under filesystem snapshots:, check that it reports enabled:. The key is masked as ****. Under filesystem storage:, check the selected mode and root.
  • Make an agent that writes a file take a snapshot. An agent with only untouched read-only initial files does not upload a filesystem snapshot.
  • Check that filesystem_snapshot_upload_seconds_count{outcome="confirmed"} increases.
  • Run golem agent oplog <agent_id>. Look for a SNAPSHOT entry with a filesystem: name and a SNAPSHOT CONFIRMED entry with the same name.

See Monitoring and troubleshooting if captures are skipped, uploads fail, or starts use older snapshots.

When filesystem snapshots are disabled

The executor can write a snapshot record without a filesystem snapshot only when the files can be reconstructed from untouched read-only initial files. There must be no other files or provisioned files, no renames or hard links, and no explicitly assigned file or directory modification times.

If the agent’s files do not meet those conditions, it skips automatic snapshots and recovers by replay. A snapshot-based manual update fails. See Snapshot availability.

Operational details

Resource MeteringXFS Setup