irises-setup-hermes
Install Irises — a user-facing front-end (web chat / CLI, plus the engine bridge) that uses this hermes as its deep-work engine. Explains it, checks prerequisites, asks the person's questions and a cl
SKILL.mdskills/irises-setup-hermes/SKILL.md
GitHubIrises Setup (hermes engine) — install it, on the person's yes
You install Irises, from your own terminal, once the person has said yes. Your job is to explain what Irises is, check that the box can run it, ask the few questions that are theirs to answer, run the installer, get the gateway restarted the safe way, and verify the result.
The one thing that needs care is the gateway restart at the end. Hermes reads the API server and the bridge plugin only when its gateway starts, so the install is not live until that restart. How it happens depends on where this conversation is running — check that first (step 0), because getting it wrong kills your own turn mid-reply.
What Irises is (say this in your own words)
A user-facing texting assistant — a fast conversational front line — that delegates ALL deep work
(research, email, files, reminders, memory) to this hermes. This hermes stays completely unmodified;
Irises talks to it only through the OpenAI-compatible API server (API_SERVER_ENABLED) and the cron
REST API.
Irises rides on top of this hermes: on boot it auto-detects it (sets OPS_BACKEND=hermes),
reuses this hermes's API key, and makes its own voice inherit this hermes's provider, endpoint and
model — including when this hermes runs on an OpenAI-compatible or otherwise obscure API (OpenAI,
Azure, vLLM, deepseek-direct, Groq, a self-hosted gateway…), not just OpenRouter or Anthropic. The
voice runs this hermes's OWN model on every lane it can reach — no stand-in slug is substituted — so
chat turns cost and pace what this hermes's model does; deep work uses that same model, as always.
There is nothing to configure by hand.
0. Where are you running? (decides the restart)
echo "gateway=${_HERMES_GATEWAY:-0}"
gateway=0— the hermes terminal chat (hermesin a shell). You are not inside the gateway, so the installer can restart it for you and your turn survives. Run the install without--no-gateway-restart; the restart is part of it.gateway=1— a messaging chat (Telegram, WhatsApp, Discord, Signal…). You are a child of the gateway. A restart from here would kill this very turn, which is why your terminal guard refuses one. Run the install with--no-gateway-restart, report the result, then ask the person to type/restartin this chat./restartis hermes's own command: it lets running turns finish, restarts the gateway, and tells them when it is back. (The installer also skips the restart on its own whenever it sees_HERMES_GATEWAY=1— pass the flag anyway, so your command says what it does.)
1. Check the prerequisites (read-only)
node --version # needs 22.13+ (Irises's local store uses the builtin node:sqlite)
git --version
curl --version
hermes gateway status
hermes config get model.default # the model Irises's voice will inherit (step 2)
hermes config get model.provider
hermes config get model.base_url
Those three are the only config values you read. Never read model.api_key, and never print
~/.hermes/.env or any other file with a key in it — you name a key, you never show one.
If node --version is below 22.13, look for a newer Node already on the box (nvm under
~/.nvm/versions/node/, or Homebrew) and tell the person which one to put on PATH. Do not install
Node or any system package yourself — stop and tell them what is missing.
On Windows, your terminal already runs commands in Git Bash, which is the shell the installer
needs. Say the honest part up front: the Windows paths (the Git Bash install, the Irises Task
Scheduler task) are stub-tested only, and this may be the first real run. Linux and macOS are the
platforms with mileage on them.
2. Ask, explain, and get a clear yes
Ask only what is theirs to decide, and offer the default:
- Which chats should Irises front? Default
*:*— every chat on every platform this hermes speaks, including their operator and control chats. A narrower answer becomes--front, e.g.--front 'telegram:*'or--front 'telegram:*,whatsapp:+1555*'. - Port? Default 3000. Anything else becomes
--port N. - Timezone? Default the host's own. Anything else becomes
--tz Europe/Paris(an IANA zone).
Then tell them, before you run anything:
- Which model and API Irises will use. The person cannot pick these here (the terminal menu asks;
this install keeps the default), so say them plainly, with the real values from step 1:
- Engine: this hermes. Deep work — research, email, files, reminders — is handed to you and runs on your model, exactly as it does today.
- Her voice (every chat reply, plus two small helper calls per turn) inherits your model, on
your API and your key:
<model.default>via<model.provider>at<model.base_url>, paid from the key you already use — name it (OPENROUTER_API_KEY,ANTHROPIC_API_KEYorOPENAI_API_KEYin hermes's.env), never its value. Say the consequence too: every chat turn now costs and paces like one of your turns, so a large, slow or reasoning model makes her chat slower and dearer. - The exception. If the provider is one Irises cannot call directly —
bedrock,vertex,gemini,copilot,nous,moa— or the provider is empty or one Irises does not know and the model id has no/in it, her voice cannot inherit: it runs on Irises's own default models instead, on whichever OpenRouter, Anthropic or OpenAI key hermes's.envhas. If it has none of those, her voice has no model until they add one. Deep work still runs on your model either way. Say which case applies before they say yes. - Want a different voice model? That takes its own API key, which never travels through chat.
After the install, in their own terminal:
IRISES_MODEL_API_KEY=… bash ./scripts/configure.sh --model-lane openrouter --model-slug <id>(oranthropic;openaialso needs--model-base-url). It stops her borrowing your key;bash ./scripts/configure.sh --model-inherithands her voice back to your model.
- What changes in this hermes: its
.envgetsAPI_SERVER_ENABLEDandAPI_SERVER_KEY(if the API server is not on already),IRISES_URL,IRISES_FRONT,IRISES_PUSH_TOKENandIRISES_BRIDGE_TOKEN, after a backup next to the file. Every key is recorded in~/.irises/install-manifest.json, and the uninstall takes each one back out. The bridge plugin goes into hermes's plugin folder. No hermes source code is touched. - What gets installed: a clone in
~/irises, its npm dependencies and build, and a user-level service (systemd --useron Linux, a LaunchAgent on macOS, a Task Scheduler task namedIriseson Windows) so she survives a reboot. Her data lives in~/.irises. No database, no root. - The gateway restarts at the end (or on their
/restart, from a messaging chat). Any hermes chat in flight ends there. Hermes then posts its own "♻️ Gateway online" message in their home channel — that is hermes, not Irises, and it can be silenced per platform with<platform>.gateway_restart_notification: falsein hermes's config (theirs to edit, not yours). - With bridge mode on, Irises answers the fronted chats in her own voice and uses you as her
engine. You stay reachable directly in a terminal, still answer anything
IRISES_FRONTdoes not cover, and answer everything whenever Irises is down (fail-open, so a broken front never drops messages). - Shortly after the restart, Irises usually texts first — a one-time introduction, sent only on a chat this hermes has genuinely exchanged messages in before (the "first move", see Notes). A text from her out of the blue is the feature working, not a glitch.
Wait for a clear yes. "Sounds good" to the explanation is not a yes to the install — ask "Shall I install it now?" and act on the answer to that.
3. Run the install
Clone, unless ~/irises already holds an Irises clone — then use it as it is (the installer repairs
in place; pulling new code is an update, step 6). Never touch an Irises checkout anywhere else.
git clone https://github.com/criblaurens/irises ~/irises
Then, from inside the clone, the installer in its flag form. --yes is required — the interactive
menu (bash ./scripts/irises.sh, npm run setup) asks questions on a keyboard you do not have, so
never run it.
From the hermes terminal chat (gateway=0):
cd ~/irises && bash ./scripts/engine-setup.sh --engine hermes --yes --front '<their answer>'
From a messaging chat (gateway=1):
cd ~/irises && bash ./scripts/engine-setup.sh --engine hermes --yes --front '<their answer>' --no-gateway-restart
Add --port N / --tz ZONE if they answered with one. Keep the quotes around the --front value.
It takes several minutes (npm install and two builds). Run it with background=true and
notify_on_complete=true, or in the foreground with timeout=600 (your foreground limit). Tell them
it is running and roughly how long, so the silence is not a surprise.
Read the end of the output. The last line is RESULT: <token> and the exit code means:
0 installed and verified · 1 a step failed (the message says which) · 2 a usage mistake in your
command · 4 Irises did not answer /health in time · 5 installed, but the gateway did not come
back verified. Relay the summary block in plain words — what is installed, where, and what is left.
On anything but 0, quote the failing line, point at ~/.irises/logs/server.log, and stop: do not
retry with different flags or try to fix it by starting things by hand.
4. The restart
gateway=0: the installer already restarted the gateway; the summary'sgateway:line saysbounced and verified. Nothing more to do.gateway=1: the summary'sgateway:line saysNOT restarted. Ask the person to type/restartin this chat, and to message you once hermes says it is back. That message starts a fresh turn — go to step 5 then. If they prefer a terminal,hermes gateway restartthere does the same; you never run it yourself from a messaging chat.
5. Verify (read-only)
curl -s http://127.0.0.1:3000/health
Use the port they installed on if it is not 3000. A JSON body with a version object is a healthy
install. Its models object is what is actually live, so confirm the model in plain words from it:
models.voice lists each voice role with its model, provider and endpoint, and
models.engine names your deep-work model. If it differs from what you told them in step 2, say so.
If any voice role shows "configured": false, her voice has no working key on that lane — tell them
which key it needs (in hermes's .env, or IRISES_MODEL_API_KEY with configure.sh --model-lane),
in their own terminal, never pasted into chat. Then tell them where to talk to her: any fronted chat, the web chat at
http://127.0.0.1:3000, or npm run chat in the clone for a terminal session. If the health check
fails, point them at ~/.irises/logs/server.log and the installer's output — do not try to fix it by
starting anything.
6. Later: settings, update, uninstall
Same rules for all of these: say what it will change, get a clear yes, run it from ~/irises with
--yes, and from a messaging chat always add --no-gateway-restart and then ask for /restart.
Change a setting — the port, the service, which chats she fronts, the model her voice runs on, the
browser chat, the timezone, the dashboard password, or any documented .env key, without re-running
the installer:
bash ./scripts/configure.sh --show # report only: every setting and where it came from
bash ./scripts/configure.sh --tz Europe/Paris --yes
bash ./scripts/configure.sh --front 'telegram:*' --yes
bash ./scripts/configure.sh --model-inherit --yes # hand her voice back to this hermes's model
--show is read-only — run it first when they ask what is set. A change to Irises's own settings
restarts her and checks /health; a --front or --port change can edit this hermes's .env and
needs a gateway restart to take effect. Secrets never go on the command line: --set KEY with the
value in IRISES_SET_VALUE, which the person sets in their own terminal, never in chat.
Update:
bash ./scripts/update.sh
It pulls, rebuilds, restarts Irises, and restarts the gateway (skipped with --no-gateway-restart).
If the new build fails to compile or come up, it rolls back to the one that was running. Irises checks
for new builds on her own and mentions one once, in chat, when it is waiting.
Detach — usually what someone means when they say they want this hermes back:
bash ./scripts/engine-setup.sh --detach-engine --yes
It undoes every engine-side change — the bridge plugin, the keys Irises added, the values it moved,
IRISES_FRONT — so this hermes is left as if Irises had never been installed, except that the
.bak-irises-* backup files stay. Irises herself, her service, the clone and ~/.irises are left
alone; running the install again attaches her back.
Uninstall:
bash ./scripts/engine-setup.sh --uninstall --yes
Stops and unregisters the service, removes the bridge plugin and the engine-side keys the installer
added, and keeps their data. Deleting the data is theirs to type, never yours: --purge-data
deletes ~/.irises (memory and database) and cannot be undone — hand them that command
(--archive-data alongside it writes a ~/.irises-backup-<timestamp>.tar.gz first) instead of
running it.
7. Never
- Never restart the gateway yourself from a messaging chat — not with the hermes CLI, not through
systemctl,launchctl,schtasks, or process control, not by scheduling it for later. Your terminal guard refuses those for a reason; do not route around it. Ask for/restart. - Never run the interactive menu (
bash ./scripts/irises.sh,npm run setup), and never pipe answers into it. - Never install before a clear yes, and never pass
--purge-data. - Never install system packages (Node, git, curl) — say what is missing.
- Never touch another Irises checkout that already exists somewhere else on this machine.
- Never edit hermes's config by hand — the installer makes its own
.envchanges, backed up and recorded; anything beyond that (like the restart-notification key) is the person's to change. - Never print a secret. The installer never shows one; do not go looking in the
.envfiles.
Notes
- Details, security notes, and troubleshooting live in
docs/ENGINES.mdinside the clone. - Which model is live: Irises's voice model vs. this hermes's deep-work model show in
/health, on the/dashboardoverview, and vianpx tsx ./scripts/print-model-map.ts. Irises will also tell the person her model plainly if they ask in chat, and her build, and whether an update is waiting. Override any voice role with<ROLE>_PROVIDER/<ROLE>_MODEL_OPENROUTER/<ROLE>_MODEL_OPENAI/<ROLE>_MODEL, or turn inheritance off withENGINE_MODEL_INHERIT=off(seedocs/ENGINES.md§ Model inheritance). - On its first boot, Irises sends this hermes a one-time engine-mode onboarding over the API
server: how to recognize a delegated request, the reply contract, the full-reach invitation and its
hard limits (including never messaging the user on any channel itself). Hermes appends it to its own
SOUL.md by its own hand — nothing in hermes is edited by Irises. To remove it later, tell hermes by
chat to delete that section; to skip the send entirely, set
ENGINE_ONBOARDING=offin the Irises.env. The text is printed bynpx tsx ./scripts/print-engine-doctrine.tsinside the clone. - Once after that, Irises makes the first move: she asks this hermes what it already knows about
its user — a normal chat message hermes answers in its own words, nothing in hermes is read or
edited — and keeps a sanitized version in her own memory so her first words are not cold. Then she
either texts the user first, only on a chat this hermes has genuinely exchanged messages in
before, or sends nothing at all and folds the introduction into her reply the first time they text
her. Exactly once per install; skip it with
FIRST_MOVE_ENABLED=falsein the Irises.env.