POSIX and filesystem semantics

KiwiFS stores real files on a real filesystem, not blobs in a database. How POSIX-like the experience is depends on how you reach those files.

Compliance by access path

Access path	POSIX level	Notes
Direct filesystem	Full	Real files, crash-safe atomic writes, `mmap` works
NFS mount	Near-full	Userspace NFSv3, symlinks, open-then-delete, stable handles across restarts
FUSE mount	Near-full	Remote client over HTTP. Symlinks, directory rename, sub-second mtime, `O_APPEND`; no kernel `mmap`
WebDAV	Partial	`MOVE`, `COPY`, `MKCOL`, `DELETE`; buffered writes that spill to disk
REST, S3, MCP	N/A	HTTP, object-store, or tool semantics

What works on NFS and FUSE

Semantic	NFS	FUSE	Notes
Atomic writes	Yes	Yes	Write to temp file, `fsync`, rename, `fsync` the directory
`rename(2)`	Yes	Yes	Includes directory renames
`O_APPEND`	Yes	Yes	FUSE fetches the current content first, so appends land at the real end of file
`O_TRUNC`, `ftruncate`	Yes	Yes
Symlinks and `readlink`	Yes	Yes	Targets that escape the knowledge root are rejected
Open-then-delete	Yes	—	NFS defers deletion until the last handle closes
`fsync`	Yes	Yes	Pushes the write through the pipeline
Sub-second mtime	—	Yes
Advisory locks	Yes	—	Process-local only
`readdir` hides `.git` and `.kiwi`	Yes	Yes
Real `stat` values	Yes	Yes	Size, mode, and mtime are not synthetic
64 MB file size limit	Yes	Yes	Larger files fail with `EFBIG`
Path safety	Yes	Yes	Blocks traversal, null bytes, control characters, and segments over 255 bytes

Intentionally not supported

Semantic	Why
Hard links	One blob at several paths would break git versioning
`chmod`, `chown`	There is no user or group model. Access is controlled by API keys or OIDC
POSIX ACLs	Access control lives at the HTTP and space level
Extended attributes	Frontmatter serves the same purpose
Distributed locks	Locks are process-local. Use `If-Match` for cross-client concurrency
`mmap` over FUSE	FUSE I/O goes over HTTP, so the kernel can’t map pages

Concurrency and durability

Optimistic locking

REST writes accept an If-Match header with the file’s ETag. A stale ETag returns 409 Conflict. If-Match: * follows RFC 7232.

Serialized writes

Writes from every protocol share one pipeline and one lock, so concurrent writers queue instead of corrupting each other.

Single-instance guard

The server holds an flock on .kiwi/server.lock. The kernel releases it on any exit, including SIGKILL, so there is no stale lock to clean up. Two servers can’t share one knowledge root.

Git lock recovery

Every 10 seconds, a background watcher removes .git/index.lock if it is older than 60 seconds. Git subprocesses get SIGTERM before SIGKILL, so they usually release the lock themselves.

Line-ending integrity

KiwiFS sets core.autocrlf=false and * -text in .gitattributes, so ETags always match the raw bytes on disk. The API blocks writes to .gitattributes.

Frontmatter size limit

YAML frontmatter larger than 64 KB is treated as empty. Headings in the body are still indexed.

Symlinks over REST

Create a symlink by writing its target with Content-Type: application/x-symlink, and read the target back with readlink:

Terminal

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=latest.md' \
  -H 'Content-Type: application/x-symlink' \
  -d 'reports/2026-10.md'

curl 'http://localhost:3333/api/kiwi/readlink?path=latest.md'

Alternate protocols

Set up NFS, S3, WebDAV, and FUSE.

Files as truth

Why KiwiFS stores plain files.

Versioning

Git commits behind every write.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Compliance by access path

What works on NFS and FUSE

Intentionally not supported

Concurrency and durability

Symlinks over REST

Alternate protocols

Files as truth

Versioning

​Compliance by access path

​What works on NFS and FUSE

​Intentionally not supported

​Concurrency and durability

​Symlinks over REST

​Related

Alternate protocols

Files as truth

Versioning

Compliance by access path

What works on NFS and FUSE

Intentionally not supported

Concurrency and durability

Symlinks over REST

Related