Self-hosting Khiip

Self-host releases paused — July 2026

Khiip is being restructured. The published PyPI releases are yanked and new installs are unavailable; the source repository is private during the rebuild. Existing installations keep working — nothing already installed changes. This page documents the last released version (0.2.4).

Khiip is self-hosted by design — the daemon runs entirely on your machine, against your own accounts and rate-limit budgets, and your data stays in your filesystem. There is no hosted capture service.

Install

Install from PyPI (recommended):

uv tool install khiip      # isolated, on your PATH
# or: pipx install khiip / pip install khiip

Install from source instead

git clone https://github.com/KhiipAI/khiip.git ~/projects/khiip
cd ~/projects/khiip
pip install -e ".[dev]"

Requires Python 3.10+. See Installation for per-source credentials.

Run the daemon

khiipd serve                       # 127.0.0.1:8478 by default
khiipd serve --host 0.0.0.0 --port 8478   # bind on your LAN (see the security note below)

The daemon stays in the foreground. To keep it running:

• Quick/dev: khiipd serve & (backgrounds it in the current shell)
• Durable: run it under your OS process manager so it restarts on boot/crash — see Autostart (launchd / systemd).

Binding beyond localhost

The daemon defaults to 127.0.0.1 (local only). If you bind it to 0.0.0.0 to reach it from other machines, it’s exposed to your network — all /api/v1 routes require the Bearer token (in ~/.config/khiip/auth.toml), but the daemon speaks plaintext HTTP, so put it behind your own TLS/reverse-proxy or a private network (e.g. Tailscale) rather than exposing it to the public internet.

An explicit --host flag binds directly. Setting the host in config.toml instead additionally requires [daemon] allow_non_loopback = true — without it, serve binds loopback and warns, because [daemon] host doubles as the address clients dial (see Configuration).

Run as a managed service

For a daemon that restarts on boot or crash, run khiipd serve under your OS process manager — full systemd user-service and launchd agent templates live on the dedicated Autostart (launchd / systemd) page.

Where your data lives

What	Default path	Notes
Config + auth token	~/.config/khiip/	config.toml + auth.toml (the API key)
SQLite index	~/.local/share/khiip/index.db	derived cache (vault is canonical; a rebuild-from-vault command is planned — back it up for now, see below)
Vault (Markdown captures)	~/khiip-vault/	canonical — your source of truth
Source-tier raw bytes	[storage] data_root (defaults under ~/.local/share/khiip/)	gzipped originals; insurance against upstream rot

See Configuration for overrides.

Cross-machine sync

Khiip has no sync server — you bring your own. Point the vault and data_root at synced storage:

[daemon]
vault_path = "~/Library/Mobile Documents/com~apple~CloudDocs/khiip-vault"  # iCloud, e.g.

[storage]
data_root = "/Volumes/SSD/khiip-data"   # external SSD / Dropbox / network mount

Run the daemon on one machine at a time against a given vault to avoid write conflicts.

Backup

Because the vault is canonical and the index is derived, a minimal backup is:

1. ~/khiip-vault/ — your captures (Markdown + frontmatter). The important one.
2. data_root — the Source-tier raw bytes, if you want the originals preserved.
3. ~/.config/khiip/auth.toml — the API key (or just rotate it after a restore with khiipd auth rotate).

Also back up ~/.local/share/khiip/index.db for now. By design it’s a derived cache reconstructable from the vault — a khiipd rebuild-index command is planned for exactly that — but that command isn’t shipped yet, so don’t rely on regenerating it. After any restore, run khiipd validate to check vault ↔ index consistency.

Automating it

A vault backup is just a file copy, so any scheduler works. A nightly rsync to an external disk via cron, for example:

# crontab -e  →  run at 02:30 daily
30 2 * * * rsync -a "$HOME/khiip-vault/" /Volumes/Backup/khiip-vault/

Add your data_root to the same job if you want the Source-tier originals mirrored too.

Upgrading

Khiip is on PyPI, so upgrading the base daemon is a one-liner (no phone-home — you upgrade when you choose):

uv tool upgrade khiip       # or: pipx upgrade khiip / pip install -U khiip
khiipd validate             # sanity-check the vault ↔ index after upgrade

Then restart the daemon. An upgrade replaces the code on disk, but a running khiipd serve keeps serving the pre-upgrade code until it’s restarted — Ctrl-C and start it again, or restart the service if it runs under launchd/systemd (Autostart). Until you do, khiipd version (a fresh CLI process) and the running daemon’s /health will disagree about the version — that mismatch is the tell.

If you installed from source, git pull && pip install -e ".[dev]" instead. See Releases for the current version of every surface (base, Khiip Plus, and the Obsidian plugin) and how to update each.

Roadmap

• Docker image + compose — planned; not yet available (use the PyPI install above for now)