> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="config.toml">
    ```toml .kiwi/config.toml theme={null}
    [[spaces]]
    name = "engineering"
    root = "/data/eng-wiki"

    [[spaces]]
    name = "product"
    root = "/data/product-wiki"
    ```
  </Tab>

  <Tab title="CLI flags">
    ```bash theme={null}
    kiwifs serve \
      --space engineering=/data/eng-wiki \
      --space product=/data/product-wiki
    ```
  </Tab>
</Tabs>

<Info>
  The first registered space is the **default** — requests without a space identifier route there.
</Info>

## 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                          |

<CodeGroup>
  ```bash Path-based routing theme={null}
  curl 'http://localhost:3333/api/kiwi/engineering/tree?path='
  ```

  ```bash Header-based routing theme={null}
  curl 'http://localhost:3333/api/kiwi/tree?path=' \
    -H 'X-Kiwi-Space: engineering'
  ```
</CodeGroup>

<Warning>
  If `X-Kiwi-Space` is set but the space does not exist, the request fails immediately — no silent fallback to the default.
</Warning>

## 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](/api/spaces) for curl examples.

## Per-space auth

With `auth.type = "perspace"`, API keys scope to a single space:

```toml .kiwi/config.toml theme={null}
[[auth.api_keys]]
key = "kiwi_sk_eng_..."
space = "engineering"
actor = "eng-team"
```

## MCP

Use `--space <name>` when the knowledge root hosts multiple configured spaces:

```bash theme={null}
kiwifs mcp --root /data --space engineering
```

## Related documentation

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration#multi-space">
    `[[spaces]]` config syntax.
  </Card>

  <Card title="Spaces API" icon="server" href="/api/spaces">
    REST CRUD for space management.
  </Card>
</CardGroup>