Quickstart

This takes about five minutes. You need macOS or Linux (amd64 or arm64), or Docker.

Install KiwiFS

Release binary
Docker
From source

Download the latest release for your platform and put it on your PATH:

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
kiwifs --version

All builds are on the releases page, each with a .sha256 checksum.

Terminal

docker run -d --name kiwifs -p 3333:3333 -v kiwifs-data:/data ameliaanhlam/kiwifs

The container runs kiwifs serve --root /data and creates a knowledge base from the kb template on first start. Skip to step 4.To keep the files in a host folder instead of a named volume, see Docker.

Requires Go 1.27+, Node 20+, and make. The build compiles the web UI and embeds it in the binary.

Terminal

git clone https://github.com/kiwifs/kiwifs.git
cd kiwifs
make build
./kiwifs --version

go install github.com/kiwifs/kiwifs@latest does not work: the module does not include the built web UI, so the embed step fails. Use make build.

Create a knowledge base

Terminal

kiwifs init --root ./knowledge

This scaffolds the default kb template: sample pages, page schemas, a workflow, and a .kiwi/ folder with configuration and an agent playbook.

knowledge

.kiwi

config.toml

playbook.md

rules.md

schemas

templates

workflows

getting-started

guides

reference

index.md

SCHEMA.md

Pass --template to start from something else, such as wiki, memory, tasks, adr, or blank. See Init templates for all twelve.

Start the server

Terminal

kiwifs serve --root ./knowledge

Open http://localhost:3333 to see the web UI. The same port serves the REST API under /api/kiwi/ and MCP over HTTP at /mcp.

You can skip init. If the root has no .kiwi/config.toml, serve initializes it with the kb template first.

Write a page

Write through the API or straight to disk. Both go through the same pipeline.

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=notes/auth.md' \
  -H 'X-Actor: my-agent' \
  --data-binary $'# Authentication\n\nOAuth2 with JWT access tokens.\n'

mkdir -p knowledge/notes
printf '# Authentication\n\nOAuth2 with JWT access tokens.\n' > knowledge/notes/auth.md

The REST call returns the new ETag, which you pass as If-Match on later writes to detect conflicts:

{"etag":"934818f7f7cc3f1a23edc793a08bc8720fc05085","path":"notes/auth.md"}

Verify it was indexed and versioned

Terminal

curl 'http://localhost:3333/api/kiwi/search?q=jwt'
curl 'http://localhost:3333/api/kiwi/versions?path=notes/auth.md'

The search returns notes/auth.md with the match highlighted. The versions list shows one commit whose author is my-agent, or fswatch if you wrote to disk.

Your knowledge base is running. Every write is now searchable within a moment and recorded as a git commit.

Connect an agent

Point an MCP client at the running server. Your agent gets 78 tools for reading, writing, searching, querying, refactoring, and coordinating through drafts and claims.

Claude Code
Claude Desktop and Cursor
No server

Terminal

claude mcp add --transport http kiwifs http://localhost:3333/mcp

MCP config

{
  "mcpServers": {
    "kiwifs": {
      "command": "kiwifs",
      "args": ["mcp", "--remote", "http://localhost:3333"]
    }
  }
}

Without a running server, kiwifs mcp can open the folder directly:

MCP config

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

Use --remote instead whenever kiwifs serve is running on the same folder, so that one process owns the writes.

See MCP for the tool reference and remote auth.

Next steps

Configuration

Auth, search, versioning, vector embeddings, and more.

Agent interface

Filesystem, REST, and MCP access patterns.

Web UI

Tree, editor, graph, Bases, and search.

Deploy with Docker

Run KiwiFS in production with Docker Compose.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Connect an agent

Next steps

Configuration

Agent interface

Web UI

Deploy with Docker

​Connect an agent

​Next steps

Configuration

Agent interface

Web UI

Deploy with Docker

Connect an agent

Next steps