FAQ

General

What is KiwiFS?

A markdown filesystem for agents and teams. It’s a single Go binary with a web UI, git versioning, full-text and vector search, and access over REST, MCP, NFS, S3, WebDAV, and FUSE. Your content stays plain markdown files on disk.

How is this different from Obsidian?

Obsidian is a desktop app. KiwiFS is a server: it adds a web UI, agent APIs, a git audit trail, and server-side search over the same kind of markdown files. You can import an Obsidian vault directly.

How is this different from Notion or Confluence?

Those tools keep content in their own databases. KiwiFS stores plain markdown, so cat page.md and git clone always work.

Do I need to know git?

No. Git runs under the hood and the web UI and API hide it. It is the audit trail, not the interface.

Is KiwiFS production-ready?

KiwiFS is in active development (v0.19). Core features run in production, but public APIs may change before v1.0. Pin a version and read the changelog before upgrading.

Installation

What are the system requirements?

One static binary. SQLite and the web UI are embedded, and there are no CGo dependencies. KiwiFS runs on macOS, Linux, and Docker. git must be on the path for git versioning. The FUSE client (kiwifs mount) isn’t available on Windows.

How do I install it?

Download a release binary, or run the Docker image:

Terminal

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL "https://github.com/kiwifs/kiwifs/releases/latest/download/kiwifs-$OS-$ARCH.tar.gz" | tar -xz
sudo mv "kiwifs-$OS-$ARCH" /usr/local/bin/kiwifs

# or, with Docker
docker run -d -p 3333:3333 -v kiwifs-data:/data ameliaanhlam/kiwifs

The Quickstart also covers building from source with make build.

What is in .kiwi/, and what can I delete?

.kiwi/ holds configuration and derived state side by side:

Path	What it is	Safe to delete?
`config.toml`, `rules.md`, `playbook.md`	Configuration and agent instructions	No
`templates/`, `schemas/`, `workflows/`	Page templates, JSON Schemas, workflow definitions	No
`comments/`	Inline comments, one JSON file per page	No
`state/`	Search index (`search.db`) and other indexes	Yes. Rebuild with `kiwifs reindex`

Commit everything except .kiwi/state/, which kiwifs init adds to .gitignore.

Which template should I start with?

kiwifs init defaults to kb. Use wiki for a team wiki, memory for agent memory, or tasks for task tracking. See Init templates for all 12.

Agents

How do agents read and write?

Three ways, all through the same write pipeline:

MCP: kiwifs mcp --root ~/knowledge over stdio, or the /mcp endpoint that kiwifs serve always exposes. 78 tools.
REST: PUT /api/kiwi/file and friends.
Filesystem: an NFS or FUSE mount, with cat, echo, and grep.

Can agents use KiwiFS without a running server?

Yes. kiwifs mcp --root ~/knowledge works directly on the folder in-process. To share one knowledge base between several agents, run kiwifs serve and point them at it with kiwifs mcp --remote http://host:3333.

How do I configure Cursor, Claude Code, or Claude Desktop?

mcp.json

{
  "mcpServers": {
    "kiwifs": {
      "command": "kiwifs",
      "args": ["mcp", "--root", "/path/to/knowledge"]
    }
  }
}

For a KiwiFS Cloud workspace, kiwifs connect <slug> --write auto writes the config for you. See MCP.

How does provenance tracking work?

Send X-Actor and X-Provenance headers on writes. The actor is recorded as the git commit author, and KiwiFS adds a derived-from entry to the page’s frontmatter.

How do I reorganize pages without breaking links?

Use a refactor plan. It moves, renames, and merges pages in one commit and rewrites every link that pointed at them. Use Restructure in the web UI, kiwifs refactor plan and apply in the CLI, or kiwi_refactor_plan and kiwi_refactor_apply over MCP. See Refactor.

Security

Is my server open by default?

Yes. The default auth mode is none, which suits a laptop. Before exposing a server, set [auth] type to apikey, perspace, or oidc. See Authentication.

Why do /raw/ links or llms.txt return 401 or show fewer pages?

When auth is on, /raw/{path} needs an Authorization header or a signed URL from GET /api/kiwi/raw-sign, unless the file is public or published. /llms.txt and /llms-full.txt list only public or published pages. The web UI signs image and video URLs for you. See Raw files and llms.txt.

Do NFS, S3, and WebDAV use my API keys?

Only the global api_key in apikey mode. NFS uses an IP allowlist (--nfs-allow) and no keys. Keep these protocols on a private network. See Alternate protocols.

Can people see quiz answers in search?

No. KiwiFS indexes only the question of a quiz, so answers don’t appear in search results or snippets. The answers stay in the markdown file itself.

Search

What search backends exist?

Tier	Engine
1	`grep` (no dependencies)
2	`sqlite`: FTS5 with BM25 ranking (default)
3	Vector search with `[search.vector]` (optional)

The web UI’s search runs full-text and vector search together when vector search is on. See Search.

Can I run vector search without a cloud API key?

Yes. Use Ollama (or the built-in ONNX embedder) as [search.vector.embedder] and sqlite as [search.vector.store] provider. Everything stays on your machine. See Ollama vector search.

How do I rebuild the index?

Terminal

kiwifs reindex --root ./knowledge

Web UI

Can I hide parts of the web UI?

Yes. Set keys under [ui.features] to false, for example edit = false for a read-only UI. This only hides buttons; use auth scopes to actually block writes. See Customize the UI.

A shortcut doesn't work in my browser. Can I change it?

Some defaults, like Mod+Shift+W and Mod+N, are also browser shortcuts. Rebind them in .kiwi/keybindings.json or [ui.keybindings]. See Keyboard shortcuts.

Why is the progress tracker collapsed?

Every folder in a progress tracker starts collapsed so long courses stay readable. Click a folder’s header to expand it.

Does PDF export work offline?

Export as PDF in the web UI downloads the Typst compiler from a CDN the first time, so it needs internet access. For offline or automated exports, use kiwifs export --format pdf or POST /api/kiwi/export/document.

Protocols

NFS, S3, WebDAV, or FUSE?

Protocol	Best for
NFS	Docker and Kubernetes mounts
S3	Backup tools and pipelines
WebDAV	Finder, Explorer, desktop sync
FUSE	Mounting a remote server on a workstation

See Alternate protocols.

Can one server host several knowledge bases?

Yes. Pass --space name=path once per extra knowledge base, or list them in [[spaces]]. Each space has its own git repo and search index, and its own routes at /api/kiwi/{name}/.... See Multi-space.

Data

What happens if the server crashes mid-write?

Writes are atomic: KiwiFS writes a temp file, calls fsync, and renames it into place. You get either the old file or the new one, never half of each.

How do I back up?

Set [backup] remote to push to a git remote every few minutes, or run kiwifs backup.
Restore with kiwifs restore --from <remote> --to <dir>.
Or rsync the knowledge root.

See Backup and sync.

How do I migrate from Obsidian or Notion?

Terminal

kiwifs import --from obsidian --path ~/vault --root ./knowledge

export NOTION_API_KEY=secret_...
kiwifs import --from notion --database-id $DATABASE_ID --root ./knowledge

The web UI’s import wizard supports both too. See Import.

License

Is KiwiFS open source?

KiwiFS is source-available under the Business Source License 1.1. You can self-host, modify, and embed it, including in production. You can’t offer KiwiFS itself to third parties as a competing hosted service. Each release converts to Apache 2.0 four years after it ships.

Can I use it commercially?

Yes, to build and run your own applications and internal services, and to embed it in your product. The only restriction is offering KiwiFS itself as a commercial hosted service.

How do I contribute?

See CONTRIBUTING.md for the code, or the docs repo for documentation.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

General

Installation

Agents

Security

Search

Web UI

Protocols

Data

License

​General

​Installation

​Agents

​Security

​Search

​Web UI

​Protocols

​Data

​License

General

Installation

Agents

Security

Search

Web UI

Protocols

Data

License