kepr

A self-hosted home for your Koh repositories.

Kepr stores your project snapshots on a machine you own. Offer your work from anywhere, keep public repos to share and private repos for everything else, and recover any save at any time. Every save is kept, every file is recoverable, and nothing touches infrastructure you don't control.

---

What it is

Kepr is a remote host for Koh repositories. It runs as a small daemon on a machine you own — a homelab server, a VPS, a spare laptop — and gives every Koh project a home with a web presence, a release pipeline, and a full snapshot history.

One instance holds everything. Mark a repo private and it's a rolling snapshot buffer for your own work — koh offer pushes there, and if something goes wrong you reach back in, all on infrastructure you trust. Mark a repo public and anyone can browse it, steal the source, and download releases. Public and private live side by side on the same instance; visibility is a per-repo choice, flipped any time with koh offer --private / --public or koh visibility.

---

Core concepts

Faces. A face is a specific save inside a Koh repo tracked by Kepr. koh offer offers a face. koh offer --local packages a save into a portable .face file that someone else can apply to their own Koh repo.

Offers. An offer is a snapshot pushed from Koh to Kepr. It runs a two-phase protocol: Koh first negotiates which objects Kepr is missing, then sends only those. Kepr never receives data it already has.

Steals. A steal pulls a snapshot from Kepr into a local Koh repo — a fully working repo, objects and all. Steal from anywhere on your network, or anywhere in the world from a public repo.

The rolling window. Each face keeps a rolling window of saves per lane. When the window fills, the oldest save is pruned; objects shared between saves are deduplicated and deleted only when the last save referencing them is gone. Set max_snapshots = 0 to keep everything forever.

Lanes. Koh tracks main and dev. Kepr maintains the rolling window independently per lane — experimenting on dev never crowds out your main history.

Objects. Every file is stored as a zlib-compressed blob keyed by its BLAKE3 hash. Unchanged files between saves are stored once — deduplication is automatic and exact. Files under 512 bytes are inlined in the manifest, never stored as separate blobs.

Manifests. Every save is a JSON manifest on disk — the source of truth. The database is a derived index; kepr recover rebuilds it entirely from the manifests. No save is ever lost unless its manifest is gone too.

---

Getting started

Install Kepr

curl -fsSL kepr.uk/install.sh | sh

Or via Nix:

nix profile add https://kepr.uk/kepr/archive/HEAD.tar.gz

NixOS users: a module is provided — see the NixOS section in the docs.

Initialize your instance

kepr init

Guided setup — prompts for your domain, data directory, HTTP and SSH ports, and your first operator SSH key. Writes kepr.toml. Generates a recovery phrase, shown once: store it safely.

kepr start

Starts the daemon. Visit your configured domain to confirm it's running.

Connect Koh, and log in

koh login kepr.local

Registers this machine's SSH key with your account. On a new machine later, koh login adds that machine's key too — one account, many keys. Lost every machine? koh login --recover <host> uses your recovery phrase plus an emailed confirmation to enrol a fresh key, so your work continues.

Offer your first save

koh offer

Your snapshot is stored. Lose your machine, steal it back from anywhere. To keep a repo private, offer it private:

koh offer --private

Install a project hosted on Kepr

curl -fsSL kepr.uk/myproject/install.sh | sh

Or nix profile add https://kepr.uk/myproject/archive/HEAD.tar.gz, or steal the source directly with koh steal kepr.uk/myproject.

---

Features

Private and public repos. Visibility is per-repo on one instance. Private repos are invisible to anyone without read access — not just locked, but unlisted and unconfirmable. Flip visibility any time from Koh; the instance is the source of truth.

Builds and releases. Drop a kepr.build file at your repo root and koh offer --builds cross-compiles release binaries on your own machine and uploads the finished artifacts. No external CI, no third-party runners — and the instance never compiles your code, it stores and serves the binaries with provenance metadata. An empty kepr.build is enough to start; Koh detects your language and infers sensible defaults.

Contributions. With contributions.accept_offers = true, other Koh users can offer saves to your repos. Incoming offers land in quarantine pending review — accept to merge, decline to discard. Every pending offer carries an automated trust assessment.

Safety analysis. Every repo gets a continuous safety record: binary blob detection, build-script analysis, trojan-source checks (bidi overrides, homoglyphs), supply-chain review, and license compatibility — ecosystem-aware, updated with each offer. A transparent record, not a badge: clean repos show a clear confirmation, real findings are plain-language and specific.

Traffic, privately. Per-repo counts of steals, archive downloads, and release downloads, visible to the owner. Fully anonymous by design — no per-visitor tracking, no IP logging, just counts.

Accounts and recovery. One account, many machine keys. A recovery phrase plus email confirmation re-enrols a key after losing every device, so work continues. Secrets are hashed with Argon2id.

Themeable. Make the instance yours — the operator sets the brand colours from the admin panel and the whole UI re-themes live, no rebuild.

Recovery and storage. kepr recover rebuilds the database from manifests. kepr backup / restore handle full backups; kepr image produces a portable instance snapshot — data, config, and the exact binary that produced it — restorable on any machine with no dependencies. Deduplication spans all saves and all repos; kepr storage verify rehashes every object, and kepr storage trend projects disk usage 30 days out.

---

Operator commands

| Command | What it does | |---|---| | kepr init | Guided first-time setup | | kepr start / stop / restart | Daemon lifecycle | | kepr status | Instance health at a glance | | kepr doctor | Full self-diagnostic | | kepr config | Read and write configuration | | kepr keys | Manage operator SSH keys | | kepr repos | List, rename, and remove repos | | kepr prune | Trim a repo to its rolling window | | kepr offers | Review pending contributions | | kepr backup / restore | Full instance backup and restore | | kepr storage | Storage usage, GC, verification | | kepr image | Portable instance snapshot | | kepr recover | Rebuild database from manifests | | kepr logs | Structured activity log |

Full reference for every command and option: kepr.uk/docs

---

Configuration

Kepr is configured via kepr.toml, written by kepr init and editable any time. Most changes take effect immediately; a few need kepr restart. Use kepr config set <key> <value> — it validates before writing and tells you whether a restart is needed.

The web interface

Every instance has a web UI. Visitors browse public repos, read descriptions, view history, download bundles, and install via Nix or curl. The operator gets the admin panel at /admin — dashboard, repos, issues and tickets, keys, storage, email, configuration, the theme picker, and per-repo traffic. Repo pages show what the software actually does — network calls, file writes, process spawning — derived from the source and linked to the exact lines. An auditable record, not a README promise.

NixOS

A NixOS module is included. Add the Kepr flake input, import the module, configure with Nix options — no kepr init, no imperative setup. The module manages the service, data directory, and firewall. Full setup in the docs.

---

MIT licensed. Built by Asha Software.

hope in every line of code