# Data storage

Choose where the board lives separately from where its page is hosted. Git and
SQLite and Postgres persist cards. A static page publishes a snapshot; browser storage
remembers your view and, in GitHub account mode, a checked copy of the board.

## Where cards are saved

| Method | Advantages | Tradeoffs |
| --- | --- | --- |
| **Markdown + local Git** | Readable files, ordinary diffs and history. Work offline with an editor, the CLI or the board skills. No GitHub account required. | Manage the checkout and team synchronization yourself. Browser editing needs the local API; its commits are not pushed automatically. |
| **GitHub + Git** | Repository history and access controls. Browser edits use the signed-in person's identity. One canvas can load several authorized repositories. | Requires an HTTPS backend, a GitHub App and network access. Repository permissions and App installations determine which sources are available. |
| **SQLite** | Own the database and API independently of GitHub. Atomic writes, immutable revisions and stale-write checks. GitHub login can open both database and repository sources. | Operate the API, persistent disk and backups. Configure database readers and writers. Standalone token access is an alternative. The remote CLI and MCP use the API; filesystem skills do not edit the database directly. |
| **Postgres** | The same store interface with remote persistence, atomic revisions and concurrent server support. Works with vanilla PostgreSQL or Supabase through a normal connection string. | Operate or choose a database host, configure TLS, permissions and backups, and keep within its quotas. The board server remains required. Supabase Free has usage limits and may pause after inactivity. |

Choose local Git for work centered on files and commits. Choose GitHub when
repository permissions and several sources are useful. Choose SQLite when you
want a persistent server independent of GitHub. Setup: [local API](/docs/guides/live),
[GitHub backend](/docs/deployment/deploy), [SQLite backend](/docs/deployment/sqlite),
[Postgres and Supabase](/docs/deployment/postgres).

SQLite stores its database beside the API process and serializes writes.
Run clients through that API. Multiple application servers and heavy concurrent
writes need a different deployment design; see SQLite's
[deployment guidance](https://www.sqlite.org/whentouse.html). Postgres locks each
board's head during an atomic write; stale revisions remain conflicts on every store.

## Static snapshots and browser storage

| Layer | Advantages | Limits |
| --- | --- | --- |
| **Static export** | Publish the built board on GitHub Pages or any static host. No runtime backend or sign-in needed to read that snapshot. | Cards are embedded in the exported files. The page cannot save cards; export move commands and apply them to the source, then rebuild. It cannot discover private sources. |
| **Browser preferences** · `localStorage` | Restore filters, named filters, appearance, collapsed columns and panel sizes. GitHub account mode also remembers configured sources. | Saved in this browser, not synchronized between devices or stored in the backend. Clearing storage removes them; blocked storage leaves only the current page's state. |
| **Account board cache** · `localStorage` | Show the last checked cards and source list while the API revalidates access, including mixed GitHub and SQLite sources. Confirmed writes update the saved copy. | A bounded copy tied to the backend, account session and sources. Cached cards stay read-only until checked. Sign-out or refused authorization discards it. Standalone token mode does not use this cache. |
| **Token credentials** · `sessionStorage` | Local and SQLite API credentials stay in the current tab. SQLite credentials are scoped to the API address. | Credentials persist neither cards nor preferences. A new tab needs its own local or SQLite connection. GitHub account sessions use separate browser storage. |

A page on GitHub Pages can still edit through a remote API. Pages hosts the
frontend; the configured backend determines where edits are saved.
**Profile → Settings** shows backend synchronization. View preferences remain
local in every mode.

## CLI, skills, HTTP and MCP

| Tool | Available | Scope |
| --- | --- | --- |
| **Board CLI** | `folio-agents board` | Reads and edits the Markdown directory named by `board.source`. Optional `--commit` records a Git commit. It does not connect to a remote API or edit SQLite. |
| **Server CLI** | `folio-board-server api` | Starts the Git, SQLite or Postgres API selected in `agents.yaml`. |
| **Board skills** | `folio-board`, `using-folio-board` | Packaged with manifests for Codex and Claude Code. They operate Markdown/Git boards through the board CLI. They do not provide SQLite commands. |
| **HTTP API** | `/v1/sources`, `/v1/board`, `/v1/cards/{id}` and write routes | Browser and script access to Git, SQLite and Postgres through the same interfaces. `POST /v1/cards` creates a card on each store. |
| **Remote CLI** | `folio-board` | Reads, creates and edits cards through HTTP with a source-bound API token. It supports GitHub, SQLite and Postgres. |
| **Folio Board MCP** | Streamable HTTP at `/mcp` | Uses the same source-bound tokens, permissions, validation and revision checks as HTTP. Read tokens expose read tools; write tokens also expose card creation and operations. |

The board CLI still reads the seed folder if you leave `board.source` in a
SQLite configuration. After the first import, changes to that folder do not
update the database. Use the API for subsequent edits.

SQLite's separate [`sqlite3` shell](https://www.sqlite.org/cli.html) can inspect
the database and make backups. Card edits go through Folio's API so validation,
hash checks and revision history run together. The shell is not a Folio Board
CLI or MCP server.

References: [CLI](/docs/reference/cli), [remote tokens and CLI](/docs/deployment/tokens),
[MCP](/docs/deployment/mcp), [API](/docs/reference/api),
[board protocol](/docs/guides/agents).

## Back up the authoritative store

For Git boards, preserve the repository and its board branch; push local
commits to your chosen remote. Keep the GitHub backend's secrets separate from
the repository.

For SQLite, keep the database and WAL files on persistent storage. Use
SQLite's [online backup mechanism](https://www.sqlite.org/backup.html) for a
running server. An ephemeral container disk loses the board on replacement.

The optional SQLite seed imports files into a new database once. It does not
synchronize Git and SQLite or preserve the seed's Git commit history. There is
no automatic round-trip migration between stores in this release.

Postgres uses a private `folio_board` schema with immutable revisions and shared
content blobs. Preserve it with standard Postgres backups. Supabase Free does
not include automatic database backups; export them separately. The browser
never receives the database connection string.

[Authorization storage](/docs/deployment/authorization) preserves encrypted
credentials, account handles and token revocations independently of cards.
Choose SQLite on a persistent volume or Postgres on an ephemeral API host.
Preserve the signing key separately from database backups.

[Render and Docker](/docs/deployment/containers) describes both arrangements:
Postgres for cards and authorization on Render Free, or SQLite on a Docker
volume. Local Git clones remain rebuildable cache.