Settings

Knowmarks can be configured through environment variables, a config file, or the dashboard settings screen.

Configuration Precedence

1. Environment variables — Highest priority. Always wins.
2. Config file — config.json in the data directory. Created on first write from the settings screen.
3. Hardcoded defaults — Used when nothing else is set.

Config File

The config file lives at <data_dir>/config.json and uses a nested JSON structure:

{
  "embedding": {
    "provider": "fastembed",
    "model": "BAAI/bge-small-en-v1.5"
  },
  "llm": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "google/gemini-2.5-flash",
    "api_key": "your-key-here"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 3749
  }
}

The config file is created automatically when you change settings through the dashboard. You can also edit it manually.

Dashboard Settings

Open the dashboard (km serve) and click the settings icon in the header to access:

• Embedding provider — Choose between fastembed, Ollama, or OpenAI-compatible API
• LLM provider — Configure the model endpoint for generative features
• Connector setup — Karakeep server URL and token, Readwise token

Background Service (macOS)

Install Knowmarks as a launchd service for automatic background sync:

km service install

This creates a user-level launchd agent that runs the dashboard server and connector polling in the background.

Other service commands:

km service status     # Check if the service is running
km service logs       # Show recent service output
km service uninstall  # Stop and remove the service

Note

The service captures your current LLM and embedding environment variables at install time. If you change these variables, re-run km service install to update the service configuration.

Data Directory

By default, Knowmarks stores data in the OS-standard application data directory:

• macOS: ~/Library/Application Support/knowmarks/
• Linux: ~/.local/share/knowmarks/
• Windows: C:\Users\<user>\AppData\Local\knowmarks\

Override with the KNOWMARKS_DATA_DIR environment variable:

export KNOWMARKS_DATA_DIR=/path/to/custom/directory