Skip to main content
Multi-space mode lets one KiwiFS process host multiple independent knowledge bases. Each space has its own root directory, git repo, search index, and .kiwi/ state.

​
When to use multi-space

  • Separate team wikis on one host (engineering vs product).
  • Per-tenant isolation in self-hosted deployments.
  • A default space plus dynamically provisioned workspaces.

​
Configure spaces

.kiwi/config.toml
[[spaces]]
name = "engineering"
root = "/data/eng-wiki"

[[spaces]]
name = "product"
root = "/data/product-wiki"
The first registered space is the default — requests without a space identifier route there.

​
Request routing

Resolution order:
PriorityMethodExample
1X-Kiwi-Space headerSet by a reverse proxy (subdomain → space name)
2URL path prefix/api/kiwi/{space}/tree
3Default spaceFirst registered space
curl 'http://localhost:3333/api/kiwi/engineering/tree?path='
If X-Kiwi-Space is set but the space does not exist, the request fails immediately — no silent fallback to the default.

​
Space admin API

MethodPathPurpose
GET/api/spacesList all spaces with metadata
GET/api/spaces/:nameSingle space summary
POST/api/spacesCreate { "name", "root" }
DELETE/api/spaces/:nameRemove a dynamic space
Dynamic spaces persist to .kiwi/spaces.json under the first space’s root and restore on restart. See Spaces API for curl examples.

​
Per-space auth

With auth.type = "perspace", API keys scope to a single space:
.kiwi/config.toml
[[auth.api_keys]]
key = "kiwi_sk_eng_..."
space = "engineering"
actor = "eng-team"

​
MCP

Use --space <name> when the knowledge root hosts multiple configured spaces: 
kiwifs mcp --root /data --space engineering

Configuration

[[spaces]] config syntax.

Spaces API

REST CRUD for space management.
Last modified on May 23, 2026