Multi-space

Run multiple isolated knowledge bases on one KiwiFS server with path or header routing.

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

config.toml

.kiwi/config.toml

[[spaces]]
name = "engineering"
root = "/data/eng-wiki"

[[spaces]]
name = "product"
root = "/data/product-wiki"

CLI flags

kiwifs serve \
  --space engineering=/data/eng-wiki \
  --space product=/data/product-wiki

The primary space is the one you serve from --root, optionally named with [space] name. Requests without a space identifier route there. Additional [[spaces]] entries are extra isolated knowledge bases.

Browser URLs

Space	Page URL
Primary	/page/{path}
Other	/s/{space}/page/{path}

Legacy /page/{space}/{path} links still resolve when {space} is a registered name.

Request routing

Resolution order:

Priority	Method	Example
1	X-Kiwi-Space header	Set by a reverse proxy (subdomain → space name)
2	URL path prefix	/api/kiwi/{space}/tree
3	Primary space	[space] name, or "default"

Path-based routing

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

Method	Path	Purpose
GET	/api/spaces	List all spaces with metadata
GET	/api/spaces/:name	Single space summary
POST	/api/spaces	Create { "name", "root" }
DELETE	/api/spaces/:name	Remove 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

Related documentation

Configuration

[[spaces]] config syntax.

Spaces API

REST CRUD for space management.