Configuration

Every .kiwi/config.toml key, its default, and the environment variables and flags that override it.

KiwiFS reads .kiwi/config.toml from the knowledge root when the server starts. Every key is optional: a missing key takes the default listed on this page, and a missing file means all defaults.

Settings are applied in this order, last one wins:

1. Built-in defaults.
2. .kiwi/config.toml.
3. Environment variables that override specific keys (see Environment variables).
4. kiwifs serve flags you pass explicitly, such as --port or --auth.

Changes take effect on restart. Auth settings can also be reloaded in place by sending SIGHUP to the server.

Any string value can reference an environment variable as ${NAME}. It is expanded at load time, and an unset variable expands to an empty string. Use this to keep secrets out of the file: api_key = "${OPENAI_API_KEY}".

The starter file

kiwifs init, and kiwifs serve on a folder without a config, writes this file. The rest of the generated file is commented-out examples.

.kiwi/config.toml

[server]
port = 3333
host = "0.0.0.0"

[storage]
root = "."

[search]
engine = "sqlite"

[versioning]
strategy = "git"

[auth]
type = "none"

[storage] root is informational. The server always uses the folder passed to --root.

Server

.kiwi/config.toml

[server]
host = "0.0.0.0"
port = 3333
public_url = "https://wiki.example.com"
cors_origins = ["https://app.example.com"]

Key	Default	Description
host	"0.0.0.0"	Bind address for the REST API, web UI, and /mcp. Also used by --s3, --webdav, and --nfs.
port	3333	HTTP port.
public_url	unset	Base URL for permalinks (the X-Permalink header and share links). The KIWI_PUBLIC_URL environment variable overrides it.
cors_origins	[]	Browser origins allowed to call the API. Merged with [server.cors] allowed_origins.

CORS

.kiwi/config.toml

[server.cors]
allowed_origins = ["https://app.example.com"]
allowed_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
allow_credentials = true
max_age = 86400

Key	Default	Description
allowed_origins	[]	Allowed origins. "*" allows any origin.
allowed_methods	GET, PUT, POST, DELETE, OPTIONS	Methods advertised in preflight responses.
allow_credentials	false	Send Access-Control-Allow-Credentials.
max_age	3600	Preflight cache lifetime in seconds.

Origins on localhost, 127.0.0.1, and [::1] are always allowed. Beyond those:

• With auth off (type = "none"), no other origin is allowed, whatever the lists say.
• With auth on and both lists empty, any origin is allowed, because every request still needs a token.
• With auth on and either list set, only listed origins are allowed.

Rate limiting

.kiwi/config.toml

[server.rate_limit]
requests_per_minute = 600
burst_size = 50

Key	Default	Description
requests_per_minute	0 (off)	Sustained rate per client. Any value above 0 turns the limiter on.
burst_size	50	Requests a client may make at once before the rate applies.

Clients are identified by a hash of their bearer token, or by IP address when they send none. /health, /healthz, /readyz, and /metrics are never limited.

Search

.kiwi/config.toml

[search]
engine = "sqlite"
async_index = true
index_window_ms = 200
index_batch_max = 100

Key	Default	Description
engine	"sqlite"	sqlite for BM25 full-text search over SQLite FTS5, or grep for a zero-index scan. DQL, Bases, analytics, and most health checks need sqlite.
async_index	true	Index writes in the background in small batches instead of inside each request.
index_window_ms	200	How long the background indexer collects writes before flushing.
index_batch_max	100	Flush early once this many paths are queued.

See Search.

Vector search

Semantic search is off until you set enabled = true and configure an embedder. The vector store defaults to an embedded SQLite store.

.kiwi/config.toml

[search.vector]
enabled = true
worker_count = 5

[search.vector.embedder]
provider = "openai"
model = "text-embedding-3-small"
api_key = "${OPENAI_API_KEY}"
dimensions = 1536

[search.vector.store]
provider = "sqlite"

Key	Default	Description
enabled	false	Turn on embedding, the vector store, and semantic search.
worker_count	5	Parallel embed-and-store workers. Lower it for a small local embedder.

Embedder providers

Set under [search.vector.embedder]. provider defaults to openai.

provider	Keys
openai	api_key, model, optional base_url for OpenAI-compatible endpoints. azure-openai is an alias.
ollama	model, optional base_url and timeout (for example "120s")
cohere	api_key, model, optional base_url
voyage	api_key, model, optional base_url
http	url, optional headers table. Any service that returns embeddings over HTTP.
bedrock	model, region. Uses the standard AWS credential chain.
vertex	project, location, model, optional credentials_file (falls back to application default credentials)
onnx	model_path, tokenizer_path. Requires a binary built with -tags onnx; see Optional features. Fetch a model with kiwifs model download.

dimensions sets the vector size for providers that support it.

The onnx provider also accepts runtime_path, max_tokens, pooling (mean or cls), normalize (default true), query_prefix, passage_prefix, and tensor-name overrides input_ids_name, attention_name, token_type_name, and output_name.

Vector store providers

Set under [search.vector.store]. provider defaults to sqlite (sqlite-vec is an alias).

provider	Keys
sqlite	None. Stored under .kiwi/state/.
qdrant	url, optional api_key, collection
pgvector	dsn (a PostgreSQL connection string), optional table
pinecone	url, api_key, optional namespace
weaviate	url, optional api_key, collection (the class name)
milvus	url, optional api_key, collection

For a CPU-only VPS running Ollama, see Ollama vector search on a small VPS.

Chunking

Pages are split into chunks before embedding.

.kiwi/config.toml

[search.vector.chunk]
size = 1500
overlap = 150
context_template = "{{ .Title }}{{ if .Headings }} > {{ .Headings }}{{ end }}"

Key	Default	Description
size	1500	Target chunk size in characters. Chunks break on paragraph boundaries where possible.
overlap	0	Characters carried over from the end of one chunk to the start of the next.
context_template	"{{ .Headings }}"	Go template prepended to each chunk before embedding, so a chunk carries where it came from. Fields: .Title, .Path, .Headings, .HeadingPath, .Frontmatter.
context_hook_url	unset	URL that receives a POST per chunk and returns {"context": "..."} to use instead of the template. Any failure falls back to the template.

Changing size, overlap, or context_template affects only chunks embedded afterwards. Run kiwifs reindex to rebuild existing vectors.

Versioning

.kiwi/config.toml

[versioning]
strategy = "git"
async_commit = true
batch_window_ms = 200
batch_max_size = 50

Key	Default	Description
strategy	"git"	git: every write is a git commit. cow: copy-on-write snapshots under .versions/, no git needed. none: writes overwrite in place.
async_commit	true	Batch git commits in the background. Writes are logged first and recovered on restart if the server stops before committing.
batch_window_ms	200	How long to collect writes before committing a batch.
batch_max_size	50	Commit early once this many paths are pending.
max_versions	100	Snapshots kept per file with strategy = "cow".

If git is not available, the server logs a warning and runs with none. See Versioning.

Authentication

.kiwi/config.toml

[auth]
type = "apikey"
api_key = "${KIWI_API_KEY}"

type	Behavior
none (default)	No authentication.
apikey	One shared key in api_key. Clients send Authorization: Bearer <key>.
perspace	Keys listed in [[auth.api_keys]], each scoped to a space, an access level, and optionally a path prefix.
oidc	Bearer tokens validated against an OpenID Connect issuer.

Per-space keys

.kiwi/config.toml

[auth]
type = "perspace"

[[auth.api_keys]]
key = "${ENG_READ_KEY}"
space = "engineering"
actor = "ci-reader"
scope = "read"
prefix = "docs/"

Key	Default	Description
key	required	The bearer token.
space	required	Space the key is valid for.
actor	unset	Identity recorded as the git author for writes made with this key.
scope	"admin"	read, write, or admin.
prefix	unset	Limit the key to paths under this prefix.

kiwifs token create generates and stores scoped keys for you. See Auth tokens.

OIDC

.kiwi/config.toml

[auth]
type = "oidc"

[auth.oidc]
issuer = "https://accounts.google.com"
client_id = "your-client-id"

The --auth, --api-key, --oidc-issuer, and --oidc-client-id flags on kiwifs serve override these keys.

Space visibility

.kiwi/config.toml

[space]
name = "docs"
visibility = "private"

Key	Default	Description
name	"default"	Name of the primary space (the --root folder) in the space selector and in /api/kiwi/{name}/... routes.
visibility	"private"	Who can read without a token.

Visibility only matters when auth is on. It relaxes auth for GET and HEAD requests:

Value	Reads without a token
private	None.
unlisted	Single-file reads by exact path. Tree, search, and listings still need a token.
public	All reads.

Change it at runtime with PUT /api/kiwi/space/visibility.

Multi-space

Serve several independent knowledge bases, each with its own git history and indexes, from one server.

.kiwi/config.toml

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

[[spaces]]
name = "notes"
root = "../notes"

Key	Default	Description
name	required	Space name. Its API lives under /api/kiwi/{name}/....
root	required	Folder for the space. Relative paths resolve against --root.
visibility	"private"	Same values as [space] visibility.

You can also add spaces with kiwifs serve --space eng=/data/eng. See Multi-space and the Spaces API.

Content rules

Lint

.kiwi/config.toml

[lint]
auto_format = true
reject_errors = true

Key	Default	Description
auto_format	true	Normalize markdown on write: table alignment, trailing whitespace, unclosed fences.
reject_errors	true	Reject writes that still have error-severity lint issues after formatting.

Schemas

.kiwi/config.toml

[schema]
enforce = true
discriminator = "type"
enforce_level = "reject"

Key	Default	Description
enforce	false	Validate frontmatter against .kiwi/schemas/{value}.json on write.
discriminator	"type"	Frontmatter field whose value picks the schema. Use "kind" if your pages key on kind.
enforce_level	"reject"	reject fails the write. warn logs the violation and commits anyway, which helps when adopting schemas on existing content.

See Schemas.

Typed links

.kiwi/config.toml

[links]
typed_fields = ["supersedes", "superseded_by", "cites", "extends", "contradicts"]

Frontmatter fields listed in typed_fields are indexed as wiki links with that relation, so they show up in backlinks, the graph, and refactor link rewrites. The default is ["contradicts", "supersedes", "superseded_by"]. See Wiki links.

Write guards

[[validate_write]] rules protect existing files based on their current frontmatter. New files are never affected.

.kiwi/config.toml

[[validate_write]]
name = "accepted-adrs-are-immutable"
match = { frontmatter = "status", values = ["accepted", "superseded"] }
reject = "body_change"
message = "Accepted ADRs are immutable. Write a new ADR that supersedes this one."

Key	Description
name	Label used in logs.
match	frontmatter names the field; value or values lists the values that trigger the rule.
reject	overwrite rejects any write to a matching file. body_change allows frontmatter edits but rejects changes to the body.
message	Error returned to the writer.

Sequence numbers

.kiwi/config.toml

[sequences]
directories = ["logs/"]

[format_hooks.auto_sequence]
directory = "decisions/"
field = "number"

• [sequences] directories: writes under these folders get a monotonic <!-- seq:N --> marker so gaps are detectable.
• [format_hooks.auto_sequence]: a new file under directory without field in its frontmatter gets the next number, such as number: 12 for ADRs.

Workflow transitions

.kiwi/config.toml

[workflow]
enforce_transitions = true

[workflow.transitions]
open = ["in_progress"]
in_progress = ["done", "blocked"]
blocked = ["in_progress"]

Key	Default	Description
enforce_transitions	false	Reject writes that change frontmatter status from one value to another not listed for it.
transitions	{}	Map from each status to the statuses it may move to. A status with no entry is unrestricted.

Per-workflow state machines live in .kiwi/workflows/*.json. See Workflows.

Refactoring

Standing rules for refactor plans from the CLI, REST API, MCP, and the web UI’s Restructure view.

.kiwi/config.toml

[refactor]
approval_files = 50
approval_links = 200
protect = ["policies/**", "index.md"]
scope = "wiki/"
folder_map = "index.md"

Key	Default	Description
approval_files	50	A plan an agent applies that writes or deletes more files than this needs a person’s approval. -1 turns the check off.
approval_links	200	Same, counted in rewritten links.
protect	[]	Globs no plan may write, delete, or move.
scope	unset	When set, the only folder plans may touch.
folder_map	unset	A page that lists where pages belong (a folders: frontmatter list or - folder bullets). Moving a page into an unlisted folder is a warning.

Agents that apply a plan over the limits are asked to confirm through MCP elicitation when their client supports it. Otherwise the plan waits in GET /api/kiwi/refactor/pending until someone approves it. See Refactor.

Collaboration

Drafts

.kiwi/config.toml

[drafts]
enabled = true
max_active = 10

Key	Default	Description
enabled	false	Turn on draft spaces: git branches in separate worktrees where agents stage edits before merging. Needs strategy = "git".
max_active	10	Maximum open drafts at once.

See Draft spaces.

Webhooks

.kiwi/config.toml

[webhooks]
enabled = true
max_workers = 4
max_retries = 5

[[webhook_entries]]
url = "https://hooks.example.com/kiwifs"
events = ["write", "delete"]
secret = "${WEBHOOK_SECRET}"
path_glob = "concepts/**"

Key	Default	Description
enabled	false	Turn on webhook delivery and the webhooks API.
max_workers	4	Concurrent deliveries.
max_retries	5	Retries per delivery, backing off from 5 seconds to 1 hour.

[[webhook_entries]] registers webhooks at startup, skipping any URL that is already registered. events can include write, delete, transition, bulk, and rollback. path_glob defaults to **. Without a secret, one is generated. See Webhooks.

Audit

.kiwi/config.toml

[audit]
enabled = true

Records every API request with its actor and serves the log at GET /api/kiwi/audit. Off by default. See Audit log.

Maintenance

Janitor

The janitor scans for stale pages, orphans, and broken links on a schedule.

.kiwi/config.toml

[janitor]
interval = "24h"
stale_days = 90
startup_scan = true

Key	Default	Description
interval	"24h"	Time between scans. "0s" turns the scheduled scan off.
stale_days	90	Pages not updated or reviewed within this many days are reported as stale.
startup_scan	false	Also scan once when the server starts.

To flag runbooks whose last execution is too old or failed:

.kiwi/config.toml

[janitor.execution_staleness]
directory = "runbooks/"
date_field = "last_executed"
max_age_days = 90

[janitor.execution_staleness.flag_values]
last_outcome = "failure"

date_field defaults to last_executed and max_age_days to stale_days. Findings appear in kiwifs check, kiwifs janitor, and GET /api/kiwi/janitor.

Backup

Push the git history to a remote on a timer.

.kiwi/config.toml

[backup]
remote = "[e-mail]:org/knowledge.git"
interval = "5m"
branch = "main"
rebase_before_push = true

Key	Default	Description
remote	unset	Git remote URL. Backup is off until this is set.
interval	"5m"	Time between pushes.
branch	current branch	Remote branch to push to.
rebase_before_push	true	Fetch and rebase onto the remote branch before pushing, to avoid non-fast-forward failures.

See Backup sync.

Queries

DataView

.kiwi/config.toml

[dataview]
max_scan_rows = 10000
query_timeout = "5s"
max_auto_indexes = 20

[dataview.custom_fields]
age_days = "days_since(updated)"
is_long = "_word_count > 1500"

Key	Default	Description
max_scan_rows	10000	Rows a single DQL query may scan.
query_timeout	"5s"	Time limit for a DQL query over the API.
max_auto_indexes	20	Frontmatter fields KiwiFS may index automatically after they appear in WHERE or SORT.
custom_fields	{}	Computed fields available in every query, defined as DQL expressions.

See DQL.

Similarity profiles

Named nearest-neighbour searches over frontmatter, served by GET /api/kiwi/similar and the kiwi_similar MCP tool.

.kiwi/config.toml

[[similarity.profiles]]
name = "dataset"
match = { kind = "dataset" }
path_prefix = "datasets/"
numeric = ["stats.rows", "stats.columns"]
categorical = ["format", "license"]
weights = { "license" = 3.0 }

Key	Description
name	Profile name to pass as profile.
match	Only pages whose frontmatter equals these values are candidates.
path_prefix	Optional subtree filter.
numeric	Fields compared by range-scaled difference. Dotted paths reach into nested frontmatter.
categorical	Fields compared by equality.
weights	Per-field multipliers. Unlisted fields weigh 1.

Memory

.kiwi/config.toml

[memory]
episodes_path_prefix = "episodes/"

Pages under episodes_path_prefix (default episodes/) are treated as episodic when their frontmatter does not say. See Episodic memory.

Web UI

.kiwi/config.toml

[ui]
theme_locked = false
start_page = "welcome"
custom_css = ".kiwi/custom.css"
keybindings_file = ".kiwi/keybindings.json"
typed_fences = true

Key	Default	Description
theme_locked	false	Stop readers from switching between light and dark themes.
start_page	"welcome"	First view when no page is in the URL: welcome, recent, dashboard, or a page path such as index.md.
custom_css	".kiwi/custom.css"	Stylesheet loaded after the built-in styles.
keybindings_file	".kiwi/keybindings.json"	JSON file of shortcut overrides.
typed_fences	true	Render bare widget fences such as ```tree as widgets. Set false if existing pages use those tags for something else. The kiwi- spellings always render.
typed_fence_tags	all	Render only these bare widget tags, for example ["array", "matrix"].

Feature switches and toolbar

Every switch defaults to true. Set one to false to hide that part of the web UI, for example for a read-only public site.

.kiwi/config.toml

[ui.features]
edit = false
history = false
publish = false
graph = true
kanban = true
canvas = true
whiteboard = true
timeline = true
bases = true
data_sources = true

[ui.toolbar]
views = ["graph", "bases", "kanban"]

[ui.toolbar] views picks which view buttons appear in the header and in what order: graph, bases, canvas, whiteboard, timeline, kanban, and data. An empty list hides them all.

Sidebar

.kiwi/config.toml

[ui.sidebar]
pinned = ["index.md"]
hidden = ["archive/"]

[[ui.sidebar.sections]]
label = "Guides"
paths = ["getting-started/", "guides/"]

Frontmatter chips

.kiwi/config.toml

[ui.tags]
banner = ["status", "difficulty", "tags"]
hide = ["internal_id"]

[ui.tags.colors]
easy = "emerald"
google = "#4285F4"

banner lists the frontmatter keys shown as chips under the page title. It defaults to ["tags"], and an empty list hides chips. Colors are token names such as emerald, amber, red, or blue, or hex values.

Branding

.kiwi/config.toml

[ui.branding]
name = "Team Wiki"
logo_url = "assets/logo.png"
favicon_url = "assets/favicon.svg"
welcome_title = "Welcome"
welcome_message = "Start with the onboarding guide."

Relative paths are served from the knowledge base. Unset keys keep the KiwiFS defaults.

Keyboard shortcuts

.kiwi/config.toml

[ui.keybindings]
search = "mod+j"
toggle_sidebar = "mod+b"

mod is Cmd on macOS and Ctrl elsewhere. Actions include search, new_page, toggle_editor, save, toggle_sidebar, graph, toggle_bases, toggle_timeline, toggle_kanban, toggle_mode, shortcuts_help, undo, focus_tree_filter, and close_overlay.

Editor slash commands

Add entries to the editor’s / menu that insert a template page:

.kiwi/config.toml

[[ui.editor.slash_commands]]
id = "incident"
label = "Incident report"
icon = "siren"
description = "Insert the incident template"
template = ".kiwi/templates/incident.md"

See Web UI.

Assets

.kiwi/config.toml

[assets]
max_file_size = "25MB"
allowed_types = ["image/png", "image/jpeg", "application/pdf"]

Key	Default	Description
max_file_size	"100MB"	Largest upload accepted.
allowed_types	common types	MIME types accepted for upload. The default covers PNG, JPEG, GIF, WebP, SVG, AVIF, HEIC, HEIF, BMP, MP4, WebM, Ogg, QuickTime, MP3, WAV, FLAC, AAC, M4A, and PDF.

Import

Settings for Airbyte-based imports.

.kiwi/config.toml

[import]
airbyte_api_key = "${AIRBYTE_API_KEY}"
airbyte_workspace_id = "${AIRBYTE_WORKSPACE_ID}"
docker_host = "unix:///var/run/docker.sock"
prefer_airbyte = true
image_prefix = "airbyte/"
pull_policy = "if-not-present"

Key	Default	Description
airbyte_api_key	unset	Airbyte Cloud API key, for running connectors without local Docker.
airbyte_workspace_id	unset	Airbyte Cloud workspace.
docker_host	$DOCKER_HOST	Docker socket for local connectors.
prefer_airbyte	true	Route network sources through Airbyte even when a built-in connector exists.
image_prefix	"airbyte/"	Prefix for connector images, for example a private registry.
pull_policy	"if-not-present"	always, if-not-present, or never.

See also Import connections.

Tracing

KiwiFS writes a structured JSON record of what each REST or MCP request did: files read, searches run, and writes made.

.kiwi/config.toml

[tracing]
enabled = true
output = "file"
file = "/var/log/kiwifs-trace.jsonl"

Key	Default	Description
enabled	true	Set false to turn tracing off.
output	"stderr"	stderr or file.
file	unset	Path for output = "file". Falls back to stderr if unset or not writable.

Environment variables

Variable	Used by	Effect
KIWI_PUBLIC_URL	serve	Overrides [server] public_url.
KIWI_BACKUP_REMOTE	serve	Overrides [backup] remote.
KIWI_BACKUP_INTERVAL	serve	Overrides [backup] interval.
KIWI_BACKUP_REBASE_BEFORE_PUSH	serve	Overrides [backup] rebase_before_push. Accepts true, 1, yes, or on.
KIWI_API_KEY	connect, rules, refactor	Default API key when talking to a remote server.
KIWIFS_API_KEY, KIWIFS_BEARER, KIWIFS_BASIC_PASS	mount	Credentials for the FUSE client.
DOCKER_HOST	import	Docker socket for Airbyte connectors, unless [import] docker_host is set.
NOTION_API_KEY, AIRTABLE_API_KEY, CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN	import	Credentials for those import sources when not passed as flags.

Any other variable can be pulled into the config with ${NAME}.

Related

CLI reference

kiwifs serve flags and every other command.

Optional features

What is off by default and how to turn it on.

Auth tokens

Create scoped API keys.

Deploy with Docker

Pass config and secrets to a container.