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, GitHub backend, SQLite backend, Postgres and Supabase.
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 . 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 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, remote tokens and CLI, MCP, API, board protocol.
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 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 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 describes both arrangements: Postgres for cards and authorization on Render Free, or SQLite on a Docker volume. Local Git clones remain rebuildable cache.