Configuration reference (knosh.json)¶

Knosh reads its global configuration from ~/.config/knosh/knosh.json and, optionally, a project-local configuration from .knosh.json in the current directory. When both files exist, their contents are merged: local values take precedence over global values. If a key is missing from both files, the default is used.

Run knosh init to create a file pre-populated with all defaults.

Options¶

agentsDir¶

Type: string
Default: ~/.config/knosh/agents

Path to the directory containing agent Markdown files. Knosh looks for <agentsDir>/<agentId>.md when an agent is referenced by ID.

~ and $HOME are expanded to the user's home directory.

anthropicApiKey¶

Type: string or null
Default: none

API key for the Anthropic provider. Required to use models with model: "anthropic/..." in an agent configuration. If this is unset, Knosh falls back to the ANTHROPIC_API_KEY environment variable.

mistralApiKey¶

Type: string or null
Default: none

API key for the Mistral provider. Required to use models with model: "mistral/..." in an agent configuration. If this is unset, Knosh falls back to the MISTRAL_API_KEY environment variable.

ollamaURL¶

Type: string
Default: http://localhost:11434

Base URL of the Ollama server. Required to use models with model: "ollama/..." in an agent configuration. The default points to a locally running Ollama instance.

openAiApiKey¶

Type: string or null
Default: none

API key for the OpenAI provider. Required to use models with model: "openai/..." in an agent configuration. If this is unset, Knosh falls back to the OPENAI_API_KEY environment variable.

Config file merging¶

When both a global and a local config exist, their JSON keys are merged before parsing. The local file's values win on any key that appears in both. This lets you set API keys globally and override individual settings (such as agentsDir) per project.

Example¶

{
  "agentsDir": "~/.config/knosh/agents",
  "anthropicApiKey": "sk-ant-...",
  "ollamaURL": "http://localhost:11434"
}