Folio is very close to the kind of Git-centered knowledge system I keep looking for.
Folio is a self-hosted wiki where the page content lives in Git, while the web app gives people collaborative editing, permissions, search, offline document edits, whiteboards, tables, file previews, AI assistant workflows, and MCP access for agents.
The short version:
Folio = browser wiki + Git repository as source of truth + Postgres/Redis runtime
It is not just a Markdown editor. It is a long-running collaborative web app.
What is Folio?
Folio describes itself as:
The vibe-coded, open-source alternative to Notion and Confluence.
The repository I checked was:
Repository: https://github.com/evergreen-it-dev/folio
Checked commit: 2cf9b6cca2a85b9b1225e76f44bc0434a9102242
Commit date: 2026-10-09
Latest checked tag: v0.1.0
License: MIT
Runtime: Node.js 22, Fastify, React, Vite, PostgreSQL, Redis, Git
Container image tested: ghcr.io/evergreen-it-dev/folio:latest
Each Folio space is a Git repository, or a folder inside one. Documents are Markdown files, whiteboards are editable SVG files, data tables are Markdown table files, and file pages keep their uploaded files in the space.
PostgreSQL does not replace Git as the content source of truth. It stores accounts, access rights, indexes, audit data, and collaborative editing state.
Why It Is Interesting
Most wiki tools store content in a database and offer export later.
Folio flips that:
Git repository = durable content
Database = operational state, index, access, collaboration
That gives you:
- normal Git history;
- commits authored by people;
- direct edits from an IDE;
- remote repository sync;
- Markdown links;
- readable table files;
- SVG whiteboards;
- a way for agents to read and write the same knowledge base.
This is why Folio is worth looking at next to tools like Monolith, Emdash, and the Git-based Astro/Hugo CMS idea. It already proves that a browser-first Git-backed editing workflow can feel like a modern workspace.
Features
Folio currently covers a lot:
| Area | What Folio Provides |
|---|---|
| Documents | Markdown editor with reading, live edit, and source modes |
| Collaboration | Real-time editing for documents, tables, and whiteboards |
| Git | Spaces backed by Git repositories, delayed commits, sync status, conflict awareness |
| Whiteboards | Excalidraw-based boards stored as SVG |
| Diagrams | Visual Mermaid editor plus Markdown Mermaid blocks |
| Tables | Typed table files with views, filters, sorting, forms |
| Files | PDF, Word, Excel, and PowerPoint preview pages |
| Offline | Opened documents and whiteboards stay editable; offline-created docs/boards sync later |
| Access | Instance admin, space roles, page restrictions, invitations, access requests |
| Sharing | Public share links and .md share output for agents |
| AI | Cursor-backed assistant, .agent folder instructions, assistant analytics |
| MCP | Remote MCP server for Claude, ChatGPT, Codex, Cursor, VS Code, n8n, Open WebUI |
The MCP angle is unusually complete. Folio exposes tools for listing spaces, reading pages, searching, creating/updating pages, working with whiteboards, querying/updating data tables, and reading history.
Self-Hosting Folio with Docker
I added a Home-Lab compose folder here:
Home-Lab Folio composeThe compose uses the published container image, PostgreSQL, and Redis:
name: folio
services:
app:
image: ${FOLIO_IMAGE:-ghcr.io/evergreen-it-dev/folio:latest}
container_name: folio
restart: unless-stopped
ports:
- "${FOLIO_BIND:-0.0.0.0}:${FOLIO_PORT:-4870}:4870"
environment:
NODE_ENV: production
PORT: "4870"
DATABASE_URL: postgresql://folio:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@postgres:5432/folio
REDIS_URL: redis://redis:6379
PUBLIC_URL: ${PUBLIC_URL:?Set PUBLIC_URL in .env}
ASSET_BACKEND: local
FOLIO_SECRET: ${FOLIO_SECRET:-}
GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
GOOGLE_ALLOWED_DOMAINS: ${GOOGLE_ALLOWED_DOMAINS:-}
CURSOR_API_KEY: ${CURSOR_API_KEY:-}
CURSOR_AGENT_MODEL: ${CURSOR_AGENT_MODEL:-auto}
CURSOR_AGENT_WORKSPACE_ROOT: /app/data/assistant/workspaces
CURSOR_AGENT_STATE_DIR: /app/data/assistant/state
FOLIO_POSTHOG_KEY: ${FOLIO_POSTHOG_KEY:-}
FOLIO_POSTHOG_HOST: ${FOLIO_POSTHOG_HOST:-}
TRUST_PROXY: ${TRUST_PROXY:-}
entrypoint: ["/sbin/tini", "--", "/bin/sh", "-c"]
command:
- |
set -e
if [ -z "$$FOLIO_SECRET" ]; then
secret_file=/app/data/.folio-secret
if [ ! -s "$$secret_file" ]; then
umask 077
node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > "$$secret_file"
echo "folio: generated a new secret in $$secret_file"
fi
FOLIO_SECRET="$$(cat "$$secret_file")"
export FOLIO_SECRET
fi
exec npx tsx server/index.ts
volumes:
- folio-data:/app/data
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_started
healthcheck:
test:
- CMD
- node
- -e
- "fetch('http://127.0.0.1:4870/api/health').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
interval: 30s
timeout: 5s
retries: 3
start_period: 60s
postgres:
image: postgres:17-alpine
container_name: folio-postgres
restart: unless-stopped
environment:
POSTGRES_USER: folio
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
POSTGRES_DB: folio
volumes:
- folio-pg:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U folio -d folio"]
interval: 5s
timeout: 5s
retries: 20
redis:
image: redis:7-alpine
container_name: folio-redis
restart: unless-stopped
command: redis-server --save '' --appendonly no
volumes:
folio-data:
folio-pg:
Start it:
cd folio
cp .env.sample .env
nano .env
docker compose up -d
Generate the database password once:
openssl rand -base64 32
Then use:
FOLIO_IMAGE=ghcr.io/evergreen-it-dev/folio:latest
FOLIO_PORT=4870
FOLIO_BIND=0.0.0.0
PUBLIC_URL=http://192.168.1.2:4870
POSTGRES_PASSWORD=replace-with-a-long-random-password
FOLIO_SECRET=
FOLIO_SECRET can be empty. In that case Folio generates one on first start and stores it in the persistent app data volume. If you set it manually, keep it permanently because it encrypts saved Git tokens and personal AI keys.
Open:
http://192.168.1.2:4870
The first account created in the browser becomes the instance administrator.
Field Note: Local Trial
I tested Folio locally with the Home-Lab compose.
The stack started three containers:
folio
folio-postgres
folio-redis
The app applied migrations, generated a local FOLIO_SECRET, and became healthy.
Health check:
curl http://127.0.0.1:4870/api/health
Response:
{"ok":true}
The setup endpoint also showed a fresh instance:
curl http://127.0.0.1:4870/api/auth/state
{
"needsSetup": true,
"user": null,
"memberships": {},
"google": false
}
So yes, you can try the UI at http://192.168.1.2:4870/ and create the first admin account there.
Backup Notes
Folio needs both Git/data and PostgreSQL to be backed up.
The official backup model is:
docker compose exec -T postgres pg_dump -U folio folio > folio-db.sql
docker compose exec -T app tar czf - -C /app/data . > folio-data.tgz
Why both?
| Data | Where |
|---|---|
| Wiki content, space repositories, uploads, generated secret | /app/data / folio-data volume |
| Users, roles, access rules, search/index data, collaboration snapshots | PostgreSQL |
| Presence/rate-limit/transient state | Redis, intentionally not persistent |
If a space is connected to a remote Git repository, the page files also exist there after sync. That still does not replace the database backup, because access and collaboration state are not purely in Git.
FAQ
Is Folio a static site CMS?
No.
Folio is Git-native, but it is not a static-site CMS. It is a long-running app with PostgreSQL, Redis, persistent disk, browser sessions, WebSockets, and collaborative editing.
It can manage Markdown content in Git. It does not directly replace an Astro, Hugo, or Cloudflare Pages build pipeline.
Is Folio a SilverBullet or Logseq alternative?
Only partly.
Folio overlaps with SilverBullet and Logseq because it can store Markdown, work offline in some editing flows, and give you a browser-based knowledge workspace. But its center of gravity is different.
| Tool | Best Fit |
|---|---|
| Logseq | Personal knowledge graph, daily notes, backlinks, local-first PKM |
| SilverBullet | Personal/local-first Markdown workspace with programmable notes |
| Folio | Team wiki/workspace with Git-backed spaces, permissions, collaboration, whiteboards, tables, files, and MCP |
So I would not call Folio a direct Logseq replacement. It is closer to a Git-native Notion or Confluence alternative for teams and agents.
For one person writing linked daily notes, Logseq or SilverBullet still feels lighter. For an internal handbook, engineering wiki, client workspace, or agent-readable team knowledge base, Folio is much closer.
How can Folio be Git-based and still use PostgreSQL and Redis?
Because Git is the durable content layer, not the whole application state.
Folio stores the actual space content in Git-backed files: Markdown documents, SVG whiteboards, table files, uploaded files, and repository history. That is the part you can inspect, sync, clone, and version outside Folio.
PostgreSQL stores the operational state that Git is bad at:
- users and sessions;
- space memberships and roles;
- access restrictions;
- indexes and metadata;
- collaboration state;
- audit/history pointers;
- app configuration.
Redis is used for transient runtime coordination: presence, rate limits, short-lived collaboration/session work, and similar fast state. It is not the durable knowledge store.
That split is the key architectural idea:
Git = content source of truth
Postgres = app/account/collaboration source of truth
Redis = fast temporary runtime state
It is Git-native, not Git-only.
Can it run on Cloudflare Pages, Vercel, or Netlify?
No.
Folio needs:
- a long-running server process;
- persistent disk for Git repositories and uploaded files;
- PostgreSQL;
- Redis;
- WebSocket connections.
That rules out Cloudflare Pages, Vercel, Netlify, and similar static/serverless-only hosting.
Does Folio work offline?
Partially, and in a useful way.
Opened documents and whiteboards can stay editable without a connection. New documents and whiteboards can also be created offline and synchronized later. Folio uses browser storage and Yjs-based collaboration state for this.
But it is not a fully offline-first app where everything works without the server. Data tables, forms, file uploads, templates, and opening a never-before-loaded page need a connection. A closed browser also cannot load Folio fresh while offline because the app itself comes from the server.
Is Folio a PWA?
It has serious offline behavior, but I would not describe it as a simple static PWA.
The offline capability is part of the web app: IndexedDB, Yjs persistence, local pending pages, dirty document tracking, and reconnect sync. It still depends on the server for authentication, routing, synchronization, Git operations, permissions, tables, forms, file uploads, and fresh app loads.
Can Folio power the Git-based Astro/Hugo CMS idea?
It provides useful inspiration, but it is not a drop-in fit.
Good ideas to borrow:
- browser editing over Git-backed Markdown;
- visible sync state;
- conflict handling;
- offline document drafts;
- agent-readable Markdown endpoints;
- MCP write tools;
.agentpages as repo-versioned instructions.
Important mismatch: Folio rewrites pages in its own format. Its documented limitations say front matter keeps only Folio’s own keys: id, order, status, icon, and cover. Other front matter keys may be dropped when Folio rewrites a page.
That is a problem for Astro/Hugo posts where front matter is the publishing contract.
For a static-blog CMS, I would borrow Folio’s collaboration and Git-sync ideas, but preserve arbitrary front matter and make the build trigger explicit through Git commits and CI/CD.
How could Folio inspire a custom Git-based CMS?
The useful pattern is not “copy Folio exactly.” It is the separation of responsibilities.
For a custom Astro/Hugo CMS, I would borrow these ideas from Folio:
- browser editor writes real repository files;
- Git commits are first-class, not an export feature;
- offline drafts can exist locally and sync later;
- users see sync/conflict state clearly;
- permissions live in an app database;
- assets have a managed upload flow;
- agents can read and write through a structured API/MCP layer.
But I would change the content contract:
- preserve arbitrary front matter exactly;
- keep
.mdor.mdxfiles shaped for the static-site generator; - store photos in a clear asset backend such as R2/S3;
- commit Markdown changes to Git;
- let CI/CD rebuild and deploy the static site;
- keep the database as workflow/auth metadata, not as the public site’s runtime dependency.
That would give you the best of both worlds: Folio-like editing ergonomics, but Hugo/Astro-style static output.
How does Folio compare with Monolith and Emdash?
Folio is closest to a collaborative internal wiki.
Monolith felt more like a Cloudflare/Hono-oriented CMS/workspace direction. Emdash was closer to an Astro SSR CMS idea. Folio is different because the content model is explicitly Git-native and team-wiki-oriented, with documents, boards, tables, files, permissions, offline edits, and MCP.
For a static public site, Folio is heavier and less directly aligned than a purpose-built Git CMS. For an internal knowledge base where Git history and AI agents matter, Folio is much closer.
What authentication does Folio use?
Folio has its own email/password auth.
On a fresh instance, the first account created through /api/auth/setup becomes the instance administrator. Sessions are stored in PostgreSQL and carried by an HTTP-only folio_session cookie.
Optional Google sign-in is available when GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_ALLOWED_DOMAINS are configured.
For agents, Folio supports personal access tokens and OAuth for MCP clients.
Why does the compose use the latest image?
The Git repository has a v0.1.0 tag, but when I checked, ghcr.io/evergreen-it-dev/folio:v0.1.0 was not published as a container tag.
The published latest image was available for amd64 and arm64, so the Home-Lab compose defaults to:
FOLIO_IMAGE=ghcr.io/evergreen-it-dev/folio:latest
The variable is exposed on purpose. If upstream publishes versioned images later, pin it there before running production updates.
What API or agent surface does Folio expose?
The main agent-facing interface is MCP at /mcp.
Personal access tokens use:
Authorization: Bearer folio_pat_...
Cloud clients such as ChatGPT or Claude can use OAuth when the Folio instance is reachable over HTTPS.
There is also a REST API for page, search, table, export, asset, and sync operations, but access administration stays browser-session-only.
Does the AI assistant require paid APIs?
Yes, for the built-in assistant.
Folio currently supports Cursor as the AI provider. Each user can add a personal Cursor API key, or the operator can set CURSOR_API_KEY as a shared fallback.
Without an AI key, the rest of Folio still works: wiki, Git, documents, tables, whiteboards, files, access control, sharing, and MCP.
Can I use my existing Git repository?
Yes, with a caveat.
Folio can create an empty space, clone an existing repository, or connect a space to a repository later. The docs note that connecting a remote repository later expects an empty repository; to start from existing content, create the space by cloning that repository.
Also remember the front matter caveat if the repo is already used by a static site generator.
Conclusion
Folio is one of the more interesting self-hosted wiki projects because it treats Git as the durable knowledge layer instead of a backup/export format.
For a team wiki, internal handbook, engineering knowledge base, or agent-readable workspace, that is compelling. For a public static website CMS, I would treat Folio as inspiration rather than the exact stack: preserve arbitrary front matter, keep assets and photos intentionally modeled, and let Git commits trigger the static build.
Comments