Multi-space

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
CLI flags

.kiwi/config.toml

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

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

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

The first registered space is the default — requests without a space identifier route there.

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	Default space	First registered space

curl 'http://localhost:3333/api/kiwi/engineering/tree?path='

curl 'http://localhost:3333/api/kiwi/tree?path=' \
  -H 'X-Kiwi-Space: engineering'

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

Configuration

[[spaces]] config syntax.

Spaces API

REST CRUD for space management.

Getting Started

Core Concepts

Guides

Data Import

Data Export

Deployment

When to use multi-space

Configure spaces

Request routing

Space admin API

Per-space auth

MCP

Configuration

Spaces API

​When to use multi-space

​Configure spaces

​Request routing

​Space admin API

​Per-space auth

​MCP

​Related documentation

Configuration

Spaces API

When to use multi-space

Configure spaces

Request routing

Space admin API

Per-space auth

MCP

Related documentation