Configuration

Open Knowledge uses hierarchical YAML configuration stored in .open-knowledge/config.yml files. Both config files are optional -- sensible defaults cover everything.

Config hierarchy

Each layer overrides the previous, from left to right. The merge is a deep merge: leaf values override, but arrays replace (not concatenate). There is no walk-up-tree discovery -- the loader checks exactly two fixed paths:

User config -- ~/.open-knowledge/config.yml
Workspace config -- ./.open-knowledge/config.yml (relative to the working directory)

Schema reference

Field	Type	Default	Description
`content.dir`	`string`	`"."`	Content directory relative to project root
`content.include`	`string[]`	`["*/.md", "*/.mdx"]`	Glob patterns for files to include in the document system (relative to `content.dir`). Must contain at least one pattern.
`content.exclude`	`string[]`	`[]`	Glob patterns to explicitly exclude, relative to `content.dir` (combined with .gitignore). See built-in skips below.
`server.port`	`number`	`0`	Collab server port. `0` asks the kernel for a free port; the resolved value is written to `server.lock` for MCP discovery. Set an explicit value (e.g. `3000`) to bind a well-known port.
`server.host`	`string`	`"localhost"`	Server bind address
`server.openOnAgentEdit`	`boolean`	`false`	When `true`, `ok start` opens the `ok ui` URL in the default browser on the first agent write
`persistence.debounceMs`	`number`	`2000`	Quiet period before CRDT changes flush to disk (ms)
`persistence.maxDebounceMs`	`number`	`10000`	Maximum wait before forced flush to disk (ms)
`mcp.autoStart`	`boolean`	`true`	When `true`, `ok mcp` detach-spawns `ok start` as a sibling process if no live `server.lock` is found. Set `false` to force disk-only mode. The env var `OK_MCP_AUTOSTART=0` wins over this setting.
`preview.baseUrl`	`string?`	(unset)	Override for the `previewUrl` emitted by MCP tools. Takes effect when `ui.lock` is absent; the env var `OPEN_KNOWLEDGE_PREVIEW_BASE_URL` wins over this setting.
`sync.enabled`	`boolean?`	auto-detect	Enable/disable GitHub sync. Auto-detected from git remote presence when omitted.
`sync.pullIntervalSeconds`	`number`	`30`	Seconds between fetch/pull cycles. +/-15% jitter applied per cycle.
`sync.pushIntervalSeconds`	`number`	`60`	Seconds between push cycles. +/-15% jitter applied per cycle.
`sync.autoCommit`	`boolean`	`true`	Automatically commit content changes at L2 flush
`sync.autoPush`	`boolean`	`true`	Automatically push after each commit
`sync.autoPull`	`boolean`	`true`	Automatically pull remote changes each cycle
`sync.commitMessage`	`string`	`"auto"`	Commit message for auto-commits. `"auto"` uses `WIP auto-save <timestamp>`.
`github.oauthAppClientId`	`string`	`"Ov23li..."`	OAuth App client ID for Device Flow. Override for forks or custom OAuth Apps.

Built-in directory skips

The following directories are always excluded from traversal regardless of .gitignore or content.exclude config. They are never user-authored content, and some (notably node_modules with pnpm) contain broken symlinks that would crash the file walker.

Category	Directories
Package managers / runtimes	`node_modules`, `.venv`, `venv`, `env`, `__pycache__`, `vendor`
Build output	`dist`, `build`, `out`, `output`, `.next`, `.nuxt`, `.svelte-kit`, `.astro`
Tool caches	`.turbo`, `.cache`, `.parcel-cache`, `coverage`
VCS	`.git`

These skips apply when the directory name appears as the first path segment. For example, dist/ at the content root is skipped, and paths like dist/foo/bar are also skipped because dist is the first segment. Nested instances under non-skipped paths (e.g. docs/dist/) rely on .gitignore or content.exclude patterns.

Example configs

Set a different default port for all projects:

~/.open-knowledge/config.yml

server:
  port: 4000

Point at a subdirectory and exclude drafts:

./.open-knowledge/config.yml

content:
  dir: docs
  exclude:
    - "drafts/**"
    - "archive/**"

Sync configuration

Projects with a git remote auto-enable sync. Override the defaults to tune sync behavior or disable it entirely:

.open-knowledge/config.yml

sync:
  pullIntervalSeconds: 60    # slower fetch cycle
  pushIntervalSeconds: 120   # less frequent pushes
  autoCommit: true
  autoPush: true
  autoPull: true

Set sync.enabled: false to disable sync for a project even when a remote exists. See GitHub Sync for the full sync guide.

Environment variables

Variable	Overrides
`PORT`	`server.port` (for `ok start`); also consumed by `ok ui` as its bind port
`HOST`	`server.host`
`OK_MCP_AUTOSTART`	Set to `0` to disable `ok mcp`'s auto-spawn of `ok start`. Overrides `mcp.autoStart` in config.
`OPEN_KNOWLEDGE_PREVIEW_BASE_URL`	Overrides the `previewUrl` base emitted by every MCP tool. Wins over `ui.lock` discovery and `preview.baseUrl` config. Use for tunnels, CI, or cloud-deployed previews.
`OPEN_KNOWLEDGE_GITHUB_CLIENT_ID`	`github.oauthAppClientId` — override the OAuth App client ID used for Device Flow

Precedence: CLI flags > environment variables > workspace config > user config > Zod defaults. A pre-existing live server.lock always takes precedence over OK_MCP_AUTOSTART=0 — the env var only suppresses the spawn path, it doesn't prevent MCP from connecting to a server the user started manually.

CLI flags

--port and --host are the highest-precedence overrides. They take effect regardless of what YAML files or environment variables specify.

npx @inkeep/open-knowledge start --port 8080

Verifying config changes

After editing config, run preview to verify the resolved content scope:

npx @inkeep/open-knowledge preview

This prints the file count, applied include/exclude patterns, and a sample of matched paths -- useful for confirming that content.include or content.exclude changes had the intended effect.

Configuration

On this page