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

# Local storage

> Where your workspace lives and how to preserve it.

Flowfield stores its workspace separately from the installed application and your source code.

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

Choose another workspace directory with `FLOWFIELD_DATA_DIR` or `flowfield --data-dir
/absolute/path serve`. Project checkouts and their local edits remain separate from task state.

## Upgrades

On startup, Flowfield upgrades supported databases automatically. Before changing an
existing database, it saves a verified snapshot in `~/.flowfield/backups/` (or your chosen
data directory). Migration steps run in one transaction. An error or interrupted process
rolls back the upgrade; an error stops startup and includes recovery instructions.

Upgrades require exclusive access: stop the service before updating, then start the new
build. Flowfield refuses an incompatible database and preserves its contents. Reinstalling
an older application does not downgrade a newer database. The queue is paused after restart;
review interrupted work before enabling workers again.

Database upgrades preserve project identity, installed guidance and execution artifacts.
They do not rewrite project files or install new guidance. Update guidance separately
using the [integration instructions](/integrations/codex).

## Inspect and recover

These commands work without a running service and never initialize or upgrade a database:

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

Add `--json` for structured output. For another workspace, put `--data-dir /absolute/path`
before `storage`.

A failed migration normally needs only a corrected build and another start. To recover
the pre-upgrade database explicitly, stop the service, choose an ID from `storage backups`,
and run:

```sh theme={null}
flowfield storage restore BACKUP_ID --confirm
```

Recovery verifies the snapshot and saves the current database before replacing it.
It refuses a running service, an incompatible schema, a different workspace, or a workspace
that has received writes since the snapshot. This prevents recovery from discarding newer
work. Start Flowfield to retry the upgrade after restoring. Keep the workspace at the same
path when using these recovery snapshots.

## Backups

Flowfield retains up to three database snapshots, including snapshots made before recovery.
These are for migration recovery: they do not contain execution artifacts, managed
workspaces or your project repositories, and cannot repair an unreadable current database.

For a full backup, stop the service and copy the whole workspace directory together with
the relevant project repositories. Preserve those files together when recovering from disk
loss or corruption. Keep a full backup before upgrading.

Normal browser, CLI and agent operations use the service. Offline storage commands are
limited to inspection and guarded recovery.


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