Skip to main content
Flowfield stores all workspace data on your local machine, separate from the installed application and your source code. Understanding the storage layout helps you back up your work, manage upgrades safely, and recover from failures.

​
Storage locations

Flowfield splits data across a few well-defined locations so that project identity travels with your repository and execution state stays in one managed workspace. To use a different workspace directory, set FLOWFIELD_DATA_DIR or pass --data-dir /absolute/path before the serve command:
Project checkouts and their local edits remain separate from task state.

​
Automatic upgrades

When the service starts, Flowfield upgrades supported databases automatically. Before changing an existing database, it saves a verified snapshot in ~/.flowfield/backups/ (or your chosen data directory). All migration steps run in a single transaction — if anything goes wrong, the entire upgrade rolls back, startup stops, and Flowfield prints recovery instructions. To upgrade safely:
  1. Stop the running service before installing a new build.
  2. Start Flowfield with the new build — migrations run automatically.
  3. The worker queue is paused after restart; review any interrupted work before re-enabling it.
Flowfield refuses to open an incompatible database and preserves its contents. Installing an older application does not downgrade a newer database.

​
Inspect storage (offline)

These two commands work without a running service and never initialize or modify a database:
Add --json for structured output. To inspect an alternate workspace, put --data-dir /absolute/path before storage:

​
Recovery

A failed migration normally requires only a corrected build and another start attempt. If you need to restore the pre-upgrade database explicitly, follow these steps:
1

Stop the service

Make sure the Flowfield service is not running before you attempt recovery.
2

List available snapshots

Each entry shows a backup ID, schema version, and creation timestamp.
3

Restore the snapshot

Recovery verifies the snapshot and saves the current database before replacing it. It refuses to proceed if the service is running, the snapshot schema is incompatible, the snapshot belongs to a different workspace, or the workspace has received writes since the snapshot was taken — this prevents recovery from discarding newer work.
4

Retry the upgrade

Start Flowfield again to retry the migration against the restored database.
Keep the workspace at the same path when using these recovery snapshots.

​
Full backups

Flowfield’s automatic snapshots cover database migration recovery only. For a complete backup of your work, stop the service and copy the entire ~/.flowfield/ directory together with the relevant project repositories. Keep those copies together — the database references project paths, and recovering from disk loss or corruption requires both. Take a full backup before every major upgrade.
Flowfield retains up to 3 database snapshots, including any snapshots created during recovery. These cover migration recovery only — they do not contain execution artifacts, managed workspaces, or project repositories. They also cannot repair an unreadable current database.