Alternate protocols

Besides REST and MCP, KiwiFS can expose your knowledge base over NFS, an S3-compatible API, WebDAV, and a FUSE client. Use them when a tool already speaks a filesystem or object-store protocol: an agent sandbox that runs grep, a backup job that runs aws s3 sync, or a desktop that maps a network drive. Every write, whatever the protocol, goes through the same pipeline: atomic write, git commit, search index update, and SSE broadcast.

Quick comparison

Protocol	Default port	Enable with	Best for
REST + web UI	`3333`	always on	Web UI, curl, CI scripts
MCP	stdio, or `8181` with `--http`	`kiwifs mcp`	Claude, Cursor, custom agents
NFS (v3)	`2049`	`kiwifs serve --nfs`	Docker and Kubernetes mounts
S3-compatible	`3334`	`kiwifs serve --s3`	Backups, ETL, S3 clients
WebDAV	`3335`	`kiwifs serve --webdav`	Finder, Explorer, desktop sync
FUSE	—	`kiwifs mount` (client)	Mounting a remote server on a workstation

Enable protocols

The NFS, S3, and WebDAV servers start with kiwifs serve and listen on --host (default 0.0.0.0):

Terminal

kiwifs serve --root ./knowledge \
  --nfs --nfs-allow 10.0.0.0/8 \
  --s3 \
  --webdav

Protocol flags

Flag	Default	Description
`--nfs`	`false`	Start the userspace NFSv3 server
`--nfs-port`	`2049`	NFS listen port
`--nfs-allow`	localhost only	Comma-separated IPs or CIDRs allowed to mount
`--s3`	`false`	Start the S3-compatible API
`--s3-port`	`3334`	S3 listen port
`--webdav`	`false`	Start the WebDAV server
`--webdav-port`	`3335`	WebDAV listen port

GET /readyz reports whether each enabled protocol is accepting connections, and returns 503 if one isn’t.

NFS

KiwiFS runs a userspace NFSv3 server. Without --nfs-allow, only loopback clients (127.0.0.0/8 and ::1) can mount. There is no portmapper, so pass the port explicitly:

sudo mkdir -p /mnt/kiwi
sudo mount -t nfs -o vers=3,tcp,port=2049,mountport=2049,nolock localhost:/ /mnt/kiwi

sudo mkdir -p /private/tmp/kiwi
sudo mount -t nfs -o vers=3,tcp,port=2049,mountport=2049,nolocks localhost:/ /private/tmp/kiwi

apiVersion: v1
kind: PersistentVolume
metadata:
  name: kiwi-knowledge
spec:
  capacity:
    storage: 10Gi
  accessModes: [ReadWriteMany]
  mountOptions: [vers=3, tcp, port=2049, mountport=2049, nolock]
  nfs:
    server: kiwifs.internal
    path: /

Agents then use ordinary shell tools:

Terminal

cat /mnt/kiwi/pages/auth.md
grep -r "timeout" /mnt/kiwi/
echo "- 2026-10-19: rotated keys" >> /mnt/kiwi/log.md

NFS supports symlinks, open-then-delete, and file handles that stay valid across server restarts. .git and .kiwi are hidden from listings.

NFS has no authentication. Access is controlled only by --nfs-allow, so allow the narrowest network range you can.

S3-compatible API

The whole knowledge base is one bucket named knowledge. With multiple spaces, each space is its own bucket. Object keys are file paths.

Terminal

export AWS_ACCESS_KEY_ID=kiwi AWS_SECRET_ACCESS_KEY=kiwi AWS_DEFAULT_REGION=us-east-1

aws s3 ls s3://knowledge/ --recursive --endpoint-url http://localhost:3334
aws s3 sync s3://knowledge/ ./backup/ --endpoint-url http://localhost:3334
aws s3 cp notes.md s3://knowledge/pages/notes.md --endpoint-url http://localhost:3334

The S3 server doesn’t check AWS signatures, so any access key works. It supports ListObjectsV2 with delimiters and pagination, which aws s3 sync, boto3, and rclone rely on.

WebDAV

Connect a desktop client to http://<host>:3335/:

macOS: in Finder, choose Go → Connect to Server and enter http://localhost:3335/.
Windows: map a network drive to http://localhost:3335/.
Linux: use davfs2, or open the URL in your file manager.

WebDAV supports MOVE, COPY, MKCOL, and DELETE. Large uploads are buffered to disk before they’re committed.

FUSE remote mount

kiwifs mount mounts a remote KiwiFS server as a local folder over HTTP. The mount point is a positional argument:

Terminal

kiwifs mount --remote http://host:3333 ~/kiwi

Mount flags

Flag	Env fallback	Description
`--remote`	—	Server URL (required)
`--bearer`	`KIWIFS_BEARER`	Sends `Authorization: Bearer <token>`. Use this with KiwiFS API keys.
`--api-key`	`KIWIFS_API_KEY`	Sends `X-API-Key: <key>`, for proxies that expect that header
`--basic-user`, `--basic-pass`	`KIWIFS_BASIC_PASS`	HTTP Basic auth, for proxies
`--space`	—	Mount a non-default space

Terminal

export KIWIFS_BEARER=kiwi_rw_...
kiwifs mount --remote https://wiki.example.com --space acme ~/acme-wiki

The mount stays in the foreground until you unmount it. FUSE reports sub-second mtimes, supports O_APPEND, symlinks, and directory renames, but not kernel mmap.

FUSE needs macFUSE on macOS or fuse3 on Linux. kiwifs mount isn’t available on Windows; use WebDAV or REST instead.

Authentication

Protocol	How it authenticates
REST, MCP over HTTP	Every auth mode
S3	`Authorization: Bearer <api_key>` in `apikey` mode
WebDAV	Bearer, or Basic auth with any username and the API key as password, in `apikey` mode
NFS	None. IP allowlist only
FUSE	Uses the remote server’s REST auth

S3 and WebDAV check only the global [auth] api_key. With perspace or oidc auth, or with no auth, they accept every request. Most S3 clients can’t send a bearer header, so in practice keep S3 and WebDAV on a private network or behind a firewall in production.

POSIX semantics

Access path	POSIX level
Local knowledge root	Full
NFS mount	Near-full
FUSE mount	Near-full (no `mmap`)
WebDAV	Partial
REST, S3, MCP	HTTP or tool semantics

See POSIX and filesystem semantics for the full matrix.

Agent interface

How agents reach KiwiFS.

CLI commands

Full kiwifs serve and kiwifs mount reference.

POSIX semantics

What works on each mount.

Authentication

API keys, scopes, and OIDC.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Quick comparison

Enable protocols

NFS

S3-compatible API

WebDAV

FUSE remote mount

Authentication

POSIX semantics

Agent interface

CLI commands

POSIX semantics

Authentication

​Quick comparison

​Enable protocols

​NFS

​S3-compatible API

​WebDAV

​FUSE remote mount

​Authentication

​POSIX semantics

​Related

Agent interface

CLI commands

POSIX semantics

Authentication

Quick comparison

Enable protocols

NFS

S3-compatible API

WebDAV

FUSE remote mount

Authentication

POSIX semantics

Related