Folio

What does this agent do, and when should you use it?

Folio is an open-source, self-hosted alternative to Notion and Confluence built around one rule: the Git repository is the wiki. Documents, data tables, whiteboards, forms, Obsidian canvases/bases, artifact pages and uploaded files are all plain files in a space's repository; the database holds only the index, access rights and live-editing state. The browser offers Reading, Live edit and Source modes with real-time co-editing for multiple people, and pages stay editable offline until the connection returns. AI comes in two layers: the built-in Folio AI assistant (Ask for read-only, Agent for writes) and an MCP server exposing 41 tools that Claude Code, Cursor, claude.ai, ChatGPT and other clients reach via a personal access token or OAuth 2.1, never exceeding the token owner's rights. Deployment is docker compose up -d; the assistant runs on a Cursor key you supply or an administrator provides, and everything else works without one.

Folio scans Markdown files in a Git repository and renders them as pages, storing whiteboards as editable Excalidraw SVGs, data tables as a single .table.md file, forms as .form.md, and Claude artifacts as a <name>.artifact/ folder. Edits sync in real time in the browser and are committed after roughly 90 seconds of quiet or immediately on Sync, with the last editor as commit author and the message folio:update. The built-in assistant and outside agents use the same tool set: the /mcp endpoint offers 41 tools covering listing and searching spaces, reading and writing pages, building forms, editing table columns and views, reading outlines, tags, properties and links, querying the link graph (get_graph), publishing artifacts (publish_artifact), and reading history. A .agent folder in each space defines that space's assistant instructions as ordinary pages, and /admin/assistant shows answer ratings, surveys and a list of unanswered questions. Publishing turns a space into a read-only site on a path, subdomain or custom domain, optionally with search, downloads and a visitor-facing Ask AI.

1. A product team's docs/ folder: bind the repository folder as a space, let a technical writer edit in the browser while developers see ordinary commits with an author name via git pull.
2. A company that needs a self-hosted knowledge base: run one Docker stack on a VPS, assign administrator/editor/viewer roles per space through the access matrix, and keep an audit log of every grant.
3. Teams automating with Claude Code or Cursor: have the agent read the release process, write release notes and add a roadmap row through MCP, saved in Git under that person's name.
4. Teams publishing public docs: flip a space to a public website with in-space search, Markdown/PDF/DOCX downloads and an optional Ask AI for visitors.
5. Field or travel work: keep writing on already-opened pages and whiteboards offline, then let changes sync back to the same address without duplicates.
6. Migrating off Confluence: point Folio at a Confluence Cloud or on-premises page or tree and import it as Markdown, with Cloud whiteboards becoming Excalidraw boards.

How do you install or deploy this agent?

You need Docker and Git; nothing else:

git clone https://github.com/evergreen-it-dev/folio.git
cd folio
docker compose up -d

The first start builds the application and takes a few minutes. Then open http://localhost:4870 and create the first account, which becomes the instance administrator. For a VPS there is a one-command script in deploy/vps, or the same compose file with --profile https for automatic HTTPS; ready-made kits for Coolify, Railway, Render, DigitalOcean, Dokploy, CapRover, Easypanel, Portainer and Fly.io live in deploy/.

For development:

cp .env.dev.example .env
docker compose -f docker-compose.dev.yml up -d
npm install
npm run dev

The dev server listens on http://localhost:4871 and needs Node.js 22.12 or newer (22.13 or newer for the assistant). Vercel, Netlify and other serverless hosts are explicitly not supported.

How do you use this agent?

After creating your account, the welcome wizard asks what to create first — a document, a whiteboard or a data table — or you can connect an existing Git repository from the same screen. The shortest way to attach an agent over MCP:

claude mcp add folio --transport http https://wiki.example.com/mcp \
  --header "Authorization: Bearer folio_pat_…"

A personal access token carries a read or write scope and never more rights than its owner. For claude.ai or ChatGPT, add https://wiki.example.com/mcp as a custom connector, sign in to Folio and allow read or read + write on the consent screen. Any page, optionally with its child pages, is available as clean Markdown:

curl https://wiki.example.com/share/<token>.md

Folio AI runs on Cursor keys, chosen in this order: the person's own key, the space's key, the instance key, then CURSOR_API_KEY from the server environment. A space administrator sets the space key from the space menu; an instance administrator can disable personal keys so everyone uses the shared one. Without any key, everything except the assistant still works.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ