Kana Hermes Waifu Assistant

A waifu assistant for your Hermes Agent: a living, talking anime face for the Hermes you already run.

Kana turns Hermes into a Hermes waifu: a Live2D character who answers in the language you write in and, with her voice on, speaks every reply in Japanese with lip sync. Hermes stays the only agent: its tools, files, memory, and sessions work exactly as before.

Contents

• Why Kana
• Quick start
• Screenshots
• Features
• Deploy on a VPS
• Connecting to Hermes
• Voice
• Live2D avatars
• How it works
• Development
• Documentation

Why Kana

Hermes is powerful, but a terminal or chat log is not much company. Kana is the waifu layer on top of it: a presentation layer, not another assistant.

• One agent. Every reply comes from your Hermes session. Kana never runs a second model, translator, or tool loop.
• Your installation, untouched. Kana starts or adopts the official hermes serve and never patches or writes into Hermes.
• Private by design. The Hermes session token stays inside the Kana server. Your browser talks only to Kana, behind your own password.

Quick start

You need Linux x64 (glibc), Node.js 22.13+, and Hermes Agent installed.

npm install -g kana-alya
kana

The first run asks you to create an access password, then opens Kana in your browser. There is no default password.

Useful commands:

Command	What it does
kana	Start Kana on this computer and open the browser
kana serve	Run headless for a VPS or systemd service
kana password	Create or change the access password (--stdin for scripts)
kana doctor	Check Node.js, Hermes, password, voice, and data folders
kana setup	Explain the optional local voice engine download
kana config	Open the advanced config.json

Your data (password hash, settings, voice profiles, model cache) lives in $KANA_DATA_DIR when set, otherwise $XDG_DATA_HOME/kana or ~/.local/share/kana.

Screenshots

Dark theme, stage patterns, and files Hermes sends	Hermes slash commands, read live from your installation
An avatar wardrobe and stage backgrounds	Chat-first on phones, with Kana in a call-style tile

Features

Conversation

• Replies in the language you write in, as Markdown (lists, code, links), with no language setting to pick. With the voice on, Kana also speaks each reply in Japanese; switching language affects new replies only.
• History comes from Hermes, so conversations follow you to other browsers.
• The Hermes activity log shows which tools ran for each reply.
• Files Hermes sends (audio, video, images, documents) appear as a player, a preview, or a Download button instead of a file path.
• Composer with file attachments, voice dictation, and a model picker. The picker opens with the last Hermes model list at once and refreshes it in the background.
• On phones and tablets the conversation fills the screen and Kana sits in a small call-style tile framed on the face.

Hermes controls

• The live, categorized / command catalog with argument completion, including your installed skills.
• Dedicated dialogs for approvals and clarifications. Sudo passwords and secrets are never stored.
• /new, /sessions, /resume, /branch, /title, /status, /compress, and more.
• /restart restarts the hermes serve Kana started and brings you back to the same conversation; /reload applies ~/.hermes/.env changes. Models added to Hermes's config.yaml appear in the model picker without either.

Character

• Live2D avatars: the official Haru and Mao samples, or a model folder imported into your browser. Settings → Avatar is a wardrobe of portrait cards.
• Emotions, motions, lip sync, and cursor-following gaze.
• Stage backgrounds (an illustrated room, soft patterns, or your own image), plus light and dark themes.

Voice

• Local Japanese speech with Irodori-TTS v4.1 Anime on a CPU engine, with voice cloning from a short, consented sample.
• Or an external voice service: Pollinations (ElevenLabs, Qwen TTS, Grok TTS, and more).
• Lip sync follows the audio, and Stop cancels generation on the server.

Security and operations

• Password sign-in with lockout that never blocks your own known browsers and does not depend on IP addresses (safe behind shared home internet).
• Cross-site request protection, server-side logout, and an owner-only data folder.
• Installable app shell, and safe diagnostics that redact tokens, prompts, and secrets.
• A configuration guide inside Kana at /docs, in English and Indonesian.

Deploy on a VPS

kana serve runs the same app headless. Set the password once as the account that owns Hermes, then run Kana behind HTTPS:

KANA_DATA_DIR=/var/lib/kana kana password
KANA_DATA_DIR=/var/lib/kana kana serve --port 3000

• Run it with systemd as the same user that runs Hermes. Linux only lets that user read the Hermes session token.
• Put Nginx in front for HTTPS. Use proxy_set_header Host $http_host;, disable buffering for /api/hermes/events, and allow client_max_body_size 14m.

The complete systemd unit and Nginx configuration are in the VPS deploy checklist. To build from source instead of npm, see Install Kana.

Warning

npm run dev is a development server only. Never keep it running behind Nginx or on a VPS.

Connecting to Hermes

Usually there is nothing to do. Kana:

1. finds the Hermes executable in PATH or the usual install locations (the official installer, pipx, uv, Nix, Homebrew, and Termux);
2. adopts a running hermes serve owned by the same user, or starts one on 127.0.0.1 with a token that only the Kana server knows;
3. connects your browser through Kana's authenticated relay.

If detection fails, kana doctor shows what it found. Set hermes.executable in config.json to an absolute path and restart Kana. Details: Hermes auto-detection on Linux.

To start Hermes yourself, give it a token Kana can discover:

HERMES_DASHBOARD_SESSION_TOKEN="a-long-random-token" hermes serve --host 127.0.0.1 --port 9119

After you change Hermes's configuration, you rarely need to leave Kana:

Change	What to do
A model or provider added to config.yaml	Nothing. It appears in the model picker right away.
~/.hermes/.env (API keys)	Type /reload.
MCP servers	Type /reload-mcp now.
Anything else Hermes reads at startup	Type /restart. Kana restarts the hermes serve it started and resumes the conversation. A Hermes you started yourself is restarted where you started it.

Voice

Voice is optional and off on new installs. Turn Kana's voice on or off in Settings → Voice; replies always stay readable as text.

• Local Irodori TTS (default). Irodori-TTS v4.1 Anime on the irodori-c engine, on the CPU of the machine running Kana (Linux x86-64; no Python or GPU). Nothing is downloaded until you press Download voice engine in Settings → Voice: about 480 MB for the engine and 3.1 GB for the model, checksum-verified and resumable. A model already in your Hugging Face cache is reused instead of downloaded. Pick the bundled Kana voice, the model's own faster voice, or clone one from a consented sample.
• Pollinations. Set tts.provider to pollinations with your key, model, and voice. Each external service is its own integration; API keys stay in the server's config.json and never reach the browser.

Configuration examples are in Speech, including every local engine option. CPU synthesis is slower than realtime on modest hardware; the engine's int8 path is used automatically on CPUs with AVX-512 VNNI.

Live2D avatars

Choose Haru or Mao in Settings → Avatar, or import a model folder with the Import Live2D card. Each avatar is a card with its portrait, which Kana takes from the stage and keeps in your browser. Imported folders stay in your browser (IndexedDB) and are never uploaded. An imported avatar's ⋯ menu has its size, Rename, and Remove, and it has its own bindings for the mouth parameter, emotion expressions, and motion groups, which you can preview before saving.

The official samples load from Live2D's pinned sample repository and are not redistributed by Kana.

This content uses sample data owned and copyrighted by Live2D Inc. The sample data are utilized in accordance with terms and conditions set by Live2D Inc. This content itself is created at the author's sole discretion. See the official sample model terms.

How it works

Browser (Kana UI)
  │  session cookie, same origin only
  ▼
Kana server (Next.js)
  ├─ /api/hermes/*    → one server-held WebSocket → hermes serve  → Hermes agent
  ├─ /api/voice/tts/* → local irodori-c engine or Pollinations
  └─ data folder      → password hash, settings, activity log, voices

Hermes events are translated into a stable internal model that drives the transcript, activity log, avatar emotion, and audio. Hermes starts each reply with a short header (the emotion, the language, and the Japanese speech while the voice is on) and then writes the answer in Markdown. In the browser, each workspace keeps its shared state in small per-concern zustand stores, and plain service classes talk to Hermes, voice, and the avatar, so typing re-renders only the composer. More in process boundaries and the security model.

Development

git clone https://github.com/misaalya/kana-hermes.git
cd kana-hermes
npm ci
npm run password                         # once, for your local data folder
npm run dev -- --hostname 127.0.0.1      # http://127.0.0.1:3000

Build and run the production package from the checkout:

npm run package:local
node bin/kana.mjs

Checks:

npm run lint && npx tsc --noEmit && npm test   # fast
npm run quality                                # full gate, including browser journeys

Real-environment checks (need Hermes, network, or target hardware) are npm run test:hermes:restart, npm run test:live2d:official, and npm run test:package:npm. Local-voice latency stays a manual check on the target machine, because Kana ships no latency harness. Contributor rules are in AGENTS.md.

Documentation

Topic	Guide
Every config.json setting, inside Kana	Open /docs in Kana (English and Indonesian)
Installing locally or on a server	Install Kana
config.json, TTS providers, deployment mode	Configure Kana
Attachments, dictation, model picker	Use the composer
VPS, systemd, Nginx, supported platforms	Supported environment
Threat model and reverse proxy	Kana security model
Release channels and Hermes compatibility	Compatibility
Quality gates and releases	Quality gates · Release checklist
The documentation map	docs/README.md
Changes and migration notes	CHANGELOG.md

License

MIT. Live2D sample models are subject to Live2D's own terms, above.