Supabase Local Manager

Data and storage layout

Manager records, project volumes, backups and encrypted secrets: what lives where, and what a backup actually copies.

On this page
  1. What it is
  2. Why it matters
  3. Where state lives
  4. The manager database
  5. The secret boundary
  6. Project data and backups
  7. Failure and recovery
  8. What a restore does not bring back
  9. Where you see the project boundary

What it is

The manager stores three kinds of state in three places. Its own configuration and records live in a SQLite database in the platform data directory. Project data lives in each project's Docker volumes, outside the manager. Secrets that the manager must keep for later use are encrypted in the manager database under the vault master key. Backups are files in the project directory.

Keeping these apart is deliberate. The manager database is small and replaceable; a project's data is the thing worth protecting. A manager reset should not be a project data loss, and a project reset should not erase the register.

Why it matters

Backups, restores and machine moves all depend on knowing what is where. Copying the manager database is not a backup of your projects. Copying a project folder is not a backup of the manager's records. A restore that mixes the two can bring back a project record whose files are gone, or files that no project record points at.

It also matters for the vault. A manager database backup contains encrypted vault rows, so the backup is only useful together with the master key that encrypted them. Keeping the key in the same place as the database defeats the point of encrypting the rows; keeping it nowhere makes the backup unrecoverable. Store the key where you store the machine's other secrets, and keep a copy with the database backup.

Where state lives

Data and storage layout The manager keeps projects, users and settings in a manager SQLite database in the platform data directory. Each Supabase project keeps its Postgres and storage data in Docker volumes. Project backups are SQL files under the project backup folder. Vault secrets are encrypted before storage. Three layers of state Manager database SQLite file in the platform data directory projects / users / settings port allocations / audit rows loaded in memory via sql.js Per-project data Docker volumes managed by the Supabase CLI Postgres data / storage objects project containers not copied by the builder Project files inside the registered project directory supabase/config.toml supabase/backups/*.sql written on demand Secrets and logs Project secrets and edge-function secrets are encrypted with scrypt and AES under the vault master key before storage. The master key is configuration, not database content. Its previous value can be retained during rotation. Proxy access logs and denial logs live in the manager log directory and follow the admin retention setting. The manager database is rewritten as a whole on mutation; copy it only while the manager is stopped. No product data is copied into docs/ by the site builder. manager project

Diagram: the manager database sits in the platform data directory and contains projects, settings, port allocations and encrypted vault rows; each project's Postgres data sits in Docker volumes; backups are SQL files under the project's supabase/backups directory.

Manager stateProject stateBackup file

The manager database

The database is SQLite, loaded into memory with sql.js and rewritten on mutation. On Windows it lives under the application data directory, for example %APPDATA%\supabase-local-manager\Config\supabase-manager.db; on Linux and macOS it uses the platform data directory. Because the whole file is rewritten, a copy taken while the manager is running can be inconsistent. Stop the manager, or copy between writes, before treating the file as a backup.

Numbered migrations apply in one transaction, with a pre-migration backup file beside the database and an automatic restore on failure. A leftover backup file after a failed boot is a signal that the last migration did not complete.

The secret boundary

Security boundaries and credentials Three credential types cross three boundaries. A manager session cookie is checked by the manager API. A project anon or service-role key is checked by the front-door evaluator. The service-role key is additionally required for the postgres-meta route. Vault secrets are encrypted under the vault master key. Three credentials, three checks Manager sessionJWT in httpOnly cookieplus CSRF double-submit Project API keyanon or service_rolefrom the project status Vault master keyconfiguration valueencrypts stored secrets Manager API boundaryverify session / token version / CSRF / ownership before a project route runs Front-door boundaryresolve project first, then evaluate session ownership or project key /pg/ requires service_role · Studio is not opened by an API key Secrets at restscrypt-derived key + AES-GCM for project and edge-function secrets previous master key can remain in the key ring Legend: green = request credential · violet = data-at-rest key.

Diagram: the manager process holds the vault key and decrypts secrets only inside its own boundary; project containers receive secrets through configuration, and the manager database holds ciphertext rather than plaintext.

Manager boundaryEncrypted at restProject boundary

Project data and backups

Each project's Postgres data lives in Docker volumes managed by the Supabase CLI. The manager does not mount or copy those volumes; it asks the CLI to start and stop the stack and asks the database for catalog information. Project backups are SQL dumps written under supabase/backups in the project folder, with metadata in the manager database.

The manager's own log directory follows the platform log location and is bounded by the admin retention setting. Proxy and denial logs are operational records, not a permanent audit archive.

Failure and recovery

A corrupted manager database can be restored from a backup file beside it, or reset at the cost of the register and settings. The project folders are unaffected by either. A failed vault key rotation makes existing vault entries unreadable unless the previous key is retained; keep VAULT_MASTER_KEY_PREVIOUS until the rotation is confirmed. A project folder moved on disk breaks its record's path; re-register it rather than editing the database by hand.

Configuration

<code>VAULT_MASTER_KEY</code>
Encrypts vault rows; the key itself must be backed up separately.
<code>VAULT_MASTER_KEY_PREVIOUS</code>
Keeps a prior key available after rotation.
<code>SUPABASE_MANAGER_ENV_FILE</code>
Overrides the environment file path for tests or multiple instances.
Log retention
Bounds the manager's log history.
Back up the master key with the database. A database restored without its key still cannot decrypt its vault rows.

What a restore does not bring back

Restoring the manager database brings back records and settings, not project data. Restoring a project backup brings back that project's database, not its storage objects or its manager record. A complete recovery from a machine loss needs the project folders, the manager database, the master key and any exported backups, and the order matters: restore the database with its key before you expect vault rows to decrypt.

Where you see the project boundary

Project overview showing service health for Postgres, Kong, Studio, Auth, Storage and Realtime, masked API keys, quickstart snippets, and an advisor findings summary.
project-overview
A single project overview: service health, masked keys, client snippets and advisor results.

Related

Backups featureCreate and restore a project backup.Security modelThe principles behind the vault boundary.ConfigurationThe key and path variables.Troubleshooting databaseRecovering a locked manager database.