Mikronous

A small, local personal assistant for the desktop (KDE Plasma on Linux, and Windows 10/11). The brain is Hermes Agent (Nous Research, MIT) with its full toolset: memory, skills, reminders, files, terminal, web and browser. The model runs on your own GPU through llama.cpp. Mikronous adds the Linux desktop shell Hermes does not ship: a tray app, hotkey chat window, desktop notifications, and desktop tools for the agent.

Release: v0.2.0 (changelog), verified on a Plasma 5.27 desktop with an RTX 4070 Ti.

What you get

Piece	What it does	Phase
Hermes profile mikronous	Own persona (SOUL.md), memory, config; full Hermes toolset + the web (keyless, no account)	0
mikronous-llama.service	llama.cpp server on :8081, tuned for ~8 GB VRAM by default	0
mik model	Detect your hardware, pick/tune model, quant, context, KV cache; works for any GGUF	0.5 ✓
Hermes plugin mikronous	Tools: desktop_notify, desktop_open, clipboard, notes_manage, docs_search, set_reminder; skills daily-briefing, file-qa; /notes	1 ✓
mikronous platform	Reminders from Hermes cron arrive as KDE notifications (and in ~/.local/share/mikronous/inbox.jsonl)	2 ✓
Tray app (mik tray)	Hotkey (Meta+Space) data-slate: streaming replies, rites, sanction cards, reminders inbox, boot litany	3 ✓

Install (Linux, KDE Plasma)

Requirements: Linux with KDE Plasma 5.27 or 6 and a systemd user session, Python 3.11+, and a GPU with 8 GB or more of VRAM (NVIDIA via CUDA prebuilts, AMD/Intel via Vulkan; CPU-only works with small models).

Clone this repo at the release tag and run the installer (it installs Hermes Agent for you when it is missing, non-interactively):

git clone https://github.com/GoldenCracker97/Mikronous && cd Mikronous
git checkout v0.2.0
scripts/install.sh
mik doctor

To follow development instead, stay on Main and run mik update now and then (also in the tray menu); it pulls, re-applies the install without touching your model, and restarts the tray.

The installer creates the Hermes profile, links the plugin, installs the mik CLI (with PySide6 for the tray), downloads a prebuilt llama-server from the llama.cpp nightly releases, downloads the default model (Qwen3-4B-Instruct Q4_K_M, ~2.5 GB) into ~/.hermes/models, starts two user services (mikronous-llama and hermes-gateway-mikronous), and starts the tray with a Meta+Space shortcut and an autostart entry. --no-tray skips the desktop part.

The llama.cpp backend is picked from your hardware, no CUDA toolkit needed:

Hardware	Backend	How it is chosen
NVIDIA, driver CUDA ≥ 13.4	cuda-13.4 prebuilt	nvidia-smi reports the driver's CUDA version
NVIDIA, driver CUDA ≥ 12.8	cuda-12.8 prebuilt	same
NVIDIA with an older driver, AMD, Intel	vulkan prebuilt	GPU present without a usable CUDA driver
No GPU	cpu prebuilt

Override with MIKRONOUS_LLAMA_BACKEND=cuda|vulkan|cpu|cuda-build (the last compiles from source and needs nvcc), pin a nightly with MIKRONOUS_LLAMA_TAG=b11146, or force a fresh install with MIKRONOUS_LLAMA_REINSTALL=1.

Already running your own llama-server on :8081? Use scripts/install.sh --no-model.

Gateway topology. The Mikronous profile runs its own gateway process (hermes-gateway-mikronous.service, gateway.standalone: true in its config) with its API server on http://127.0.0.1:8643/v1, authenticated with the API_SERVER_KEY from ~/.hermes/profiles/mikronous/.env. Hermes 0.21+ would otherwise fold every profile into one shared host gateway, but that host did not load this profile's plugin in testing (no desktop tools, no reminder delivery), so the profile stays standalone. Your default profile's gateway is untouched. mik doctor prints the live endpoint.

Network and APIs

Ability	How	What leaves the machine
Devices on the LAN, is a host up, wake a PC	lan_devices, host_check, wake_on_lan	Pings and ARP on your own subnet only
Any HTTP/JSON API	http_request with auth_env: NAME; keys live in the profile .env under names you choose (e.g. GITHUB_TOKEN=) and are injected as headers, never shown to the model	Only the requests you ask for, to the host you name
Home Assistant	Hermes's built-in tools, on once HASS_URL and HASS_TOKEN are in the profile .env; mik doctor shows a row	Calls to your own Home Assistant
Commands on other machines	terminal + ssh with your own ~/.ssh/config aliases and keys	SSH to hosts you name
Learning new procedures	The assistant offers to save a procedure as a skill (skill_manage) and only does so on a yes	Nothing; skills are local files

Writes (POST/PUT/PATCH/DELETE) and commands on other machines require your confirmation first. mik privacy status lists provider keys (which would move inference off the machine, and are not allowed) separately from service keys you added for these integrations. Five skills ship with this: lan, remote-command, home-assistant, api-calls, skill-authoring.

The look: Machine Cult

The tray app is a data-slate: iron-black, brass fittings, your words in Martian red, the machine's answers in phosphor green. Dangerous commands ask for sanction, tool calls show as rites, and the first time the window opens after login it types out a short awakening litany with the loaded model's name (MIKRONOUS_NO_LITANY=1 in the environment skips the animation). The icons are original cog-and-circuit designs made for this project, not any trademarked emblem. Fonts (Cinzel, Share Tech Mono, Grenze Gotisch) ship with the app under the SIL Open Font License.

The assistant speaks in character too. mik voice shows the level; mik voice full|light|plain changes it (full: machine-priest, with hard rules that keep answers short and facts plain; light: a phrase here and there; plain: no persona). The installer defaults to full and keeps whatever you chose on re-runs; MIKRONOUS_VOICE=plain scripts/install.sh sets a different default. In a chat, "speak plainly" also turns the voice off for that conversation.

Try it

1. mik doctor — every row ok.
2. Win+Space → "What can you do?" — a streamed answer from the local model.
3. "Remind me in 1 minute to stretch." → a popup and a highlighted line in the window a minute later.
4. "What do my documents say about ?" → docs_search, then the file is read and named in the answer.
5. "Create an empty file ~/t.txt, chmod 777 it, delete it." → with approvals.mode: manual an approval card appears for the chmod.
6. New chat tomorrow: "What is my name?" → answered from memory once you have told it.

Windows

The same assistant runs natively on Windows 10/11 (Hermes Agent has a native Windows install). What differs is only the plumbing: the model runs as a background llama-server.exe process managed by the tray and mik model start|stop, the gateway is a Scheduled Task created by hermes gateway install, reminders arrive as Windows toasts, the hotkey is Ctrl+Alt+Space (Win+Space belongs to Windows), and the tray autostarts through the per-user Run key. No admin rights are needed. Everything lives under %LOCALAPPDATA%\hermes and %LOCALAPPDATA%\mikronous.

One line, nothing installed beforehand (it fetches Git and Python with winget when missing, clones to %USERPROFILE%\Mikronous and runs the installer):

irm https://raw.githubusercontent.com/GoldenCracker97/Mikronous/Main/scripts/bootstrap.ps1 | iex

Installer options go through $env:MIKRONOUS_INSTALL_ARGS = "-NoModel -Voice light" before that line. If you already have Git and Python (open a new PowerShell after installing them, so PATH is current):

git clone https://github.com/GoldenCracker97/Mikronous; cd Mikronous
powershell -ExecutionPolicy Bypass -File scripts\install.ps1      # -NoModel, -NoTray, -Hotkey "Ctrl+Alt+M", -Voice light, -VoiceInput
mik doctor

Both installers install Hermes Agent themselves when it is missing (MIKRONOUS_SKIP_HERMES_INSTALL=1 opts out). Status: the Windows port is new and has had less real-desktop testing than the KDE version; please report what breaks.

What leaves your machine

Model, memory, notes, documents, chat history	Never leave. The model is pinned to llama-server on 127.0.0.1:8081; Hermes side tasks (summaries, titles) use the same model or are skipped.
Web search and page extraction	Go out, like a browser would, through Hermes's keyless free tiers (Exa, Parallel, Firecrawl, Keenable), rotating between them. No account, no key, no identifiers. mik privacy offline turns both off.
Paid services	Nothing can enrol you. Toolsets that only work with paid keys (image_gen, video_gen, tts, x_search, vision) and the Nous-managed connections toolset are disabled in the profile, Claude Code / Codex login borrowing is off, telemetry is off, and no fallback providers are configured. Nous Portal is only ever enabled by running hermes setup --portal yourself.

mik privacy status prints the live state of each line above; mik doctor includes it as the local-only row.

Commands

Command	Purpose
Meta+Space / mik toggle	Show or hide the chat window (starts the tray if needed)
mik tray	Run the tray app in the foreground (to see errors)
mikronous chat	Talk to the assistant in the terminal (Hermes profile command)
mikronous gateway status	Gateway (API server + cron) state
mik ask "…"	One question through the gateway with the full toolset (--session <id> to continue)
mik update	Pull the latest version from GitHub, re-apply the install, restart the tray (--check to only look)
mik doctor	One-screen health check of every piece
mik tools	Toolsets the gateway exposes to the assistant
mik privacy status|offline|online	What can leave the machine; switch web access off or on
mik docs status|reindex|search <q>	Document index used by docs_search
mik embed on|off|status	Semantic file search: a small CPU embedding server (nomic-embed-text, :8082)
mik voice [plain|light|full]	How much machine-priest the assistant speaks
Alt+Space → mik <question>	Ask from KRunner without opening the window; the answer arrives as a notification
mik settings / mik chats / mik routines	Open the tray's Settings dialog / toggle the past-chats pane / open the Routines tab
mik routine list|add|pause|resume|run|remove	Scheduled agent tasks that deliver to the desktop, from a terminal
mik model start|stop|restart	Start or stop the model server by hand (systemd on Linux, a background process on Windows)

mikronous is the Hermes profile command (created by hermes profile create mikronous); mik is this project's own CLI.

The tray app

mik tray puts a blue M in the system tray. Meta+Space (or a click on the icon, or mik toggle) shows the chat window; Esc hides it. Replies stream in from the local model, tool calls show as small grey lines, and when Hermes wants approval for a command an approval card appears with the choices Hermes offers (Allow once, Allow this session, Deny). Reminders and other cron output arrive in the window too (the plugin pushes them over $XDG_RUNTIME_DIR/mikronous.sock), on top of the KDE notification.

The window talks to the same gateway as mik ask: POST /v1/runs plus the run's SSE event stream, with one Hermes session per chat (New chat in the tray menu starts another; the current one survives restarts via ~/.config/mikronous/tray.json and is reloaded from the gateway).

Header buttons. CHATS (Ctrl+H) opens the past-chats pane: every earlier tray chat from the gateway's session store, newest first; click one to continue it, right-click to rename or delete it. SETTINGS (Ctrl+,) opens a dialog for the things people actually change: voice level, approval mode, internet on/off, notes folder, the folders the file search indexes, the boot litany, whether the model stays loaded on Quit, and on Windows the hotkey. Changes that the gateway reads at start (approvals, internet, file-search folders) restart it for you; the status line says so. UPDATE checks GitHub and, when there are new commits, offers to pull, re-install and restart the tray (the same as mik update). The tray also checks quietly in the background and marks the button UPDATE • when something is new; it never installs anything without being asked.

Semantic file search. Settings → semantic search (or mik embed on) starts a second, CPU-only llama-server with a 150 MB embedding model and splits every indexed document into chunks with vectors. File questions then match meaning, not just words: "the document about renewing my car insurance" finds the policy letter that never says "car insurance". Keyword and semantic ranks are fused, so exact names and numbers still win when you use them. mik embed off removes it; the GPU model is untouched either way.

Ask about the screen. Needs a model that sees: mik model recommend --vision --apply (Qwen3-VL 4B for 8 GB cards, 8B for 12 GB; the projector file downloads with it, and the profile is told the model has vision). Then press Meta+Shift+S (Ctrl+Alt+S on Windows), the SCREEN button or mik screen: pick a region with Spectacle (the whole screen where Spectacle is missing), the window comes back with "What's on my screen?" ready to edit, and the capture is sent with your question to the local model. Before a vision model is loaded, the slate says so and attaches nothing. Captures stay in ~/.local/share/mikronous/screens/ (last 20).

Voice, fully local. Install with scripts/install.sh --voice (Windows: -VoiceInput). Hold VOX in the window and speak; release and the words land in the input box, ready to edit or send. Or tap Meta+Shift+V (Ctrl+Alt+V on Windows) anywhere to start, and again to stop. Transcription is faster-whisper on your GPU or CPU (choose the model size in Settings; the weights download once from Hugging Face, no account). Voice output in Settings reads replies aloud with Piper (one voice file, downloaded once) through a machine-spirit effect: servitor (low, metallic, measured; the default), vox-caster (narrow radio with static), cogitator (crushed, buzzing) or none. Pick one in Settings and press TEST; the Depth and Metal dials push any preset lower or more metallic (middle = as designed). From a terminal: mik say "Rite complete, Magos." --effect servitor --depth 70 --metal 80. The effects are synthesised on the fly (ring modulator, comb resonator, band-limit, bit-crush, static); no sounds are taken from any game. Nothing is sent anywhere.

KRunner. Press Alt+Space, type mik what time is it in Tokyo, Enter. The question runs in a fresh chat; when the window is hidden the answer comes as a notification (click it to open the slate). mik settings, mik routines, mik chats, mik new and mik update work there too. The tray serves KRunner's D-Bus plugin interface itself; the installer drops the plugin file and restarts KRunner. MIKRONOUS_NO_KRUNNER=1 turns it off.

Media and system control. "Pause the music", "next track", "what's playing?", "volume 30", "mute", "dim the screen to 40", "don't disturb me for an hour", "lock the screen", "bring up Firefox". MPRIS, PipeWire/PulseAudio, KDE's brightness service and Plasma's do-not-disturb timer on Linux; media and volume keys, WMI brightness and LockWorkStation on Windows. There is deliberately no suspend, reboot or shutdown.

Selected text, anywhere. Highlight text in any app and press Meta+Shift+Space (Ctrl+Alt+Shift+Space on Windows, mik selection from a script): a small menu offers Explain, Summarise, Rewrite, Translate → and Ask about it. The answer streams into the slate; Rewrite and Translate also put it on the clipboard, ready to paste over the original. The key is set by the installer next to the main one (MIKRONOUS_HOTKEY_SELECTION=… to change it).

Drop files in. Drag a file or folder from Dolphin (or Explorer) onto the window: its path is quoted into the message, and the assistant opens it directly, no search needed. Several at once work too.

Routines. Settings → Routines (or the tray menu, or mik routines) lists the scheduled rites: agent tasks Hermes's cron runs on the local model and delivers to this desktop as a notification and a plate in the slate. NEW… starts from a preset (morning briefing at 08:00, watch a page every 6 h, weekly notes review) or a custom schedule and prompt; schedules are what Hermes cron accepts (every 1d at 08:00, every 6h, weekdays at 9am, 0 18 * * 5). Pause, run now, edit and delete are there too, and reminders set in chat appear in the same list. The assistant itself still cannot create or change schedules except through set_reminder.

Model lifecycle. The tray owns the model: it starts mikronous-llama.service when it launches (the status line reads "the cogitator wakes" until the first answer is possible) and stops it on Quit, so quitting Mikronous frees the VRAM for games or other work. The tray menu also has "Unload model" / "Load model" for the same without quitting. Reminders keep firing either way: the gateway stays up and no-agent reminders need no model. Set MIKRONOUS_KEEP_MODEL=1 in the environment to keep the model resident across Quit.

Approvals. When Hermes flags a command as dangerous (rm -rf, chmod 777, sudo, …) the window shows an approval card with the choices Hermes offers. The default mode is smart: a guardian pass on the local model lets clearly harmless flagged commands through and asks you about the rest, so you will not see a card for every chmod. mikronous config set approvals.mode manual asks every time; mik doctor and scripts/install.sh leave the setting alone unless you re-run the installer, which restores smart.

Meta is the Windows key. The installer registers the shortcut in ~/.config/kglobalshortcutsrc (Plasma ignores a .desktop file's X-KDE-Shortcuts until it is there) and restarts the shortcut daemon; set MIKRONOUS_HOTKEY=Meta+M before running install.sh for a different key, or change it in System Settings → Shortcuts → Mikronous.

Desktop tools the agent gets

Tool	What it does	Where things live
desktop_notify	KDE notification via D-Bus (notify-send fallback)
desktop_open	Open a URL, a file, or launch an installed app by name (firefox, dolphin)	.desktop files in the usual XDG dirs
clipboard	Read / set the clipboard (Klipper via qdbus6, wl-paste/xclip fallback)
lan_devices / host_check / wake_on_lan	Local-network tools (see Network and APIs)
http_request	Any HTTP/JSON API, keys by name from the profile .env
set_reminder	"Remind me in 20 minutes to…": schedules a Hermes cron job in no-agent mode whose output is delivered as a desktop notification; list / cancel too	jobs in mikronous cron list; scripts in the profile's scripts/
notes_manage	Durable notes and to-dos: add, list, search, done, update, delete; also /notes in chat	~/Mikronous/notes/*.md (one file per note, plain markdown you can edit)
docs_search	Full-text search over your document folders, then the agent reads the hit with read_file	index in ~/.local/share/mikronous/docs.sqlite; folders from MIKRONOUS_DOCS_DIRS (default ~/Documents)

Reminders. "Remind me in 20 minutes to …" or "every weekday at 9 …" makes the agent call set_reminder, which creates a Hermes cron job (no model involved when it fires) delivered to the mikronous platform: a KDE notification, plus a line in ~/.local/share/mikronous/inbox.jsonl and the tray window, so nothing is lost while you are away. mikronous cron list shows the jobs. Reminders are created from chat sessions (the tray, mikronous chat, or mik ask "…"); Hermes hides the scheduling tool in mikronous -z one-shots by design.

mik docs status | reindex | search <q> manages the document index from the terminal. PDFs and Office files are extracted with Hermes's own converter when indexed from inside a Hermes session. Two skills ship with the plugin: mikronous:daily-briefing and mikronous:file-qa.

Fit the model to your hardware: mik model

mik model detect                 # GPU / VRAM / RAM / CPU and the memory budget
mik model list                   # presets with a green / amber / red verdict for this machine
mik model recommend --apply      # pick the best preset, download, write settings, restart
mik model use qwen3-8b --apply   # a specific preset
mik model use hf:unsloth/Qwen3-14B-GGUF --apply          # any Hugging Face GGUF (Q4_K_M picked)
mik model use hf:owner/repo:file.gguf --ctx 32768 --apply # exact file + context override
mik model use ~/models/anything.gguf --apply              # a local file
mik model tune --kv f16 --ctx 65536                       # change KV cache / context and restart
mik model tune --backend vulkan                           # switch llama.cpp build (cuda|vulkan|cpu)
mik model status                 # current settings and whether they still fit
mik model bench                  # prompt + generation tokens/s, VRAM in use

How the fit works: weights (file size) + KV cache (context × layers × KV heads × head size × bytes per element) + runtime overhead must fit the free VRAM minus 512 MiB headroom. The tool keeps the 64k context Hermes needs by quantising the KV cache first (f16 → q8_0 → q8_0/q4_0 → q4_0), only then shrinks the context, and only then spills layers to system RAM (LLAMA_NGL). Models with a shorter native context get YaRN rope scaling automatically. Everything lands in ~/.config/mikronous/llama.env, which you can also edit by hand, then systemctl --user restart mikronous-llama.

Hermes's own local-model catalog (27B+ models) shows up in mik model list too when Hermes is installed from git.

Layout

profile/            Hermes profile template (SOUL.md, config.yaml, env.example)
hermes_plugin/      The `mikronous` Hermes plugin (tools + delivery platform)
mikronous_cli/      `mik` CLI (doctor, ask, tools, privacy, docs, model, tray, toggle)
mikronous_model/    hardware-fit library used by `mik model`
mikronous_tray/     PySide6 tray app: data-slate window, runs/SSE client, reminder inbox socket, theme + bundled fonts
profile/voices/     Persona levels swapped into SOUL.md by `mik voice`
packaging/          .desktop files (Meta+Space shortcut, autostart) and icon
skills/             Skills shipped with Mikronous
systemd/            User units + env template
scripts/            install.sh, install-llama.sh, fetch-model.sh (Linux); install.ps1 (Windows)

Contributing

pip install -e ".[tray,dev]"
QT_QPA_PLATFORM=offscreen pytest

The tests run headless (Qt offscreen) and need no Hermes install; CI runs them on every push.

License

MIT (see LICENSE). Bundled fonts are under the SIL Open Font License; see mikronous_tray/assets/README.md.