Calm on the surface. Capable inside. A local-first productivity assistant.
- ⚡ Fast & lightweight — seconds to boot, a trimmed runtime
- 🏠 Local-first — your sessions, memory and files never leave this machine
- 🔌 Open, no lock-in — any OpenAI-compatible endpoint; plugins installed on demand
- 🎯 Outcome-first — desktop and mobile browsers, voice-ready; leads with what gets done
English · 简体中文
A real task, done end-to-end — Iris planned, wrote, verified and reported a complete single-page website, recovering on its own from a stream drop, an oversized write and a sandbox permission limit along the way:
| Main workspace | Settings | Skills hub |
|---|---|---|
 |
 |
 |
| Scheduled tasks | Usage analytics | Mobile |
|---|---|---|
 |
 |
 |
→ gitcode.com/badhope/iris — official home on GitCode: source, releases, issues, and the in-repo landing page (docs/).
→ github.com/X33834/iris — twin release host (CI + Releases). Both hosts publish the same v* tags; see MIRROR.md.
→ Live landing page — interactive overview: screenshots, architecture tour & one-click download.
| Download | Format | For |
|---|---|---|
| ⬇ Latest release — ZIP (GitCode) · GitHub | ZIP | Windows / macOS — recommended |
| ⬇ Latest release — TAR.GZ (GitCode) · GitHub | TAR.GZ | Linux / servers — full source tree |
Building from source (
git clone+pip install -e ./agent) always gives you the newest fixes. Release archives track tagged versions; feature counts in this README intentionally stay number-free because the project ships continuously.
# 1. Clone (GitHub primary; GitCode mirror is faster in mainland China)
git clone https://github.com/X33834/iris.git && cd iris
# git clone https://gitcode.com/badhope/iris.git && cd iris
# 2. One shared venv for BOTH components (Python 3.11+)
python3 -m venv .venv && source .venv/bin/activate
# 3. Install the agent (editable — pulls the agent + its deps into this venv)
pip install -e ./agent
# 4. Install the WebUI deps into the SAME venv, then launch
pip install -r ./webui/requirements.txt
cd webui && python3 server.py
# → open http://127.0.0.1:8787 in your browserWhy one venv? The WebUI server process runs the agent in-process, so the Python interpreter you launch
server.pywith needs both stacks installed in it: the agent (step 3) and the WebUI's minimal deps (step 4:pyyaml+cryptography). Installing the agent into system Python and then runningserver.pywith a different interpreter is the classic "server starts, then chat fails withAIAgent not available" trap.The WebUI auto-detects the agent checkout; if it can't find it, point it explicitly:
export IRIS_WEBUI_AGENT_DIR=$PWD/agent. Launcher env vars (port, host, state dir, auth) are listed inwebui/docs/environment-variables.md; bare-metal deployment notes live inwebui/docs/DEPLOYING.md.
Updating from source:
git pull
source .venv/bin/activate
pip install -e ./agent --upgrade
pip install -r ./webui/requirements.txt
# restart the WebUI (Ctrl-C and rerun step 4, or ./webui/ctl.sh restart)Done. Pick a built-in model, or plug in any OpenAI-compatible endpoint:
model:
provider: custom:my-provider
default: my-model
custom_providers:
- name: my-provider
base_url: https://your-endpoint/v1
api_key: your-key📘 Full setup, provider wiring, image generation, approvals and troubleshooting live in
docs/— start withdocs/quickstart.md.
Hermes is a brilliant agent framework — but it grew heavy. Iris keeps the full Hermes core while making the whole thing feel like a modern consumer AI app:
| Hermes (original) | Iris | |
|---|---|---|
| ⚡ Boot time | slow, loads everything | seconds — lazy loading, uvloop-native |
| 📦 Footprint | heavy | leaner — web UI needs only pyyaml + cryptography |
| 🖥️ Web UI | dev-tool style | modern consumer UI — light/dark + many skins, command palette |
| 🔌 Model support | provider-specific adapters | protocol-first — any OpenAI-compatible endpoint |
| 🧩 Plugins | bundled always | built-in catalog, install / uninstall on demand |
| 📚 Knowledge base | — | RAG with CJK-aware full-text search |
| 🔒 Privacy | — | local-first. No account. No telemetry. |
flowchart LR
U["🌐 Web UI<br/>chat · settings · plugins<br/>command palette"] --> S["🐍 Python Server<br/>api/routes.py · streaming"]
S --> A["⚙️ Iris Agent Core<br/>tools · memory · skills · cron"]
S --> KB[("📚 Knowledge Base<br/>SQLite FTS5 · CJK search")]
S --> PM["🧩 Plugin Manager<br/>built-in catalog · on-demand"]
S --> PL["🤖 Protocol Layer<br/>OpenAI-compatible"]
PL --> M["Any LLM endpoint<br/>one base_url + key"]
A --> T1["🛠️ Tools<br/>web · terminal · files"]
A --> T2["🧠 Memory & Skills<br/>long-term · cron"]
Two components, one experience:
agent/— the rebuilt Iris core: tools, plugins, memory, skills, cron, protocol routingwebui/— the modern control surface: chat, settings, plugin marketplace, knowledge base
| ⚡ Lightweight core | uvloop event loop, lazy-loaded modules, trimmed runtime |
| 🔌 Any model, any provider | OpenAI-compatible protocol layer — base URL + key, done |
| 🧩 Plugin ecosystem | Built-in catalog, one-click install / uninstall / toggle |
| 📚 Knowledge base RAG | Upload docs → local CJK-aware index → answers from your data |
| 🎨 Modern Web UI | Command palette (Ctrl+Shift+P), light/dark + many skins, rich settings |
| 🧠 Memory & skills | Long-term memory, skills hub, cron, kanban, todo, session search |
| 🗣️ Voice-ready | Dictation + hands-free voice + text-to-speech |
| 🌐 Multi-language | Full i18n, defaults to Chinese (中文), switch anytime |
| 🔒 Local-first & private | Sessions, memory, knowledge — all on your machine |
Iris is an independent, deeply-customized distribution of Hermes (the open-source agent framework by Nous Research). We:
- Kept the full Hermes core — upstream module layout is preserved so upstream fixes merge cleanly
- Rewrote the entire front-end in a mainstream consumer-app style
- Slimmed the deploy surface — the web UI runs on two Python deps; heavy providers stay optional
- Added knowledge-base RAG, command palette, preset prompts, ECharts rendering, and more
| Doc | What it covers |
|---|---|
docs/quickstart.md |
Install, first run, model setup |
docs/configuration.md |
config.yaml reference — providers, image gen, approvals |
docs/usage.md |
Daily use — chat, tools, tasks, kanban, memory, skills |
docs/faq.md |
Common issues & fixes (rate limits, stalls, upgrades) |
Released under the MIT License, built upon Hermes by
Nous Research (MIT). Original copyright and attribution preserved. Full license in LICENSE.
- ⭐ Star this repo if Iris is useful to you
- 🐛 Report issues — we fix fast
- 🧩 Publish plugins to the catalog
- 🌍 Translate Iris into more languages
Iris — your AI, your rules.