korvun

README

Korvun

Kernel for Orchestrated Routing — Versatile Unified Nodes
A self-hosted AI messaging gateway, multi-model router, and multi-brain orchestrator in a single Go binary.

_{Korvun Desktop — the same core, in a native window. Downloads ↓}

---

What is Korvun?

Korvun is one self-hosted Go binary that is a messaging gateway, a multi-model router, and a multi-brain orchestrator at once. A real message enters a channel, is routed to a brain, one or more models answer, a policy decides the reply, and it goes back — all in a single process. The same static binary runs on a Raspberry Pi and scales in the cloud; only I/O pieces change by configuration.

The differentiator is the dispatch policy engine. Routing is privacy- and cost-aware, with opt-in consensus, as policies of one engine:

• Privacy — a brain marked private never sends its payload to a cloud model; the privacy selector drops cloud providers before they are called. What is sensitive does not leave the machine.
• Cost — everything else is routed to the cheapest capable model, with a sequential fail-over that pays a cloud provider only when the local one fails.
• Consensus (opt-in) — critical brains can fan out to several models and pick the reply by agreement.

Features

Everything below is on master today — no roadmap item is counted as present.

• Channels — Telegram (polling), Discord (Gateway WebSocket inbound with a resume/reconnect supervisor, REST outbound with mentions blocked by default — see DISCORD-SETUP.md), and a generic Webhook channel, behind one normalized message shape (Envelope).

• Multi-brain orchestration — several brains coexist; each coordinates multiple models in parallel fan-out or cost-saving sequential fail-over, from config.

• Model providers — local Ollama and cloud Groq, behind one Model interface and a shared sentinel-error grammar.

• Policy engine — the privacy / cost / consensus routing above (PriorityReducer, ConsensusReducer, and the pre-dispatch privacy SelectModels).

• Resilience (ADR-0031) — two-layer per-attempt timeouts, retry with differentiated fallback, and an optional boot warmup that resolves the cold-start model-load stall.

• No-code builder — configure brains, models, and routes visually in the browser, no JSON by hand (BUILDER.md).

• Observability — structured slog, a Prometheus /metrics endpoint, and a /healthz liveness probe on a loopback admin server.

• Durable memory — per-conversation history that survives restarts, graceful shutdown included (SQLite by default, behind a Store seam).

• Cross-platform — one static, pure-Go binary (no cgo) for Linux, macOS, and Windows on x86-64 and ARM64.

• Signed releases — each release ships cosign keyless signatures over the checksums and a per-artifact SBOM (SPDX via Syft).

• First-class CLI — serve, config check, status, version, help:

  korvun serve --config korvun.json            # load config, wire, serve
  korvun config check --preflight korvun.json  # validate offline (+ online checks)
  korvun status                                # live wiring of a running instance
  korvun version                               # build identity
  korvun help                                  # usage
  

Korvun Desktop

Since v0.4.0 the same core also ships as a native desktop app. The full Go gateway runs in-process — one binary, one version, one release — behind a native window: first-run onboarding, an assistant that stores every secret in your OS keychain, and the visual builder embedded. Double-click, no terminal. The headless binary is unchanged and is still the way to run Korvun on a server.

Activity — every routing decision, explained where it happens.	Keychain assistant — tokens go to the OS keychain, never to the config.	Channels — each channel with its mode, health and brain.

Download v0.4.0 · macOS — universal .dmg · Windows x64 — installer · Linux x64 — tar.gz

_{Builds are unsigned: the first launch needs right-click → Open on macOS and "More info → Run anyway" on Windows — see Install & run. Built with Wails on the system WebView, so there is no bundled browser. Prefer the terminal? The headless binary ships in the same release.}

Quick start

Prefer a window to a terminal? Korvun Desktop is the same gateway with a UI — download, double-click, done. The steps below are the headless path, still the way to run Korvun on a server.

Grab a signed binary from releases, then:

# 1. korvun.example.json — a minimal, valid starting config. It lives in this repo,
#    and is bundled in the release archive from v0.2.0 onward.
korvun config check korvun.example.json      # validate it (offline, no secrets)

# 2. Provide the bot token by environment (never in the config file)
export TELEGRAM_BOT_TOKEN=<your-bot-token>

# 3. Run
korvun serve --config korvun.example.json

Full walkthrough — install and verify, configure, message the bot — in QUICKSTART.md. The legacy korvun -config <path> invocation still works via a retrocompat shim; korvun serve --config … is canonical.

Documentation

Guide	What it covers
Quickstart	Zero to a running bot.
Discord bot setup	Create the bot, the Message Content intent, invite, round-trip.
Configuration	Every config field, from the schema and ADRs.
No-code builder	Configure Korvun visually in the browser.
Install & run as a service	Download, verify, hardened systemd unit.
Korvun Desktop	The native app: download, first launch on each OS, verify the desktop artifacts.
Architecture Decision Records	Why each piece is built the way it is (incl. ADR-0032, the CLI contract).
Stage closure docs	What is closed, stage by stage.

Verifying a release

Releases are signed keyless with cosign (Sigstore) and ship an SBOM. Verify the checksums signature, then check your archive against the verified checksums.txt:

cosign verify-blob checksums.txt \
  --signature checksums.txt.sig \
  --certificate checksums.txt.pem \
  --certificate-identity-regexp 'https://github.com/Sebastian197/korvun/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Status

v0.4.0 is the current release. It ships Korvun Desktop — the same in-process core as a native, double-click app (first-run onboarding, OS-keychain secrets, the embedded builder) on macOS, Windows, and Linux, cosign-signed on the free chain — alongside the unchanged headless binary, which is still the way to run Korvun on a server. Validated end to end on real hardware — see the release notes. master builds on toward a production beta; see ROADMAP-V1.md and ROAD-TO-BETA.md for what is closed and what comes next.

Contributing

Contributions follow strict, non-negotiable conventions (TDD first, Context7 before any external library, Conventional Commits, make quality green with -race before every commit). Read CONTRIBUTING.md first.

Security

Please do not open public issues for vulnerabilities. See SECURITY.md for the private reporting channel and supported versions.

License

Licensed under the Apache License 2.0 — see LICENSE.