KKORVIN

Open-source. Self-hosted. No lock-in. v1.2.0

Your AI agent, run from one private dashboard.

Dashboard-first. Memory-persistent. Model-agnostic. No lock-in.

KORVIN is a personal AI agent that runs on your own machine and answers from one private dashboard — voice, memory, skills, and model switching in a browser. Telegram and other channels are optional. Your data never leaves your infrastructure.

Get Started View on GitHub 
Agent:     running
Dashboard: live (Cloudflare Access)
Channels:  dashboard + Telegram
Model:     DeepSeek / Gemini via LiteLLM
Voice:     Whisper STT + Kokoro TTS
Memory:    SQLite persistent

What works today

A full agent stack, built to run light.

Private dashboard

Run the whole agent from one browser tab — chat, switch models, browse memory, watch system health, and freeze the agent instantly. Protected by Cloudflare Access. Works on phone or desktop.

Channels — dashboard & Telegram

Answer from the dashboard, or send text and voice messages over Telegram and get replies in text or speech. More channels are on the roadmap.

Voice — STT + TTS included

Send a voice message, get a spoken reply. Faster-Whisper tiny.en transcribes speech (~95 MB RAM). Kokoro TTS (bm_lewis) generates voice replies. Both installed automatically — no extra setup.

Persistent memory

Every conversation stored in SQLite. Sliding window keeps the agent alive forever.

Model switching

Tap a model in the dashboard. No restart. DeepSeek V4, Gemini Flash, Claude, or any Ollama model.

11 skills included

Web research, YouTube transcription, dependency scanning, VirusTotal security scan, CVE patch research, named sessions, persistent rules, session summarization, memory search, daily digest, and goal heartbeat — all wired to Telegram and dashboard chat.

Named sessions & persistent rules

/save and /load switch conversation context by name. /rule add stores your preferences — response style, length, format — and every reply respects them automatically.

Defense-in-depth security

SSRF guard on every outbound request (blocks private and local addresses), an allow-listed egress broker for skills, a sandboxed skill runner, server-enforced rate limiting (20 req/60s), layered prompt-injection detection, secret redaction in output and logs, and automated smoke tests.

Dashboard

Manage your agent from a browser.

The Korvin dashboard runs on your server, protected by Cloudflare Access. Chat directly, switch models with one tap, browse memory, track tokens, and freeze the agent instantly. All from your phone or desktop.

Deployment guide

Honest setup requirements

One command installs everything.

Install on any Linux system. Windows support included. You need a Telegram bot token and a Gemini or DeepSeek API key. The installer sets up all services automatically.

git clone https://github.com/nosistech/korvin.git
cd korvin
sudo bash install.sh

Start with API keys. Once running, swap in any LiteLLM-compatible model — including local Ollama — by editing one config file. No code changes, no rebuilds.

Add-ons

Optional upgrades after install.

Korvin runs fully out of the box. These options are available when you need more.

STT quality upgrade

distil-medium.en

Switch from tiny.en to distil-medium.en for higher transcription accuracy. Set it in the dashboard under Voice settings. Requires about 384 MB RAM — the base install runs on far less.

Dashboard setting — no reinstall
Model swap

Any LiteLLM-compatible model

Korvin routes through LiteLLM. Swap in Claude, GPT-4o, Mistral, or a local Ollama model by editing one config file. No code changes. Switch back in the dashboard.

Edit litellm_config.yaml — restart LiteLLM
Voice customization

Kokoro voice selection

Korvin speaks in Kokoro's bm_lewis voice by default. Swap to any other Kokoro voice ID — bm_george, af_bella, af_sky, and others — by changing one line in src/voice/voice.py. No reinstall, no restart of LiteLLM.

One-line code edit — restart korvin service

Skills

Eleven skills. Unlimited ways to use them.

Every skill works through Telegram and dashboard chat — just describe what you need. New skills can be added without touching the core.

Research [topic] Web Research

Searches the web via DuckDuckGo and synthesizes a structured report with key findings and sources. No API key required — runs entirely through Korvin.

Ways to use it

  • "Research competitors to my SaaS idea: [describe it]" — market scan in seconds
  • "Research [topic] then write an executive summary" — research feeds directly into the LLM for a structured output
  • "Every Monday research the top AI news from the past week" — automated weekly intelligence feed
/patch [package] CVE Patch Research

Queries CVE databases for a package or dependency, returns severity scores, affected versions, and patch recommendations. Output is AI-synthesized — always verify against NVD or vendor advisories before acting.

Ways to use it

  • "/patch openssl" — severity scores and patch path for the current version
  • "/patch node" — known vulnerabilities in your runtime before a deploy
  • Pair with Dependency Scan — scan deps, then patch anything flagged in one flow
/save [name]  •  /load [name] Named Sessions

Save your current conversation under a name and restore it later. Switch between contexts — a project, a client, a research thread — without losing history.

Ways to use it

  • "/save project-alpha" before switching topics — pick up exactly where you left off
  • Keep separate sessions per client — load the right context before each call
  • Save a research session mid-way, load it the next morning and continue
/scan [url|ip|hash]  •  /scan system Security Scan

VirusTotal lookup across 90+ engines for any URL, IP, or file hash. /scan system reads your weekly Lynis audit report — Korvin never runs Lynis directly, preserving the privilege boundary.

Ways to use it

  • "/scan 185.220.101.47" — know if an IP is flagged before connecting
  • "/scan system" — Lynis score and top findings from the last weekly audit
  • All HIGH-risk scans require /confirm before executing — no accidental lookups
/scan deps Dependency Scan

Reads package.json and requirements.txt and reports dependency metadata — names, versions, and known issues. Zero-execution: never invokes npm, pip, or any package manager.

Ways to use it

  • Pre-deploy ritual: "/scan deps" — flag anything stale or suspicious before pushing
  • "Every Monday run /scan deps" — automated weekly hygiene, no manual checking
  • "Run /scan deps then write a formal dependency audit I can share with the team" — the LLM formats the output as a shareable report
/youtube [url] YouTube Transcription

Transcribes any YouTube video and returns the full text. Paste a URL in chat without any prefix — Korvin detects it and transcribes automatically.

Ways to use it

  • Paste a URL and say "pull out the 5 most actionable takeaways" — transcript feeds into the LLM in the same message
  • "Transcribe this conference talk and turn it into structured notes: [url]" — replaces a 45-minute watch
  • "Research [topic] then transcribe [url] and tell me what the video adds or contradicts" — cross-skill fact check
/rule add [preference]  •  /rule list Persistent Rules

Save any preference and Korvin applies it to every future response — no settings file, no re-explaining. Rules persist across sessions and accumulate over time.

Ways to use it

  • "/rule add always use bullet points" — every response reformats automatically
  • "/rule add keep answers under 150 words" — forces brevity without asking each time
  • "/rule list" then "/rule remove 2" — manage your preferences like a settings panel
/summarize  •  /search [query] Memory Management

Compress a long conversation into a summary, or search across your entire message history by keyword. Both work on the live SQLite database — no data leaves your server.

Ways to use it

  • "/summarize" at the end of a long research session — condense it before sharing or continuing tomorrow
  • "/search invoice" — find every time you discussed invoices, across all past sessions
  • Summarize then save — "/summarize" followed by "/save project-name" gives you a compact, named checkpoint
/log Activity Log

Returns a timestamped log of recent agent activity — commands run, skills triggered, errors caught. Useful for auditing what the agent did while you were away.

Ways to use it

  • "/log" after returning to the dashboard — see everything that happened since your last session
  • Pair with /status — "/log" for what ran, "/status" for current resource usage
  • Debug a missed cron or failed scan by checking the log first before digging into service logs
Automatic — 23:00 daily Daily Digest

Every night at 23:00 Korvin summarizes the day's session and delivers it to Telegram. The digest is also appended to MEMORY.md under today's date header for long-term recall.

Ways to use it

  • Wake up to a plain-text summary of everything Korvin discussed or executed the day before
  • Each digest entry in MEMORY.md becomes a searchable journal — "/search [topic]" finds it weeks later
  • Pair with Goal Heartbeat — digest shows what you did, heartbeat shows what you meant to do
/goal [text] Goal Heartbeat

Save a goal and Korvin sends a check-in message every 4 hours. The chat ID is persisted so restarts don't break the heartbeat. "/goal clear" stops it.

Ways to use it

  • "/goal ship the release today" — Korvin pings you three times during the workday
  • Habit nudge: "/goal 30 minutes of reading before bed" — gentle reminder, no app needed
  • "/goal clear" the moment you hit it — clean slate for the next priority

Agent intelligence

Korvin learns how you like to work.

You don't fill in a settings file. You talk normally — Korvin picks up corrections and applies them to every future response.

Preference learning

Say "don't do that", "next time always use bullet points", or "I prefer shorter answers" — Korvin detects the correction and saves it as a rule. Every future response applies your preferences without you repeating them.

  • Detected from natural language — no special syntax
  • Preferences persist across sessions
  • /rule add [preference] — add one explicitly
  • /rule list — see everything saved
  • /rule remove — delete one rule

Deep research with /grill

Before researching a complex topic, Korvin can ask you 3–5 clarifying questions to sharpen the brief. The better the context, the better the output.

  • /grill [topic] — get clarifying questions before research begins
  • Answer in one message — Korvin synthesizes and searches
  • Pair with Web Research for precise, context-aware briefs
  • Use before any ambiguous or high-stakes request
/grill [topic]         — clarifying questions before research
/rule add [pref]       — save a persistent preference
/rule list             — view all saved rules
/new                   — clear session, start fresh
/summarize             — summarize the current session
/search [query]        — search your message history
/brief                 — toggle concise one-sentence mode

Custom skills

Build your own skill in two files.

Korvin ships with a plugin system. Drop a directory into skills/, define a safe literal trigger pattern, and Korvin auto-loads it on the next restart — no changes to the core required.

How it works

Each skill is a directory with two files: a skill.json manifest and a handler.js module. The manifest defines the trigger pattern and permission level. The handler receives the matched message and returns a string response.

  • No registration needed — auto-discovered at startup
  • Three validated permission labels: read-only, network-read, local-status
  • Permissions are audit metadata; handler code still runs as the Korvin service user
  • Path traversal blocked — handler must stay inside skill directory
  • Errors are caught and reported — bad handlers don't crash the agent
// skills/my-skill/skill.json
{
  "name": "my-skill",
  "description": "What this skill does",
  "trigger": "^my trigger (.+)",
  "permission": "read-only",
  "handler": "./handler.js"
}

// skills/my-skill/handler.js
async function run(message, match) {
  return "You said: " + match[1];
}
module.exports = { run };

Telegram commands

What you can say right now.

Research [topic]          — web search + structured report
/youtube [url]            — transcribe any YouTube video
/scan [url|ip|hash]       — VirusTotal lookup (90+ engines)
/scan system              — latest Lynis security audit
/patch [package]          — CVE research + patch recommendations
/grill [topic]            — clarifying questions before research
/save [name]              — save current session by name
/load [name]              — restore a named session
/rule add [preference]    — save a persistent rule
/rule list                — view your active rules
/goal [text]              — set a goal; 4-hour check-in nudge
/goal clear               — remove goal and stop heartbeat
/brief                    — toggle concise mode on/off
/summarize                — summarize the current session
/search [query]           — search your message history
/scan deps                — dependency metadata scan
/status                   — agent + service health
/log                      — recent activity log

Documentation

Everything you need to get running.

Quickstart Commands Configuration Deployment

Roadmap

What is still being built.