> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowfield.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Flowfield Local Storage: Workspace, Backups, and Recovery

> Learn where Flowfield stores its workspace, how automatic database migrations work, how to inspect your data, and how to recover from a failed upgrade.

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.

| Location | Contents |
| - | - |
| `~/.flowfield/` | Workspace database, execution artifacts, and service-owned workspaces |
| `project/.flowfield/config.toml` | Portable project identity |
| `project/.flowfield/guidance.json` | Ownership records for installed guidance |
| `project/.agents/skills/flowfield-coordinator/SKILL.md` | Coordinator instructions |

To use a different workspace directory, set `FLOWFIELD_DATA_DIR` or pass `--data-dir /absolute/path` before the `serve` command:

```sh theme={null}
flowfield --data-dir /absolute/path serve
```

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:

```sh theme={null}
flowfield storage status
flowfield storage backups
```

Add `--json` for structured output. To inspect an alternate workspace, put `--data-dir /absolute/path` before `storage`:

```sh theme={null}
flowfield --data-dir /absolute/path storage status
flowfield --data-dir /absolute/path storage backups
```

## 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:

<Steps>
  <Step title="Stop the service">
    Make sure the Flowfield service is not running before you attempt recovery.
  </Step>

  <Step title="List available snapshots">
    ```sh theme={null}
    flowfield storage backups
    ```

    Each entry shows a backup ID, schema version, and creation timestamp.
  </Step>

  <Step title="Restore the snapshot">
    ```sh theme={null}
    flowfield storage restore BACKUP_ID --confirm
    ```

    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.
  </Step>

  <Step title="Retry the upgrade">
    Start Flowfield again to retry the migration against the restored database.
  </Step>
</Steps>

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.

<Warning>
  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.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.