Configuration

Open Knowledge reads YAML config from three places:

Project — ./.ok/config.yml (this project, committed to git)
User — ~/.ok/config.yml (every project on your machine)
Project-local — ./.ok/local/config.yml (this project on this machine; gitignored). Holds per-machine-per-project preferences such as autoSync.enabled. Maintained by the editor (auto-sync onboarding modal, sync popover, Settings pane Sync section); you don't normally hand-edit it.

All files are optional; defaults cover everything.

You can edit config two ways:

Settings pane in the editor — Cmd/Ctrl-, or App menu → Settings…
Your IDE — ok init scaffolds a $schema magic comment for autocomplete and validation

Edits made anywhere reflect everywhere; an open Settings pane refreshes live.

Schema

Field	Type	Default	Description
`content.dir`	string	`"."`	Content directory, relative to project root. Auto-set to the relative sub-path when `.ok/` is scaffolded at the git working-tree root from a sub-folder. Excluded paths live in `.okignore` — see Ignore patterns.
`preview.baseUrl`	URL	(unset)	Override for `previewUrl` returned by MCP tools. Project-scope only.
`appearance.theme`	`"light" \| "dark" \| "system"`	(unset)	Editor theme.
`appearance.editorModeDefault`	`"wysiwyg" \| "source"`	(unset)	Initial editor mode for new docs.
`autoSync.enabled`	`boolean \| null`	`null`	Per-machine git auto-sync toggle. Lives in project-local config. `null` means "unanswered" — the editor's onboarding modal triggers on first remote-detected open.

Default frontmatter for a folder lives in that folder's .ok/frontmatter.yml, not in config.yml. Drop a .ok/ directory inside any folder and Open Knowledge applies its rules to docs underneath. Set rules from the editor's folder properties pane, or via the set_folder_rule MCP tool.

Ignore patterns

Path exclusions live in a project-root .okignore file using gitignore syntax — .gitignore rules are honored automatically alongside it, and a leading ! re-includes a file .gitignore excluded. Edit patterns from the Ignore patterns section of the Settings pane, the right-click menu in the file tree, or by hand in any editor; the running server picks up changes without a restart. See Ignore patterns for the full UX.

Precedence

CLI flags > environment variables > project-local config > project config > user config > defaults. Leaf values at higher levels override the same leaf below; arrays replace, they don't concatenate.

Environment variables

Variable	Sets
`PORT`	Server port
`HOST`	Server bind address
`OK_MCP_AUTOSTART`	Set to `0` to disable MCP auto-start
`OPEN_KNOWLEDGE_PREVIEW_BASE_URL`	Override the `previewUrl` returned by MCP tools
`OPEN_KNOWLEDGE_GITHUB_CLIENT_ID`	Override the GitHub OAuth App client ID

CLI flags

Flag	Sets
`--port <port>`	Server port
`--host <host>`	Server bind address
`--cwd <path>`	Working directory used to resolve config

Verifying changes

npx @inkeep/open-knowledge config validate    # schema check; exits non-zero on failure
npx @inkeep/open-knowledge preview            # show which files match your content scope