Total Pageviews

Thursday, 19 November 2026

让instinct帮我搭建基于next.js的静态博客程序ygi

我跟instinct的对话如下,共9张截图。









 
我得到的博客地址: 
https://brightmann.github.io/ygi/

项目地址:

https://github.com/yoksel/yoksel.github.io

 https://github.com/yoksel/yoksel.github.io/issues/26

https://github.com/brightmann/ygi

在此处https://github.com/brightmann/ygi/tree/master/data/posts ,新建源帖

2026-11-19-ce.md ,内容为:
---
title: 稀奇古怪的中国经济
tags: [misc1, misc2, misc3]
description: 这是一篇文章
date: 2026-11-19T21:23
---
 
此处写正文或html code
(详见 https://github.com/brightmann/ygi/blob/master/data/posts/2026-11-19-ce.md?plain=1)
 
 


 

Windows 上的安卓app运行器apkstart

 Windows 上的安卓app运行器:双击 APK 即可安装,安装完成后,会创建桌面图标。app以独立窗口运行。

CI Release License: MIT Platform

Windows 上的安卓应用运行器 —— 让安卓应用像 Windows 原生软件一样被安装和使用。 注:本项目为早期版本,作者自娱自乐产物,所有修改都是作者下班和休息日在处理,开源免费,不插广告,暂时也不是很好用,没有找过营销号推广.

  • 🖱️ 双击 .apk 即安装:注册 .apk 文件关联后,在资源管理器里双击 APK,自动解析 → 安装 → 生成桌面图标,全程无需打开任何模拟器界面。
  • 🧩 每个应用对应一个桌面图标:图标从 APK 内部离线提取并转为多尺寸 ICO,双击桌面图标 = 直接启动该应用,与打开一个原生 Windows 软件的体验一致。
  • 🪟 应用就是一个窗口:运行时以带窗口模式启动(无头模式下 Android 不出 VSYNC,应用进程活着但屏幕上是空的),ApkStart 把这块窗口改标题、换真实应用图标、按竖屏比例摆好位置,就是一个独立应用窗口;全屏铺满屏幕高度并居中,窗口模式可自由拖动缩放且按应用记忆尺寸。
  • 🔍 能被 Windows 搜到:安装后同时创建桌面 + 开始菜单(程序\ApkStart\)快捷方式,按应用名在开始菜单搜索即可直达,任务栏按应用分组。
  • 📁 数据互通:%USERPROFILE%\ApkStartShared ↔ 安卓内 /sdcard/ApkStartShared 持续双向同步,安卓应用存下的文件直接出现在本机。
  • 🪶 极致轻量:壳层本身零第三方依赖(连 ZIP / PNG / ICO / AXML 解析都是手写的),运行时按需拉起,空闲自动回收;也可以完全复用你机器上已有的安卓运行时,额外占用为零。

主界面

┌────────────────────────────────────────────────────────────┐
│  桌面图标(真实应用图标 .lnk)                              │
│      │  双击                                               │
│      ▼                                                     │
│  ApkStart.exe --launch <包名>                              │
│      │  运行时未启动?→ 自动拉起(Android Emulator + API34)│
│      ▼                                                     │
│  按系统解析出的 LAUNCHER 入口启动(不是 APK 里的主 Activity)│
│      │  存活观察 18 秒,闪退自动重试 / 重置数据 / 补权限     │
│      ▼                                                     │
│  模拟器窗口 = 应用窗口(改标题、换图标、竖屏比例、全屏居中) │
└────────────────────────────────────────────────────────────┘

下载即用(不想编译)

两个源内容一致,国内建议用 Gitee:

安装包(三种形态,内容与版本号完全一致):

形态 文件名 何时选它
商店版 ApkStart_<四段版本>_x64.msix 从 Microsoft Store 装。内置完整运行时,装完不联网;自更新交给商店
完整便携版 ApkStart-v*-win64-full.zip(约 830 MB,解压 ~1.3 GB) 不想装、也不想等下载:解压即用,运行时(模拟器 + 系统镜像)全在包里
安装版 ApkStart-v*-Setup.exe(约 1.3 GB) 想要桌面/开始菜单快捷方式、卸载项
轻量便携版 ApkStart-v*-win64-portable.zip(96 MiB,解压 ~227 MB) 只想先试试,首次启动再联网下载运行时

所有形态的 ApkStart.exe 都写入了品牌图标 + 版本资源(FileDescription = ApkStart 安卓应用运行器, CompanyName = RoutineMiku,版本与 package.json 同步),不再是 Electron 的默认图标和 33.x 版本号。 自己从源码打包时:npm run pack(轻量)/ npm run pack:full(完整)/ npm run build:msix(商店包)。

画面铺满是怎么做到的

模拟器的物理面板方向(hw.lcd.width/height)就是画面的真实形状。面板方向和应用自己声明的 screenOrientation 不一致时,Android 只会给应用一个信箱式的中间窄条 —— 两侧补黑,换窗口大小、 改 wm size、改 letterbox 样式都填不满(这套组合逐项试过,见 src/core/apk.js 的注释)。

所以 ApkStart 在安装 APK 时离线解析 AndroidManifest.xml,统计出这个应用天然是横屏还是竖屏 (启动 Activity 加权;全 sensor / fullSensor 的会在首次运行后再问安卓要一次实际值),存进 apps.json,启动时按它选面板:

  • 红果短剧这类竖屏应用 → 竖屏面板 720×1280,正立、铺满、density 190(sw606dp)同时给出平板排版;
  • 墨读这类横屏应用 → 横屏面板 1280×720,正立、铺满。

只有「面板方向和应用方向不一致」的那一次才重启运行时(约 40 秒,标题栏会给出提示), 之后同方向的应用都是秒进。标题栏的旋转按钮会把这个应用的方向记住(其它应用不受影响), 设置 → 应用窗口 → 屏幕方向可以改成「强制横屏 / 强制竖屏」。

排版由「逻辑密度」决定:720 宽按 190dpi 算等于 606dp,正好越过 Android 的 600dp 平板断点, 红果短剧的双列剧集页、设置页分栏都只在这个密度下出现(镜像默认 320dpi 只有 360dp,是手机排版)。 这就是设置里的「平板排版」开关,默认打开;关掉会回到手机排版。

在线更新(自动选较快的源)

设置 → 软件更新 → 「检查更新」,或托盘右键 → 「检查更新」。发现新版本后点「立即更新」即可。

  • 安装版下载 ApkStart-v*-Setup.exe 静默安装;
  • 轻量版下载 ApkStart-v*-win64-portable.zip,解压后覆盖程序目录——运行时目录(%APPDATA%\apkstart\runtime)、已装应用与快照都不在程序目录里,所以更新不会丢东西;
  • 替换动作由一段独立 PowerShell 脚本完成(等主进程退出 → 覆盖 → 重新拉起),不会出现「请手动关闭程序」的弹窗,也不会在桌面上残留模拟器窗口。

更新链路不是死连 GitHub,而是每次现测现选:

  1. 同时问 GitHub 与 Gitee 的最新版本,取版本号更高的那个(一个源超时/被墙不影响另一个);
  2. 把「源站直连 / Gitee 同名资产 / 镜像前缀」列成候选,每个地址真下 256KB 测速, 只算「收到首字节之后」的吞吐(握手时间不计入,否则高延迟大带宽的源会被误判成慢);
  3. 按实测速度排序,用最快的那条分块并行下载;失败自动换下一条。

设置里的「下载与更新源」可以强制只用某一边(企业网络只放行一个域名时用), 也可以关掉公共加速镜像、或改用自建镜像前缀。Gitee 附件单文件上限 100MB, 便携包换用 7-Zip 的 deflate(-mx=9)压缩后是 95.0MB,所以 Gitee 上也是 一个能直接双击解压的整包(以前要切成 .part1/.part2 手工拼接,那版已经废弃)。 两个源的同名包体积并不完全一样,客户端按测速结果只挑一个源下完,不会混拼。

两个仓库都是公开的,Gitee 的发行版列表匿名就能读,不需要填任何 token。 (只有在 Gitee 限流返回 403/429 时,才需要在设置里填一个只读 token 提高额度。)

开箱即有的默认行为(不用去设置里找):

  • 开机自动启动,常驻托盘;双击桌面图标直接进应用。
  • 安装 APK 后自动创建桌面 + 开始菜单两份快捷方式,Windows 搜索能直接搜到应用名;老版本漏建的会在启动时自动补齐。
  • 应用窗口是原生渲染(非投屏):全屏铺满屏幕高度并居中、保持手机比例不变形;窗口模式保持竖屏,可自由拖动缩放,每个应用的尺寸单独记忆。随时按 F11 或右键托盘切换。
  • 安装后自动授予应用申请的运行时权限,不会卡在系统授权框;应用闪退会自动重试、必要时重置应用数据后再拉起。
  • 网络直接用主机的网络:安卓侧走 QEMU 用户态 NAT,出口复用主机的物理网卡,不会在 Windows 上创建任何虚拟网卡 / 虚拟交换机(不需要装驱动、也不多一个网络适配器)。不需要联网下载、不需要改任何网络设置。

设置页:分好类,还能搜

设置项越来越多,所以从 0.6.0 起设置页按用途分成八类,左侧一列导航:

分类 装了什么
常用与安装 运行时与环境、一键完成、开机自启、磁盘占用与清理
显示与窗口 显示模式、自动全屏、屏幕方向、镜像自动旋转、平板排版、窗口承载方式、安卓系统设置
操作与输入 鼠标键位、键盘映射(游戏手柄)
性能与资源 资源策略、画质、数据分区、系统语言、中文输入法、快照、开机预热、高级参数
网络与下载 更新与下载源、公共加速镜像、下载线程数
诊断与修复 本机体检 · 自动配置、驱动 · 兼容补丁、自动检测 · 智能诊断
集成与文件 桌面与应用、文件互通、系统集成
更新与关于 软件更新、关于

顶部还有一个搜索框:输入「横屏」「内存」「代理」等关键词,命中项跨分类显示, 不会出现「搜到了却看不见」。上次停留的分类会记住,下次打开就在原地。

自动检测(自动 debug)

设置 → 诊断与修复 → 「自动检测 · 智能诊断」。后台定时把机器查一遍,出问题按分类列出来:

  • 运行时:上次启动失败的真实原因、引导卡死、残留锁文件、孤儿模拟器进程、快照空壳、没有硬件加速
  • 设备连接:adb 未授权(安卓弹了「允许 USB 调试吗」没人点)、offline、运行时在跑但 adb 看不到设备
  • 存储:磁盘余量、数据分区配置值与实际值不一致(差量盘挡住扩容)、共享目录不可写
  • 设置:屏幕方向策略与物理面板打架、独立窗口下的自动全屏不生效
  • 网络 / 日志:安卓侧没网、下载源不通、最近日志里的错误

每条问题都能一键处理(重启运行时、清锁、清孤儿进程、作废快照、清理磁盘、重置安卓网络…)。 修复后自动复检。

两条原则:探测失败不会被当成问题(拿不到状态就报「不知道」,绝不瞎报), 只在新问题出现时提醒一次(老问题不重复打扰,恢复了只静默记账)。 默认每 10 分钟一次,可在同一页关掉或改间隔。

从源码构建

# 1. 安装依赖(含 Electron 运行时)
npm install

# 2. 启动并完成运行时部署(一次性下载 adb / Android Emulator / 系统镜像)
npm start

# 3.(可选)注册 .apk 双击安装
npm run assoc:on

# 4. 打包便携版(免安装,可直接分发)
npm run pack
# 产出 dist/ApkStart-win64-portable/ApkStart.exe
# 5. 压成 zip 发布(必须用这个脚本,别用 Compress-Archive:体积会大 5MB、塞不进 Gitee)
node build/zip.js dist/ApkStart-win64-portable ApkStart-win64-portable.zip

单文件 EXE(内置完整运行时,装完不再联网)

如果希望「一个 EXE 发出去,对方双击就能跑,不用等下载」,用这条:

# 先把 engine/ 整理成可分发运行时(system.img 用 xz/LZMA2 极限压缩,3.1GB → 约 1.1GB;
# 同时裁掉 emulator 里用不到的部分:arm64 的 QEMU、Vulkan 后端、多语言包、qsn/自检工具、VR 资源)
npm run runtime

# 再打成安装版 EXE(electron-builder nsis 目标,装到当前用户目录)
npm run build:exe
# 产出 dist/release/ApkStart-<版本>-Setup.exe

体积构成(实测):Electron 约 180MB、emulator 瘦身后约 480MB、系统镜像 xz 压缩后约 1.1GB, 最终安装包约 1.32GB(相比 gzip 方案省约 490MB)。能再压的硬下限就在 system.img 那条 (它就是安卓系统本身,且是 verity 保护的镜像,无法从外部裁掉 GMS 组件)。 网络默认走主机 NAT,不创建虚拟网卡,所以也不依赖任何额外驱动。

首次启动会把 xz 镜像展开到 %APPDATA%\apkstart\system-images(约 20 秒,只做一次), 之后每次直接复用。AVD 与已装应用固定存放在 %APPDATA%\apkstart\avd, 即使便携版每次解压到临时目录也不会丢。

运行时说明:完全独立,不依赖任何第三方模拟器

ApkStart 是一个自持的项目,运行时组件全部由自己下载、校验和管理(位于 %APPDATA%\apkstart\runtime)。 轻量版默认从本项目的 GitHub Release 下载整包(ApkStart-runtime-*.zip),拿不到才退回下表里的官方源:

组件 来源 大小 用途
adb(platform-tools) dl.google.com 官方源 ~8 MB 安装/启动安卓应用
Android Emulator dl.google.com 官方源(8 线程并行下载) ~440 MB 运行时引擎(自带设备模型与 GPU 转译)
Android 14 通用系统镜像(Google Play x86_64) dl.google.com 官方源 源镜像 ~3.1 GB(xz 后 ~1.1 GB) 唯一的基础层:x86 应用、仅含 ARM 库的应用、GMS 都能跑,镜像即系统,无需安装
AEHD 驱动(可选) dl.google.com 官方源 ~0.2 MB 硬件加速(或用 Windows「虚拟机平台」WHPX)

首次使用时,「运行时」页会引导完成以上部署(一键部署):

  1. adb 与运行时引擎、系统镜像自动下载(官方源实测 10+ MB/s);
  2. 部署完成后自动开机,之后双击桌面图标自动拉起,全程无感。

运行时部署向导

设备兼容性(自动处理,无需干预)

  • 没有硬件加速时自动回退软件模拟;启动失败按「渲染后端 → 加速方式 → 内存/冷启动」最多 4 组参数自动重试。
  • -gpu 按引擎版本自动选择(37.x 用 software,老版本用 swiftshader_indirect),不再使用已弃用的模式。
  • 内存/核心数按物理内存自动推导(2–4 GB / 2–4 核),数据分区从 16 GB 降到 4 GB;端口动态挑空闲的,中文路径自动转短路径,AVD 锁文件自动清理。
  • 失败原因会翻译成中文并附上修复建议;设置里可「导出诊断报告」。
  • 大文件下载默认 8 线程分块 + 断点续传,不支持 Range 的源自动回退单流。
  • 只用自带运行时,与其它模拟器无关:ApkStart 不探测、不接管、也不驱动你机器上装的 MuMu / 雷电 / 蓝叠 / WSA; 装没装它们、它们怎么升级、端口怎么变,都不影响 ApkStart。设置里也不再提供「切换引擎」的选项。
  • 本机体检 · 自动配置:装完先查一遍 CPU 虚拟化(VT-x/SVM)、Windows 虚拟机监控程序平台、 显卡与显存、内存和系统版本;能自动改的(内存 / 核心 / 画质 / 渲染后端)直接写进设置并固化成驱动, 需要管理员权限的给按钮,只能在 BIOS 里改的告诉你怎么改。见 docs/preflight.md。
  • 驱动(兼容补丁)扩展:如果某台机器必须改启动参数才跑得起来(老显卡 GLES 版本低、没开硬件加速、 某版驱动一开硬件渲染就崩),可以写一份 JSON 补丁:声明匹配哪些机器、命中后改哪些参数。 设置页里能导入、启用、导出本机模板;补丁只改白名单里的启动项,不执行任何代码。见 docs/drivers.md。

容器式低成本运行

  • 只读基础层:system-images/ 全机一份,所有应用共享,不再同时存 AOSP + 兼容两套镜像。
  • 薄可写层:单个 AVD 用差量用户数据 + 命名 quickboot 快照;关闭最后一个应用窗口后(空闲时)把内存状态存成快照,下次开机走恢复而不是冷启动。
  • 空闲预热(默认开启):像 WSA / 应用宝电脑版一样,ApkStart 一启动就在后台把安卓环境引导好(窗口全程隐藏),点应用时只剩一次 am start;代价是空闲常驻约 1 GB 内存,设置里可关闭。
  • 冷启动提速:加速与引擎版本探测结果落盘缓存(按 exe 指纹失效)、跳过无谓的 wmic 进程枚举、开机探测改为自适应间隔(350ms 起)、guest 侧准备命令合并成一次 adb 往返;一次启动少等 5–10 秒。
  • /data 由 ApkStart 自己造:官方系统镜像里的 userdata.img 只是 1 MB 全零占位,真正的格式化原本由 SDK 工具完成 —— 直接拉 emulator.exe 会跳过这一步,于是 /data 挂不上、guest 掉进 recovery 重启循环,表现就是「等好几分钟还是打不开」。现在首次启动会自己生成一份 4 KB block、带 ENCRYPT(文件级加密)与 ext_attr(SELinux 标签)的 ext4,并用自带的 qemu-img + resize2fs 撑到配置的容量。实测冷启动 ~23 秒、命中快照 ~10 秒。
  • 快照完整性校验:保存被打断留下的空壳(只有几十字节的 snapshot.pb)会被识别并清理;新版 emulator 写的是 ram.bin(老版本是 ram.img),两种命名都认,不会再把刚存好的 3 GB 快照误判成空壳删掉。
  • 命令窗口彻底不出现:qemu 的控制台窗口属于 conhost.exe,pid 和 qemu 对不上,靠 pid 白名单一个都藏不住;模拟器的网络守护进程 netsimd 还会自己再弹一个黑窗。现在改为「启动模拟器之前就打开常驻压制 + 按窗口类名/标题兜底(emulator / qemu / netsim)+ 开机 90 秒内 120ms 扫一次」。
  • 打开软件只看到软件界面:模拟器主窗(Android Emulator - apkstart5554)永远不会单独出现在桌面上 —— 它要么被压制隐藏,要么已经被 SetParent 嵌进应用窗口。关掉应用窗口时会先把它从宿主窗口上摘下来并藏好,再销毁宿主(顺序反了 Windows 会把它重新挂到桌面并显示);应用退出后窗口代理还会继续「守」最多 3 分钟,避免开机途中退出的那台模拟器在几十秒后把黑窗亮出来。
  • 按需下载:遇到仅含 ARM 原生库的应用才会补齐通用镜像;.apks / .xapk 拆分包自动用 install-multiple 安装。
  • 可回收:构建时裁掉非 x86_64 的 QEMU 目标(约 400 MB);设置页可清理旧镜像、旧快照、锁文件和遗留 AVD。

目录结构

apkstart/
├─ src/
│  ├─ main.js              主进程:窗口/托盘/单实例/命令行分发/IPC
│  ├─ preload.js           安全桥接
│  ├─ ui/                  渲染层(原生 HTML/CSS/JS,无框架)
│  └─ core/
│     ├─ zip.js            极简 ZIP 读取器(按需解压)
│     ├─ axml.js           Android 二进制 XML 解析
│     ├─ arsc.js           resources.arsc 资源表解析(应用名/图标路径还原)
│     ├─ apk.js            APK 元信息:包名/版本/启动 Activity/图标/ABI
│     ├─ png.js            零依赖 PNG 编码器 + 程序图标绘制
│     ├─ shortcut.js       多尺寸 ICO 生成 + .lnk 快捷方式
│     ├─ assoc.js          .apk 文件关联(HKCU,免管理员)
│     ├─ adb.js            adb 客户端(安装/启动/同步/截图/…)
│     ├─ engine.js         运行时管理:探测/模拟器托管/空闲回收
│     ├─ sharer.js         本机 ↔ 安卓共享目录双向同步
│     ├─ installer.js      安装流水线编排
│     └─ store.js          应用清单与设置持久化
├─ engine/                 运行时组件下载缓存(emulator / system-images / platform-tools)
├─ tools/platform-tools/   便携 adb 放置处
├─ test/                   单元测试 + Electron 集成测试 + 冒烟截图
├─ build/pack.js           便携版打包
└─ scripts/assoc.js        .apk 关联命令行开关

命令行

ApkStart.exe                      打开主界面
ApkStart.exe <路径\to.apk>        安装 APK
ApkStart.exe --launch <包名>      直接启动应用(桌面快捷方式使用此参数)

测试

npm test                                   # 纯 Node 单元测试 + 引擎链路测试(不需要网络)
npm run test:boot                          # 真实引导测试:用 61MB Alpine guest 验证 QEMU 参数/建盘/优雅关机
npm run selftest                           # 运行时自检:装好 Android 后一键验证 安装→启动→截图→共享目录
electron test/electron-integration.js      # ICO / 快捷方式集成测试
electron . --smoke test\shot.png           # 启动应用并截图(界面冒烟)

npm run selftest 是装好系统后的「验收命令」——它会对当前设备依次检查 adb 连接、 Android 版本、freeform 支持、共享目录双向同步,加 --apk 某应用.apk 还会完整走一遍 安装 → 独立窗口启动 → 前台确认 → 截图。

设计取舍(诚实说明)

  • 不是从零实现的 hypervisor:安卓内核、GPU 转译、ART 运行时是数年级别的工程,本项目选择站在 AOSP/QEMU/adb 的肩膀上,把工程量集中在「原生应用级体验」上——这正是应用宝电脑版、Google Play Games PC 版等产品共同的架构思路。
  • 共享目录是同步而非挂载:Windows 无 root 时无法在安卓侧挂载 NTFS 目录,采用秒级双向同步达到同等体验。
  • ARM-only 应用 / 字节系应用:设置里开启「ARM 兼容模式」即可切换到 Android 14(API 34)Google Play 镜像(内置新版 ndk_translation 翻译层),仅含 ARM 原生库的应用可以安装运行。实测红果免费短剧(com.phoenix.read,arm64-v8a-only)可正常安装、进入推荐流并播放视频——旧版 API 30 镜像上会因字节系自带非标准 signal handler 触发翻译层保护性断言(DoBadTrampoline SIGABRT),Android 14 镜像的新版翻译层已修复。个别应用自带更深的反模拟检测(如强制校验真实传感器/基带),仍可能受限;安装失败或启动崩溃时 ApkStart 会给出中文说明。
兼容模式下运行红果免费短剧(Android 14 · AEHD 硬件加速)
红果短剧在 ApkStart 兼容模式运行

提示「未启用硬件加速」怎么办

安卓模拟器在 Windows 上只有两条加速路:

方式 是什么 谁需要管理员 装完要重启吗
WHPX Windows 自带功能「Windows 虚拟机监控程序平台」 开这个功能时 要
AEHD Google 自家内核驱动 装驱动时 不用
  • 安装版 / 便携版:设置 → 环境自检 → 「未启用硬件加速」右侧点修复,会弹一次 UAC,自动开 WHPX;如果开不起来(系统不支持 / 你点了否),会自动改装 AEHD 驱动。

  • 微软商店(MSIX)版:商店应用不能自行提权,所以点「修复」会直接帮你打开「启用或关闭 Windows 功能」对话框,勾选 「Windows 虚拟机监控程序平台」(英文 HypervisorPlatform),确定后重启电脑一次即可。

    也可以自己用管理员 PowerShell 跑:

    dism /online /enable-feature /featurename:HypervisorPlatform /all /norestart
    dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

注意别只开「虚拟机平台(VirtualMachinePlatform)」——那是 WSL2 要用的,模拟器要的是 「虚拟机监控程序平台(HypervisorPlatform)」。只开前者,emulator -accel-check 依然会说不可用。

没加速也能跑(纯软件模拟),只是开机会慢到几分钟——这也是应用里那条提示的目的, 不是启动失败。

桌面图标不对 / 显示成 ApkStart 的图标怎么办

每个安卓应用的桌面快捷方式都应该用它自己的图标(安装时从 APK 里解出来存到 %APPDATA%\apkstart\icons\<包名>.ico)。如果显示成了 ApkStart 的绿色播放键,或者干脆是空白图标:

  1. 设置 → 系统集成 → 重建快捷方式(会把桌面和开始菜单的快捷方式按当前应用清单重写一遍, 连同图标和任务栏身份一起修好);
  2. 还不行就删掉那个快捷方式,在 ApkStart 里右键应用 → 重新创建快捷方式/重装一次。

为什么会坏:早期版本整理图标时把这些 .lnk 图标的 IconLocation 统一指向了 ApkStart 的品牌图; 另外把便携版整个目录挪到别处后,.lnk 里记的绝对路径也会失效。重建一次即可。

顺带说一句:每个应用的快捷方式都带自己的 AppUserModelID, 所以固定到任务栏后,任务栏按钮和固定项用的是同一个应用图标,不会混成 ApkStart。

为什么我的 adb devices 看不到这台安卓设备

ApkStart 的 adb 服务跑在专用端口 5044,和系统里你自己的 adb(5037)完全隔开 —— 这样你的 Android Studio / scrcpy 不会跟它抢设备,它也不会误杀你手动开的模拟器。

要用命令行连它:

$env:ANDROID_ADB_SERVER_PORT = 5044
adb devices              # 会看到 emulator-5554

⚠️ 不要对着 5555 端口手动 adb connect:Play 版系统镜像会弹「允许 USB 调试吗」的系统对话框,而且它会盖在正在运行的安卓应用上,看起来像是程序出了问题。

关于作者

ApkStart 由 RoutineMiku 开发维护。

关于面板:公众号二维码与项目链接

from https://github.com/RoutineMiku/apkstart

CUDA 是什么

 

hermes-webui

 Hermes WebUI: The best way to use Hermes Agent from the web or from your phone!

 https://get-hermes.ai/setup

 

Hermes Web UI

Hermes Agent is a sophisticated autonomous agent that lives on your server, accessed via a terminal or messaging apps, that remembers what it learns and gets more capable the longer it runs.

Hermes WebUI is a lightweight, dark-themed web app interface in your browser for Hermes Agent. Full parity with the CLI experience - everything you can do from a terminal, you can do from this UI. No build step, no framework, no bundler. Just Python and vanilla JS.

Layout: three-panel. Left sidebar for sessions and navigation, center for chat, right for workspace file browsing. Model, profile, and workspace controls live in the composer footer — always visible while composing. A circular context ring shows token usage at a glance. All settings and session tools are in the Hermes Control Center (launcher at the sidebar bottom).

Setup Hermes so you can access it natively on every device:

image
Light mode with full profile support
Light mode with full profile support
Customize your settings, configure a password
Customize your settings, configure a password
Workspace file browser with inline preview
Workspace file browser with inline preview
Session projects, tags, and tool call cards
Session projects, tags, and tool call cards

This gives you nearly 1:1 parity with Hermes CLI from a convenient web UI which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI uses your existing Hermes agent and existing models, without requiring any additional setup.


Contents

image


Why Hermes

Most AI tools reset every session. They don't know who you are, what you worked on, or what conventions your project follows. You re-explain yourself every time.

Hermes retains context across sessions, runs scheduled jobs while you're offline, and gets smarter about your environment the longer it runs. It uses your existing Hermes agent setup, your existing models, and requires no additional configuration to start.

What makes it different from other agentic tools:

  • Persistent memory — user profile, agent notes, and a skills system that saves reusable procedures; Hermes learns your environment and does not have to relearn it
  • Self-hosted scheduling — cron jobs that fire while you're offline and deliver results to Telegram, Discord, Slack, Signal, email, and more
  • 10+ messaging platforms — the same agent available in the terminal is reachable from your phone
  • Self-improving skills — Hermes writes and saves its own skills automatically from experience; no marketplace to browse, no plugins to install
  • Provider-agnostic — OpenAI, Anthropic, Google, DeepSeek, OpenRouter, and more
  • Orchestrates other agents — can spawn Claude Code or Codex for heavy coding tasks and bring the results back into its own memory
  • Self-hosted — your conversations, your memory, your hardware

vs. the field (landscape is actively shifting — see docs/why-hermes.md for the full breakdown):


OpenClaw Claude Code Codex CLI OpenCode Hermes
Persistent memory (auto) Yes Partial† Partial Partial Yes
Scheduled jobs (self-hosted) Yes No‡ No No Yes
Messaging app access Yes (15+ platforms) Partial (Telegram/Discord preview) No No Yes (10+)
Web UI (self-hosted) Dashboard only No No Yes Yes
Self-improving skills Partial No No No Yes
Python / ML ecosystem No (Node.js) No No No Yes
Provider-agnostic Yes No (Claude only) Yes Yes Yes
Open source Yes (MIT) No Yes Yes Yes

† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall
‡ Claude Code has cloud-managed scheduling (Anthropic infrastructure) and session-scoped /loop; no self-hosted cron

The closest competitor is OpenClaw — both are always-on, self-hosted, open-source agents with memory, cron, and messaging. The key differences: Hermes writes and saves its own skills automatically as a core behavior (OpenClaw's skill system centers on a community marketplace); Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub has had security incidents involving malicious skills); and Hermes runs natively in the Python ecosystem. See docs/why-hermes.md for the full side-by-side.


Quick start

Run the repo bootstrap:

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

Or keep using the shell launcher:

./start.sh

For self-hosted VM or homelab installs, ctl.sh wraps the common daemon lifecycle commands without requiring fuser or pkill:

./ctl.sh start              # background daemon, PID at ~/.hermes/webui.pid
./ctl.sh status             # PID, uptime, bound host/port, log path, /health
./ctl.sh logs --lines 100   # tail ~/.hermes/webui.log
./ctl.sh restart
./ctl.sh stop

ctl.sh start runs the bootstrap in foreground/no-browser mode behind the daemon wrapper, writes logs to ~/.hermes/webui.log, and respects .env plus inline overrides such as HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start.

Stopping the server. Each launch method has its own stop path because only ctl.sh start writes a PID file (~/.hermes/webui.pid):

Launch method How to stop
python3 bootstrap.py Ctrl-C in the terminal (runs in the foreground)
./ctl.sh start ./ctl.sh stop (sends SIGTERM, waits, then SIGKILL)
Detached bootstrap.py (no --foreground) or ./start.sh Find the PID via lsof -i :8787 (or ss -tlnp) and kill it

./ctl.sh stop cannot stop a server launched by bootstrap.py or start.sh directly — it only manages processes it started itself.

How chat runs by default. WebUI runs the Hermes agent in-process, reading your HERMES_HOME config directly. It does not connect to an external Hermes/agent OpenAI-compatible API server to run chat. HERMES_API_URL is only read by the Tasks/cron health probe and does not route chat.

Two options if you run an external endpoint:

  1. Use its models as a chat provider (supported today): add it in Settings → Providers as a custom OpenAI-compatible provider with base_url = http://127.0.0.1:8642/v1 and your bearer token.
  2. Route chat through a Hermes Gateway API server (supported today via HERMES_WEBUI_CHAT_BACKEND=gateway): see docs/advanced-chat-setup.md. Full agent-loop delegation is not yet shipped; tracked in #1925.

Advanced: dynamic recall prefill & Gateway-backed chat

Two optional, self-hosted-deployment features — attaching dynamic session-recall prefill to browser turns (Joplin/Obsidian/Notion/llm-wiki routers), and routing browser chat through a running Hermes Gateway — are documented in docs/advanced-chat-setup.md. Most users need neither.

The bootstrap will:

  1. Detect Hermes Agent and, if missing, attempt the official installer (curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash).
  2. Find or create a Python environment with the WebUI dependencies.
  3. Start the web server and wait for /health.
  4. Open the browser unless you pass --no-browser.
  5. Drop you into a first-run onboarding wizard inside the WebUI.

Native Windows is not supported for this bootstrap yet. Use Linux, macOS, or WSL2. For Windows / WSL auto-start at login, see docs/wsl-autostart.md.

A community-maintained native Windows setup is documented at @markwang2658/hermes-windows-native-guide (companion setup repo: @markwang2658/hermes-windows-native). Notes from the community report in #1952:

  • Memory: community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
  • What works: chat, workspace browser, session management, all themes.
  • Known limitations: some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.
  • Native Windows setup: install Python 3.11+, then from the hermes-agent root in PowerShell: python -m venv venv → pip install -r requirements.txt → pwsh .\start.ps1 (it auto-discovers venv\Scripts\python.exe).
  • WSL2 relationship: not a prerequisite — a WSL2-built venv (venv/bin/python, ELF) isn't invokable by native Windows Python, so use the native setup above. WSL2 stays useful as a parallel install if you want the full bootstrap.py + Linux runtime.

If provider setup is still incomplete after install, the onboarding wizard will point you to finish it with hermes model instead of trying to replicate the full CLI setup in-browser. For a step-by-step walkthrough of the wizard, provider choices, local model server Base URLs, and safe re-runs, see docs/onboarding.md. If an AI assistant is helping with install, reinstall, bootstrap, provider setup, or first-run support, have it read docs/onboarding-agent-checklist.md before running commands or inspecting logs.


Features

Chat and agent

  • Streaming responses via SSE (tokens appear as they are generated)
  • Multi-provider model support -- any Hermes API provider (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI); dynamic model dropdown populated from configured keys
  • Send a message while one is processing -- it queues automatically
  • Edit any past user message inline and regenerate from that point
  • Retry the last assistant response with one click
  • Cancel a running task directly from the composer footer (Stop button next to Send)
  • Tool call cards inline -- each shows the tool name, args, and result snippet; expand/collapse all toggle for multi-tool turns
  • Subagent delegation cards -- child agent activity shown with distinct icon and indented border
  • Detached child results are delivered to the parent as internal wakeups. Their raw prompts and completion toasts do not appear as messages from the user; the parent can summarize the results in its own reply. Ordinary background-process wakeups remain visible. A completed parent reply does not, by itself, cancel or suppress outstanding children; a later result may still start a follow-up turn.
  • Mermaid diagram rendering inline (flowcharts, sequence diagrams, gantt charts)
  • Thinking/reasoning display -- collapsible gold-themed cards for Claude extended thinking and o3 reasoning blocks
  • Approval card for dangerous shell commands (allow once / session / always / deny)
  • SSE auto-reconnect on network blips (SSH tunnel resilience)
  • File attachments persist across page reloads and are stored outside the active workspace by default (~/.hermes/webui/attachments/<session_id>/, or HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/ when configured)
  • Message timestamps (HH:MM next to each message, full date on hover)
  • Code block copy button with "Copied!" feedback
  • Syntax highlighting via Prism.js (Python, JS, bash, JSON, SQL, and more)
  • Safe HTML rendering in AI responses (bold, italic, code converted to markdown)
  • Bare HTTP(S) URLs are auto-linked without absorbing adjacent CJK prose; Unicode IDN host separators and raw-CJK IRI paths remain linkable
  • Local file links: a file:/// URI in a reply renders through the media route (inline preview for images/audio/video, download otherwise). Windows drive-letter URIs (file:///C:/...) resolve to the drive path on a Windows server; on a POSIX server the leading separator is preserved so a /C:/... request stays absolute and can never alias a workspace-relative file. Only local authorities are served — a file://<host>/... UNC reference is rejected (never silently rewired to a local path), and the file must live under an allowed root (HERMES_HOME, /tmp, the active workspace, or MEDIA_ALLOWED_ROOTS)
  • rAF-throttled token streaming for smoother rendering during long responses
  • Context usage indicator in composer footer -- token count, cost, and fill bar (model-aware)

Sessions

  • Create, rename, duplicate, delete, search by title and message content
  • Session actions via ⋯ dropdown per session — pin, move to project, archive, duplicate, delete
  • Pin/star sessions to the top of the sidebar (gold indicator)
  • Pinned-conversation limits apply separately to each session's owning profile; root/default aliases share a limit. Unpin an empty session before switching its profile through chat or /goal.
  • Archive sessions (hide without deleting, toggle to show)
  • Session projects -- named groups with colors for organizing sessions; delegated subagent sessions have no project of their own and follow their nearest ancestor's project in the project filter and the Unassigned chip; forks and other child sessions keep their own project, so a fork moved to "No project" stays Unassigned
  • Delegated subagent sessions nest under their parent row. When that parent is filtered out of the current view (project, source tab, hidden), the subagent is hidden with it rather than shown as a stray top-level "Subagent Session"; a subagent without the cross-surface flag (for example in the all-profiles view) stays a top-level row when its parent is in the other (CLI/TUI) tab, was never imported, or is itself shown as a top-level subagent row, and a subagent that matches an active sidebar search is always listed
  • Project bindings -- right-click a project chip and pick Project settings… to pin a default workspace (or several workspaces, with one marked default) and a model. The chip's + (and New Chat while the project filter is active) then opens a session already in that workspace/model. The reasoning-effort binding stays in the API (POST /api/projects/bind) but is dormant: the dialog no longer offers the row, and nothing applies a stored value to a new session any more — the only mechanism would be the profile-wide reasoning-effort preference (the same agent.reasoning_effort setting the /reasoning command writes), so a row inside a per-project dialog read as per-project while silently moving the whole profile's effort; it comes back with per-session effort (#7881)
  • Session tags -- add #tag to titles for colored chips and click-to-filter Clicking a session tag chip filters the list without opening the conversation.
  • Grouped by Today / Yesterday / Earlier in the sidebar (collapsible date groups)
  • Download as Markdown transcript, full JSON export, or import from JSON
  • Create a public read-only share link for the active conversation from the Control Center; shared pages show a sanitized transcript snapshot without workspace, profile, or live controls
  • Sessions persist across page reloads and SSH tunnel reconnects
  • Model and reasoning-effort selections are restored per session; new-session defaults and legacy-session reasoning fallback use that session's profile configuration, including an authoritative HERMES_CONFIG_PATH for root; named profiles use their own config.yaml unless the override resolves inside that profile home
  • Browser tab title reflects the active session name
  • CLI session bridge -- CLI sessions from hermes-agent's SQLite store appear in the sidebar with a gold "cli" badge; click to import with full history and reply normally
  • Token/cost display -- input tokens, output tokens, estimated cost shown per conversation (toggle in Settings or /usage command)

Workspace file browser

  • Directory tree with expand/collapse (single-click toggles, double-click navigates)
  • Breadcrumb navigation with clickable path segments
  • Preview text, code, Markdown (rendered), and images inline
  • Chat links using workspace://path/to/file open files in the right-side preview pane
  • Edit, create, delete, and rename files; create folders
  • Binary file download (auto-detected from server)
  • File preview auto-closes on directory navigation (with unsaved-edit guard)
  • Dismissing the workspace panel is respected: resizing the viewport or showing the on-screen keyboard no longer force-reopens the panel after you close it (#6710)
  • Previews report their real load outcome -- a broken source is reported as a failure instead of a silent success -- and a response that never settles is released by a bounded wait so the panel still opens; the source keeps loading and a late failure is surfaced in the status line (#6710)
  • Git detection -- branch name and dirty file count badge in workspace header
  • Right panel is drag-resizable
  • Syntax highlighted code preview (Prism.js)

Voice input

  • Microphone button in the composer (Web Speech API)
  • Tap to record, tap again or send to stop
  • Live interim transcription appears in the textarea
  • Auto-stops after ~2s of silence
  • Appends to existing textarea content (doesn't replace)
  • Hidden when browser doesn't support Web Speech API (Chrome, Edge, Safari)
  • A saved fallback from browser speech recognition to server-side recording expires after 24 hours. Preferences stored by older versions get a 24-hour window on first use after upgrading. On reload after expiry, the mic returns to normal capture selection: server transcription takes priority when available; otherwise it uses browser speech recognition.

Profiles

  • Profile chip in the composer footer -- dropdown showing all profiles with gateway status and model info
  • Gateway status dots (green = running), model info, skill count per profile
  • Profiles management panel -- create, switch, and delete profiles from the sidebar
  • Clone config from active profile on create
  • Optional custom endpoint fields on create -- Base URL and API key written into the profile's config.yaml at creation time, so Ollama, LMStudio, and other local endpoints can be configured without editing files manually
  • Seamless switching -- no server restart; reloads config, skills, memory, cron, models
  • Per-session profile tracking (records which profile was active at creation)

Authentication and security

  • Optional password auth -- off by default, zero friction for localhost
  • Enable via HERMES_WEBUI_PASSWORD env var or Settings panel
  • Installed PWAs work best with WebUI's own password. Reverse proxies are supported, but proxy basic auth can block the service-worker update fetches an installed app needs and leave it on a blank screen after an update; see docs/troubleshooting.md for recovery steps.
  • Optional passkeys/WebAuthn -- register from Settings -> System after signing in with a password; the login page only shows passkey sign-in after at least one passkey exists
  • After registering at least one passkey, Settings -> System can remove the password and keep passkey-only sign-in enabled. Password auth remains the bootstrap/recovery path until you choose to go passwordless; passkeys are same-origin and stored locally in the WebUI state directory
  • Optional native OIDC login for WebUI sessions -- configure webui_oidc.issuer, client_id, allow_claim, and allow_values in config.yaml, or set the matching HERMES_WEBUI_OIDC_* environment variables. OIDC stays disabled until all four are present, and startup prints a warning if the config is partial.
  • Native OIDC sends the client secret in the token-request form body (client_secret_post) by default. When the provider's discovery document only advertises client_secret_basic in token_endpoint_auth_methods_supported (common with strict OIDC stacks such as zitadel/oidc), the secret automatically moves to the HTTP Basic header instead. Set webui_oidc.token_auth_method (or HERMES_WEBUI_OIDC_TOKEN_AUTH_METHOD) to client_secret_basic or client_secret_post to pin a method explicitly.
  • Native OIDC stores the PKCE/state nonce flow in process memory. That works for the shipped single-process server, and it also works behind a load balancer when callbacks stay sticky to the same WebUI instance. Multi-instance deployments need session affinity, or the callback can land on a different process and fail state validation.
  • Signed HMAC HTTP-only cookie with 24h TTL
  • Minimal dark-themed login page at /login
  • Security headers on all responses (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
  • 20MB POST body size limit
  • CDN resources pinned with SRI integrity hashes

Themes

  • Appearance is split into two axes: Theme (system, dark, light) and Skin (default, ares, mono, slate, poseidon, sisyphus, charizard, sienna, catppuccin, nous, geist-contrast / Geist Contrast)
  • Switch via Settings -> Appearance (instant live preview) or /theme <theme-or-skin>
  • Persists across reloads (server-side in settings.json + localStorage for flicker-free loading)
  • Skins use data-skin plus CSS variables; dark mode resolves through the .dark class, not a data-theme custom-theme axis — see THEMES.md

Settings and configuration

  • Hermes Control Center (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password)
  • Send key: Enter (default) or Ctrl/Cmd+Enter
  • Send-key on touch devices: plain Enter inserts a newline on phones (iPhone/iPod, Android phones) and on tablets / iPadOS / touch-capable Macs that only expose a coarse pointer (no attached hardware keyboard), matching the software keyboard's return key. Devices that report a fine pointer (for example, a tablet with a hardware keyboard) keep the configured physical-keyboard send-key behavior. The configured shortcut and the Send button remain available for sending.
  • Show/hide CLI sessions toggle (enabled by default)
  • Token usage display toggle (off by default, also via /usage command)
  • Task list in chat toggle (off by default) -- a collapsible task strip pinned at the top of the chat area, summarising the current session's todos. While it is on, the sidebar Todos panel is hidden and the workspace-panel Todos toggle is disabled with an explanation, so the same list is never shown twice; switch it back off in Settings -> Appearance to restore the sidebar panel and re-enable the workspace toggle.
  • Control Center always opens on the Conversation tab; resets on close
  • Unsaved changes guard -- discard/save prompt when closing with unpersisted changes
  • Cron completion alerts -- toast notifications and unread badges scoped to the active profile on the Tasks tab and session sidebar
  • Background agent error alerts -- banner when a non-active session encounters an error
  • Approval and clarification browser alerts notify once per pending owner when its session is not actively viewed. Local approval dismissal hides attention without resolving the prompt; resolution, replacement, and cancellation retire that owner's alert state. Denied or failed notification delivery can retry while the prompt remains pending.

Slash commands

  • Type / in the composer for autocomplete dropdown
  • Plain skills match case-insensitive keywords in their name or description; built-in, agent/plugin, and bundle commands keep prefix matching and take precedence over a same-slug skill
  • Built-in: /help, /clear, /compress [focus topic], /compact (alias), /model <name>, /workspace <name>, /new, /usage, /theme
  • Arrow keys navigate, Tab/Enter select, Escape closes
  • Unrecognized commands pass through to the agent

Model aliases in /model

/model <alias> accepts any alias configured for the profile, in either of Hermes's two formats:

model_aliases:                     # canonical
  sol:
    model: gpt-5.6-sol
    provider: openai-codex

model:
  provider: openrouter
  aliases:                         # legacy
    sol: openai-codex/gpt-5.6-sol  # provider-qualified
    fast: gpt-4                    # unqualified

Alias resolution follows the format of the alias:

  • A canonical model_aliases entry and a provider-qualified legacy target name their own route. The target is authoritative, so /model sol selects that provider even when a same-named model exists on another provider. A canonical entry also takes precedence over a legacy entry with the same name.
  • An unqualified legacy target names only a model, so it keeps the ordinary lookup: the active provider first, then the normal fuzzy match. This is the behavior /model had before, and it is unchanged.

Aliases that carry their own endpoint or credentials are resolved server-side; the browser only receives the model, the provider id, and an opaque route id, never a base URL or key. On the in-process backend, an alias with its own base_url follows Hermes's direct-alias credential rules: its declared api_key/key_env wins; otherwise only a credential resolved for that endpoint's own host is sent (for example an OpenRouter key to openrouter.ai), never the provider label's key to an unrelated host. The alias's provider still selects its wire protocol.

Gateway and runner chat support provider-only aliases by sending the resolved target model and provider, not the alias name: their runtime does not share WebUI's alias registry. Aliases that explicitly declare base_url, api_key, or key_env need the in-process backend. External chat starts, wakeups, Gateway regeneration, and Gateway goal kickoffs reject them with HTTP 400 and reason: model_alias_requires_in_process_backend before dispatch; a new Gateway goal is not set. Runner regeneration remains unsupported (HTTP 409), regardless of alias selection. Ambient credentials resolved for a provider-only alias do not count as alias overrides. The session retains its target model and profile-bound opaque route id, including Gateway success/error writeback, so a later backend switch can still resolve the original alias.

A session stores that opaque route id, not the endpoint, so an alias that is later deleted or renamed leaves the session pointing at a route nothing owns. That send fails closed — on every backend, the in-process worker, the gateway and the runner alike — with a controlled "model alias unavailable" error instead of quietly falling back to another provider; pick the model again to store a live route.

With HERMES_WEBUI_RUNTIME_ADAPTER=runner-local, /goal <text> returns HTTP 501 (status: unsupported) without changing an existing goal or starting a run. The runner contract does not yet provide atomic goal replacement and kickoff; WebUI never substitutes local goal execution. /goal status, pause, resume, and clear delegate to the runner when supported. Legacy-direct and legacy-journal goal kickoff behavior is unchanged for supported routes. Normal runner chat supports provider-only model aliases.

/goal <text> reads Hermes Agent's inline completion-contract lines (outcome:, verification:, constraints:, boundaries:, stop when:) into the goal's contract and keeps the first plain line(s) as the goal. /goal gate … is refused with HTTP 400 (error: unsupported_gate) on every backend, without changing the goal or starting a run: gates rerun shell commands after every turn and WebUI has no rule yet for who may add them. Use /goal -- <text> for a goal that starts with a control word such as gate or pause.

Server-initiated turns retain the pre-session stale-Agent-runtime barrier. It runs before loading the session; named-profile alias and Gateway routing happen only after admission. A stale default local runtime can therefore reject a wakeup before the session's named-profile Gateway ownership is known.

Panels

  • Chat -- session list, search, pin, archive, projects, new conversation
  • Tasks -- view, create, edit, run, pause/resume, delete cron jobs; run history; completion alerts; a Scripts subtab for a read-only browse of the profile's ~/.hermes/scripts/ directory (see docs/scripts-panel.md)
  • Skills -- list all skills by category, search, preview, create/edit/delete; linked files viewer
  • Memory -- view and edit MEMORY.md and USER.md inline
  • Profiles -- create, switch, delete agent profiles; clone config
  • Todos -- live task list from the current session; hidden while the in-chat task list toggle is on, which also disables the workspace-panel Todos tab
  • Insights -- token, cost, and skill-usage analytics; period presets (7/30/90/365 days) plus a Custom range with start/end date pickers
  • Artifacts -- files changed in the session and Skills Used, with a separate skill count and per-skill use counts
  • Spaces -- add, rename, remove workspaces; quick-switch from topbar

Mobile responsive

  • Hamburger sidebar -- slide-in overlay on mobile (<640px)
  • Sidebar top tabs stay available on mobile; no fixed bottom nav stealing chat height
  • Files slide-over panel from right edge
  • Touch targets minimum 44px on all interactive elements
  • Full-height chat/composer on phones without bottom-nav spacing
  • Desktop layout completely unchanged

Configuration & access

start.sh auto-detects almost everything; the subsections below cover the knobs for when it can't, and how to reach the UI remotely.

What start.sh discovers automatically

Thing How it finds it
Hermes agent dir HERMES_WEBUI_AGENT_DIR, then valid authoritative run_agent.py checkouts, the hermes launcher, the selected Python, valid fallback checkouts, and finally marker-only roots
Python executable HERMES_WEBUI_PYTHON, Agent venv, interpreter that proved the Agent root, .venv in this repo, then system Python
State directory HERMES_WEBUI_STATE_DIR env, then $HERMES_HOME/webui (Windows default %LOCALAPPDATA%\hermes\webui, POSIX default ~/.hermes/webui)
Default workspace HERMES_WEBUI_DEFAULT_WORKSPACE env, then ~/workspace, then state dir
Port HERMES_WEBUI_PORT env or first argument, default 8787

Before it installs the agent or writes any state, the bootstrap binds the resolved host and port as a preflight. If another service already holds the port, it stops right there, names the address it could not bind, and prints a free alternative to pass to ./start.sh <port> or set as HERMES_WEBUI_PORT in .env. The running service and your existing configuration are left untouched. When the listener on that port is a healthy WebUI -- the instance you already started -- bootstrap reports it ready and leaves it alone, browser included; only a foreign service gets the conflict message.

If discovery finds everything, nothing else is required.


Overrides (only needed if auto-detection misses)

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
export HERMES_WEBUI_AUTO_INSTALL=1  # enable auto-install of agent deps (disabled by default)
./start.sh

Auto-install requires the selected Agent to match HERMES_WEBUI_AGENT_DIR or the Agent under HERMES_HOME, and still checks ownership and permissions.

Or inline:

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

Full list of environment variables:

Variable Default Description
HERMES_WEBUI_AGENT_DIR auto-discovered Path to the Hermes Agent source or installed module root
HERMES_WEBUI_PYTHON auto-discovered Python executable
HERMES_WEBUI_HOST 127.0.0.1 Bind address (0.0.0.0 for all IPv4, :: for all IPv6, ::1 for IPv6 loopback)
HERMES_WEBUI_PORT 8787 Port
HERMES_WEBUI_STATE_DIR $HERMES_HOME/webui (Windows default %LOCALAPPDATA%\hermes\webui, POSIX default ~/.hermes/webui) Where sessions and state are stored. Note (upgrade): the default now follows HERMES_HOME — if you previously relocated HERMES_HOME to a non-default base without setting HERMES_WEBUI_STATE_DIR, your WebUI state now resolves to $HERMES_HOME/webui instead of the old platform-default ~/.hermes/webui. To keep using the old location, set HERMES_WEBUI_STATE_DIR to it (or move the directory). Installs with HERMES_HOME unset or at the default base are unaffected.
HERMES_WEBUI_SETTINGS_FILE <state dir>/settings.json Optional path for this instance's WebUI settings file (sessions, workspaces and projects stay in the state directory). Read once at startup, so restart after changing it
HERMES_WEBUI_DEFAULT_WORKSPACE ~/workspace Default workspace
HERMES_WEBUI_DEFAULT_MODEL (provider default) Optional model override; leave unset to use the active Hermes provider default
HERMES_WEBUI_PASSWORD (unset) Set to enable password authentication
HERMES_WEBUI_CSP_CONNECT_EXTRA (unset) Optional space-separated http(s):// or ws(s):// origins to append to the enforced and report-only CSP connect-src directives for trusted reverse-proxy, tunnel, or extension sidecar deployments
HERMES_WEBUI_CSP_IMG_EXTRA (unset) Optional space-separated http(s):// image origins (wildcard subdomain and port allowed), or the bare https: / http: scheme, added to the CSP img-src. Remote images are blocked by default so an assistant reply cannot make the browser fetch an arbitrary URL; blocked images render as an inert "Open image" link. Use this to show images from a trusted CDN inline, e.g. an image-generation provider
HERMES_WEBUI_SSE_CHUNKED (unset) Set truthy (1/true/yes/on) to send SSE with Transfer-Encoding: chunked. Needed behind buffering reverse proxies (e.g. jupyter-server-proxy) that otherwise buffer the whole stream; harmless but unnecessary for directly-served deployments
HERMES_WEBUI_EXTENSION_DIR (unset) Optional local directory served at /extensions/; must point to an existing directory before extension injection is enabled
HERMES_WEBUI_EXTENSION_MANIFEST (unset) Optional relative JSON manifest inside HERMES_WEBUI_EXTENSION_DIR listing bundled scripts/styles to inject; see WebUI Extensions
HERMES_WEBUI_EXTENSION_SCRIPT_URLS (unset) Optional comma-separated same-origin script URLs to inject; appended after manifest scripts; see WebUI Extensions
HERMES_WEBUI_EXTENSION_STYLESHEET_URLS (unset) Optional comma-separated same-origin stylesheet URLs to inject; appended after manifest stylesheets; see WebUI Extensions
HERMES_HOME Windows: %LOCALAPPDATA%\hermes; POSIX: ~/.hermes Base directory for Hermes state (affects all paths)
HERMES_CONFIG_PATH $HERMES_HOME/config.yaml Path to Hermes config file
HERMES_WEBUI_SERVER_CWD (unset) Working directory for the server process. Defaults to the agent dir; point it at a writable workspace when the agent dir is read-only so fallback relative writes land somewhere writable
HERMES_WEBUI_VISIBLE_SESSION_LIMIT 20 Size of the sidebar's interactive recency window (how many recent non-cron/webhook sessions are listed). Also bounds how many delegated subagent children can nest at once, since a child only renders when its row wins a slot in the window — raise it for wide fan-outs. Non-integer or non-positive values fall back to the default. Values above 200 are clamped. Resolved before profile init, so a profile .env cannot override it
HERMES_WEBUI_AGENT_CACHE_MAX 25 Max live agent instances kept warm in the in-memory LRU. Each pins a full conversation transcript, so this is the dominant lever on resident memory — lower it on installs with many long sessions to cap RAM (at the cost of more cold reloads)
HERMES_WEBUI_SESSIONS_MAX 100 Legacy operator override for the max compact Session objects held in the in-memory LRU. Prefer the webui.sessions_cache_max key in config.yaml (which takes precedence); this env var remains a fallback. Bounds resident memory so long-running installs cannot accumulate every session ever touched and eventually crash (#4765/#2233/#4633). Eviction only ever drops clean, persisted, non-active sessions; an evicted session lazily reloads from its JSON sidecar on next access
HERMES_WEBUI_RUN_JOURNAL_SWEEP (unset) Set to 0/false/off to disable the run-journal retention sweep entirely (#7613)
HERMES_WEBUI_RUN_JOURNAL_RETENTION_TTL_DAYS 14 Runs whose journal file is older than N days are archived (compressed into _run_journal_archive/, not deleted). 0 disables the age cap. Also settable via run_journal_retention_ttl_days in settings.json (the env var wins)
HERMES_WEBUI_RUN_JOURNAL_RETENTION_MAX_RUNS_PER_SESSION 40 Keep at most N newest runs live per session; older runs are archived. 0 disables the count cap (run_journal_retention_max_runs_per_session in settings.json)
HERMES_WEBUI_RUN_JOURNAL_RETENTION_MAX_BYTES_PER_SESSION 268435456 (256 MiB) Per-session budget for LIVE run-journal bytes; sessions over budget archive their oldest runs. 0 disables the size cap (run_journal_retention_max_bytes_per_session in settings.json)
HERMES_WEBUI_RUN_JOURNAL_ARCHIVE_TTL_DAYS 0 (keep forever) The only destructive knob: archives older than N days are deleted, except an archive a session still needs to recover an interrupted answer, which is kept until the session no longer references it or is deleted. 0 (default) never deletes archives — a stock install keeps every archived run forever (run_journal_archive_ttl_days in settings.json)

Run-journal retention (#7613)

The run journal stores one {run_id}.jsonl per run under sessions/_run_journal/<session_id>/; nothing removed them, so a long-lived session's journal grew without bound. An hourly sweep (piggybacked on the existing maintenance tick, never on a request path) now archives runs past the caps above rather than deleting them:

  • eligible runs are compressed (gzip) into sessions/_run_journal_archive/<session_id>/<run_id>.jsonl.gz — measured at 5–18% of the original size on real journals;
  • the compressed copy is verified to decompress to the exact original bytes before the live file is dropped;
  • runs that have not provably settled (no complete terminal row — including a journal truncated mid-write) are never touched;
  • a run the session still needs to recover an interrupted answer (its active stream, or the run an interrupted-turn marker names) stays live, so a release that predates the archive format can still recover it after a rollback;
  • every read path (run summaries, event reads, session replay, run lookup) transparently falls back to the archive, so a wrong classification costs one compressed copy, not the run;
  • deleting a session deletes its archives too.

Where dir_fd primitives are unavailable (Windows), the sweep disables itself rather than fall back to path-based moves a directory swap could redirect.

Extension deployments can inspect sanitized, authenticated diagnostics at GET /api/extensions/status; see WebUI Extensions.


Nix flake and NixOS module

Hermes WebUI has a Nix flake package and a NixOS service module so you can run it declaratively.

Install the latest package with:

nix shell github:nesquena/hermes-webui#default

Use this flake input in your system configuration:

inputs.hermes-webui.url = "github:nesquena/hermes-webui";

Then add the module and configure it in nixosModules:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-agent.url = "github:NousResearch/hermes-agent";
    hermes-webui.url = "github:nesquena/hermes-webui";
  };

  outputs = { self, nixpkgs, hermes-agent, hermes-webui, ... }: {
    nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
      modules = [
        hermes-agent.nixosModules.default
        hermes-webui.nixosModules.default
        ({ pkgs, ... }: {
          services.hermes-agent.enable = true;
          services.hermes-webui = {
            enable = true;
            host = "127.0.0.1";
            port = 8787;
            stateDir = "/var/lib/hermes-webui";
            user = "hermes";
            group = "hermes";
            hermesHome = "/var/lib/hermes/.hermes";
            agent.package = hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.default;
            environmentFiles = [ "/run/secrets/hermes-webui.env" ];
          };
        })
      ];
    };
  };
}

The module defaults to 127.0.0.1. Set host = "0.0.0.0" and openFirewall = true only when you want direct network access, and pair that with auth, for example HERMES_WEBUI_PASSWORD via environmentFiles.

The published Hermes Agent package exposes passthru.hermesVenv, so the module derives HERMES_WEBUI_PYTHON from its interpreter. Bootstrap then locates the installed run_agent.py through that interpreter without importing Agent code and exports its parent as HERMES_WEBUI_AGENT_DIR. Packages may expose passthru.hermesAgentDir as a direct path instead. Use agent.dir and agent.python as explicit overrides for custom package layouts.

When WebUI reads shared Hermes Agent state, run the service as a user that can already read that state. For a co-located Hermes Agent service, set user and group to the agent service account; the module only creates the default hermes-webui account and never changes ownership of an existing hermesHome.

The module maps directly onto existing WebUI environment variables, including: HERMES_WEBUI_HOST, HERMES_WEBUI_PORT, HERMES_WEBUI_STATE_DIR, HERMES_HOME, HERMES_WEBUI_AGENT_DIR, and HERMES_WEBUI_PYTHON.

Set environmentFiles for secrets like API keys. Protected WebUI runtime keys from the module are rejected there, so keep host, port, state, and agent wiring in the module options. Keep reverse proxy and TLS configuration in your surrounding deployment module because those details are deployment-specific.

Remote access (SSH tunnel, Tailscale, phone)

The server binds to 127.0.0.1 by default. To reach it from another machine, use an SSH tunnel (ssh -N -L 8787:127.0.0.1:8787 user@host, which start.sh prints for you over SSH) or, on a single-operator or access-restricted tailnet, use the preferred Tailscale Serve flow, which keeps WebUI on loopback behind tailnet-only HTTPS. Direct access to http://<server-tailscale-ip>:8787 with HERMES_WEBUI_HOST=0.0.0.0 and HERMES_WEBUI_PASSWORD is a fallback when Serve is unavailable. Full setup and the community ARM64-Android field report: docs/remote-access.md.

Manual launch (without start.sh)

If you prefer to launch the server directly (for example from your own systemd unit):

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent   # optional, see below
HERMES_WEBUI_PORT=8787 python3 /path/to/hermes-webui/server.py

Before importing anything else, server.py activates the Hermes Agent's dependency environment. It uses HERMES_WEBUI_AGENT_DIR when set, otherwise the same discovery start.sh uses ($HERMES_HOME/hermes-agent, ~/.hermes/hermes-agent, the hermes launcher, …), so the export is only needed for an Agent installed somewhere else. A Hermes-managed Agent (v0.21.6 or newer, installed by the official installer or hermes update) then restarts the server in its own Python with its own dependencies, so the interpreter you launch with does not need the Agent's packages. An older Agent that keeps its dependencies in venv/ or .venv/ is not restarted: run server.py with that venv's Python instead (/path/to/hermes-agent/venv/bin/python). System Python on its own lacks openai, httpx and other required packages.

Health check:

curl http://127.0.0.1:8787/health

Docker

Pre-built images (amd64 + arm64) are published to GHCR on every release.

For a comprehensive setup guide covering all 3 compose files, common failure modes, and bind-mount migration, see docs/docker.md. The README covers the 5-minute happy path.

5-minute quickstart (single container)

The simplest setup: one WebUI container that runs the agent in-process.

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# Edit .env if your host UID isn't 1000 (e.g. macOS where UIDs start at 501)
docker compose up -d
# Open http://localhost:8787

Run Compose as the user who owns your Hermes home. sudo docker compose up -d can make ${HOME} expand to the root user's home, so Docker mounts the wrong .hermes directory instead of your real ~/.hermes and the WebUI starts with config.yaml (not found, using defaults). Prefer adding your user to the Docker group and running docker compose up -d; if you must use sudo, set absolute paths first, for example HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d, then verify with docker compose config.

The container auto-detects your UID/GID from the mounted ~/.hermes volume so files written by the agent stay readable by you on the host.

To enable password protection (required if you expose the port outside 127.0.0.1):

echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong" >> .env
docker compose up -d --force-recreate

Manual docker run (no compose)

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

Build locally

docker build -t hermes-webui .
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  hermes-webui

Multi-container setups

If you want the agent and WebUI in separate containers (for isolation, or because you're already running an agent gateway elsewhere):

# Agent + WebUI
docker compose -f docker-compose.two-container.yml up -d

# Agent + Dashboard + WebUI
docker compose -f docker-compose.three-container.yml up -d

Both compose files use named Docker volumes by default, which solves the UID/GID problem by construction. If you need bind mounts to share an existing host directory, see docs/docker.md for the full migration recipe.

Known limitation (#681): in the two-container setup, tools triggered from the WebUI run in the WebUI container, not the agent container. If you need git/node/etc. on the WebUI's filesystem, either use the single-container setup, extend the WebUI Dockerfile, or use the community all-in-one image.

Source boundary note (#2453): the multi-container setup mounts hermes-agent-src read-only into the WebUI by default. This prevents WebUI-side source rewrites but is still an implementation-coupling bridge, not a stable Agent API boundary. See docs/rfcs/agent-source-boundary.md for the current source/API decoupling inventory.

Common failure modes

Symptom Likely cause Fix
PermissionError at startup UID mismatch on bind mount Set UID=$(id -u) in .env
.env: permission denied (#1389) fix_credential_permissions() enforced 0600 Set HERMES_SKIP_CHMOD=1 in .env
Workspace appears empty UID mismatch on /workspace mount Set UID=$(id -u) in .env
git: command not found in chat Two-container architectural limit (#681) Use single-container or extend Dockerfile
WebUI can't find agent source hermes-agent-src volume misconfigured Use the named volumes from compose files as-is
Podman shared .hermes fails Podman 3.4 keep-id limitation Use Podman 4+ or single-container
Host API at localhost fails from WebUI Container localhost means the container, not your host (#3012) Use http://host.docker.internal:<port> on Docker Desktop, or http://host.containers.internal:<port> on Podman
WebUI can't see ~/.hermes after sudo docker compose ${HOME} expanded to the root user's home (#3006) Run Compose as your user, or pass absolute HERMES_HOME/HERMES_WORKSPACE with sudo -E

For the deep dive on each of these, see docs/docker.md.

Note: By default, Docker Compose binds to 127.0.0.1 (localhost only). To expose on a network, change the port to "8787:8787" in docker-compose.yml and set HERMES_WEBUI_PASSWORD to enable authentication.


Running tests

Tests discover the repo and the Hermes agent dynamically -- no hardcoded paths. Use the repo test runner so local runs do not accidentally use an unsupported system Python. It creates/uses .venv with Python 3.11, 3.12, or 3.13 and installs the dev test dependencies from requirements-dev.txt when missing.

cd hermes-webui
./scripts/test.sh

Pass normal pytest arguments after the script for focused runs:

./scripts/test.sh tests/test_regressions.py -v

Or seed the repo .venv from an explicit supported base interpreter:

HERMES_WEBUI_TEST_PYTHON=/path/to/python3.12 ./scripts/test.sh tests/ -v

The override selects the Python used to create or rebuild .venv; dependencies are still installed into the repo-local virtual environment, not into the system/Homebrew interpreter.

Tests run against an isolated server with a separate state directory. Production data and real cron jobs are never touched. Current snapshot: ~11,500 tests collected across ~1,150 test files, run in CI on Python 3.11, 3.12, and 3.13 (3 parallel shards each).


Architecture

No build step, no framework, no bundler — a Python standard-library HTTP server and vanilla JS. The backend lives in api/, the frontend in static/.

Backend (api/)

server.py         HTTP routing shell + auth middleware
api/
  auth.py         Optional password authentication, signed cookies, passkeys
  config.py       Discovery, globals, model detection, reloadable config
  helpers.py      HTTP helpers, security headers
  models.py       Session model + CRUD + CLI/state.db bridge
  onboarding.py   First-run onboarding wizard, OAuth provider support
  profiles.py     Profile state management, hermes_cli wrapper
  routes.py       All GET + POST route handlers (if/elif dispatch, no decorators)
  state_sync.py   /insights sync — message_count to state.db
  streaming.py    SSE engine, run_agent, cancellation, compression
  updates.py      Self-update check and release notes
  upload.py       Multipart parser, file upload handler
  workspace.py    File ops, workspace helpers, git detection

Frontend (static/)

index.html        HTML template
style.css         All CSS incl. mobile responsive, themes + skins
ui.js             DOM helpers, renderMd, tool cards, context indicator
workspace.js      File preview, file ops, git badge, central api() fetch wrapper
sessions.js       Session CRUD, collapsible groups, search, reload recovery
messages.js       send(), SSE handlers, live streaming, session recovery
panels.js         Cron, skills, memory, profiles, settings (Control Center)
commands.js       Slash command autocomplete
boot.js           Mobile nav, voice input, theme/skin boot, bfcache handler

Tests + packaging

tests/            Pytest suite (~11,500 tests; isolated server/state fixtures)
pyproject.toml    Standard build metadata plus the Ruff lint gate; checkout launch surface still centers on bootstrap.py / start.sh / ctl.sh
Dockerfile        python:3.12-slim container image
docker-compose.yml  Compose with named volume and optional auth
.github/workflows/  CI: ruff + sharded pytest, browser smoke, Docker smoke,
                    multi-arch Docker build + GitHub Release on tag

State lives outside the repo at ~/.hermes/webui/ by default (sessions, workspaces, settings, projects, last_workspace). Override with HERMES_WEBUI_STATE_DIR. Full design notes and the endpoint catalog are in ARCHITECTURE.md.


Compatibility

The version shown in the WebUI runtime status is the WebUI version only (build/image/tag currently running). It is not a full compatibility map.

The WebUI is still coupled to Hermes Agent internals for runtime execution, provider/model access, and state/schema usage until the stable agent boundary work in #1925 and #2491 land. In practice, the WebUI imports Agent modules directly (api/config.py, api/providers.py, api/streaming.py) and reads Agent state layout directly, so version skew can cause import or behavior drift.

Compatibility policy

  • WebUI release branches are tested against the matching Hermes Agent release available at that WebUI release time.
  • Upgrade both together: upgrade or pin WebUI and hermes-agent together (same release train/version/date), especially before enabling production traffic.
  • Running pinned older/newer combinations is untested and unsupported until the stable API boundary work in #1925 / #2491 is in place.
  • Record the full hermes-agent + hermes-webui versions in issue reports when upgrade mismatches are suspected.

Docker users: pin both image tags (or corresponding pinned source revisions) rather than using latest on one side and a fixed tag on the other. When upgrading the multi-container setup, follow the agent-image upgrade procedure in docs/docker.md (which requires dropping the hermes-agent-src volume before recreating). The current source-boundary status is tracked in docs/rfcs/agent-source-boundary.md.


Docs

Start here

  • docs/why-hermes.md — why Hermes, the mental model, and a detailed comparison to Claude Code / Codex / OpenCode / Cursor
  • docs/onboarding.md — first-run wizard, provider setup, local model server Base URLs, and safe re-runs
  • docs/troubleshooting.md — diagnostic flows for common failures (e.g. "AIAgent not available")

Using & customizing

  • THEMES.md — theme + skin system, custom theme guide
  • docs/workspace-git.md — the workspace Git controls
  • docs/kanban.md — the Kanban board's status flow: who may set which column, how tasks enter and leave Scheduled, and the parent re-gating on Scheduled/Blocked → Ready
  • docs/scripts-panel.md — the Tasks panel's Scripts subtab: where the profile's ~/.hermes/scripts/ directory comes from, the read-only endpoints, and the containment rules
  • docs/EXTENSIONS.md — administrator-controlled WebUI extension injection

Deploying & operating

Contributing & design

  • CONTRIBUTING.md — contribution style, PR expectations, and local verification
  • ARCHITECTURE.md — system design, all API endpoints, implementation notes
  • TESTING.md — manual browser test plan and automated coverage reference
  • DESIGN.md — design tokens and the calm-console direction
  • docs/UIUX-GUIDE.md — UI/UX principles sourced from the design docs and visual inventories
  • docs/sse-streams.md — cross-client SSE endpoint reference: session streaming, gateway SSE probe scope, heartbeats, and proxy behavior
  • docs/architecture/transcript-auto-follow-scroll.md — transcript auto-follow contract: pinned/unpinned state model, input-tail re-pinning, reader-resume rules, and the transcript's overscroll suppression rationale
  • docs/CONTRACTS.md — project contract/RFC/design index for contributors and agents
  • docs/rfcs/README.md — RFC index for larger architecture and durability proposals

Release history & plan


Contributors

Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute.

Over 468 contributors have shipped code that landed in a release tag. The full, continuously-updated credit roll — including everyone with one or two PRs and the special-thanks roll for design and architectural work — lives in CONTRIBUTORS.md. A snapshot of the most prolific contributors:

Top contributors (by PR count, including absorbed/batch-released work)

# Contributor PRs First → latest release
1 @rodboev 399 v0.51.223 → v0.52.492
2 @franksong2702 338 v0.49.3 → v0.52.492
3 @Michaelyklam 157 v0.50.240 → v0.51.198
4 @ai-ag2026 155 v0.50.279 → v0.52.458
5 @webtecnica 91 v0.51.619 → v0.52.492
6 @bergeouss 80 v0.48.0 → v0.51.703
7 @AJV20 57 v0.51.93 → v0.51.346
8 @happy5318 56 v0.50.238 → v0.52.492
9 @starship-s 55 v0.50.123 → v0.52.492
10 @dso2ng 43 v0.50.227 → v0.51.578

See CONTRIBUTORS.md for the full ranked list of all 468 contributors — the 3+ PR tables, the 1–2 PR roll, and the special-thanks notes for design and architectural contributions.

Notable contributions

@franksong2702 — Most prolific external contributor (180 PRs, v0.49.3 → v0.51.384) Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual /compress async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine.

@Michaelyklam — Most prolific contributor of recent releases (118 PRs, v0.50.240 → v0.51.198) Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), /goal command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894).

@rodboev — Windows / cross-platform correctness + test reliability (83 PRs, v0.51.223 → v0.51.384) A broad, sustained sweep with a strong focus on making the project work outside Linux: the ctl.sh Windows process-tree-kill fix (#3670), the local Windows full-suite signal/orphan-process work, slash-command autocomplete polish, and a long tail of frontend and infrastructure fixes shipped across dozens of release batches.

@bergeouss — Provider management UI + Docker hardening (70 PRs, v0.48.0 → v0.51.385) Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile .env secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644).

@ai-ag2026 — Session recovery + audit infrastructure (75 PRs, v0.50.279 → v0.51.367) Autonomous-AI contributor (Hermes Agent-driven) focused on durability: state.db-backed sidecar reconciliation (#2041), orphan .json.bak recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in /health (#2039), crash-safe turn-journal RFC at docs/rfcs/turn-journal.md (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), Content-Security-Policy-Report-Only header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014).

@dso2ng — Session lineage + diagnostics (30 PRs, v0.50.227 → v0.51.327) /api/session/lineage-report/<sid> endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), session_source="fork" continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading.

@jasonjcwu — Composer + transcript polish (16 PRs, v0.50.227 → v0.51.132) Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes.

@Jordan-SkyLF — Live streaming + UX polish (12 PRs, v0.50.18 → v0.51.66) Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210).

@aronprins — v0.50.0 UI overhaul (PR #242, plus 9 follow-ups) The biggest single contribution to the project: a complete UI redesign that moved model/profile/workspace controls into the composer footer, replaced the gear-icon settings panel with the Hermes Control Center (tabbed modal), removed the activity bar in favor of inline composer status, redesigned the session list with a ⋯ action dropdown, and added the workspace panel state machine. Plus chat transcript redesign (#587), sidebar declutter (#584), three-column layout refactor (#899), light/dark theme + accent skins (#627), and shared confirm()/prompt() dialog replacement (PR #251 extracted from #242).

@iRonin — Security hardening sprint (PRs #196–#204) Six consecutive, focused security PRs: session memory leak fix (expired token pruning), CSP + Permissions-Policy headers, 30-second slow-client connection timeout, optional HTTPS/TLS support via environment variables, upstream branch tracking fix for self-update, and CLI session support in the file-browser API. The kind of focused, high-quality security work that makes a self-hosted tool trustworthy.

@lucasrc — Auth-hardening trilogy (PRs #2191, #2192, #2193) Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces.

@LumenYoung — Streaming hot-path correctness (8 PRs, v0.51.47 → v0.51.99) The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase.

@dobby-d-elf — Frontend reliability + motion polish (15 PRs, v0.51.38 → v0.51.161) Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212).

@JKJameson — Composer + session polish (10 PRs) Persistent composer draft per session (#1956), and a long tail of polish across the composer and session sidebar.

@gabogabucho — Spanish locale + onboarding wizard Full Spanish (es) locale covering all UI strings, plus the one-shot bootstrap onboarding wizard that guides new users through provider setup on first launch.

@deboste — Reverse-proxy auth + mobile responsive layout (PRs #3, #4, #5) Three of the very first community PRs: fixed EventSource/fetch to use URL origin for reverse-proxy setups, corrected model provider routing from config, and added mobile responsive layout with dvh viewport fix. Early foundation work.

@indigokarasu — Visual redesign proposal (PR #213) A CSS-only redesign of the full UI — proper design tokens, an icon rail sidebar replacing the emoji tab strip, consistent form cards, breadcrumb nav, and 7 built-in themes as custom properties. The PR didn't merge as-is but shaped the design language and theme architecture that shipped in v0.50.0.

@zenc-cp — Anti-hallucination guard for the ReAct loop (PR #133) A three-layer approach (ephemeral anti-hallucination prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.

@Hinotoi-agent — Profile + session security (PRs #351, #2048) Profile .env secret isolation fix (PR #351) preventing API key leakage between profiles, and session-import workspace validation (PR #2048) blocking a crafted-JSON file-read against /.

@Sanjays2402 — Endless-scroll + Start-jump race fix (PR #1949) A generation-token + mutex pair fixing the v0.51.30 race between endless-scroll prefetch and Start-jump's _ensureAllMessagesLoaded. The naive same-flag-check approach (proposed in #1942 and #1962) was a no-op for the post-await race — Sanjays2402's fix was the correct shape.

@fxd-jason — Real-time approval + clarify via SSE (PRs #1350, #1355) Replaced 1.5s HTTP polling with SSE long-connections for both approval and clarify, cutting latency from up to 1.5s to near-instant. Got all the correctness details right (atomic subscribe + snapshot, notify-inside-lock, head-of-queue payload, trailing event re-emission).

@happy5318 — Custom provider model dedup (PR #1947) Fixed the same model from different named custom providers being silently deduplicated in the picker, with Opus catching a race in the original tests that needed augmentation.

@NocGeek — Streaming scroll + manual cron output persistence (7 PRs) Streaming scroll viewport stability when tool/queue cards insert (#1360), manual cron-run output and metadata persistence (#1372, split from held #1352).

@DavidSchuchert — German translation (PR #190) Complete German locale (de) covering all UI strings, settings labels, commands, and system messages — and stress-tested the i18n system, exposing several elements that weren't yet translatable and getting them fixed as part of the same PR.

@Bobby9228 — Mobile Profiles button (PR #265) Added the Profiles entry to the mobile navigation flow, making profile switching reachable on phones.

@kevin-ho — OLED theme (PR #168) The 7th built-in theme: pure black backgrounds with warm accents tuned to reduce burn-in risk.

@andrewy-wizard — Chinese localization (PR #177) Initial Simplified Chinese (zh) locale. One of the first non-English locales.

@DelightRun — session_search fix for WebUI sessions (PR #356) Tracked down the missing SessionDB injection in the streaming path that was silently breaking the tool for every WebUI session.

@lawrencel1ng — Bandit security fixes (PR #354) Systematic bandit-scan fixes: URL scheme validation before urlopen, MD5 usedforsecurity=False, and 40+ bare except: pass blocks replaced with proper logging.

@shaoxianbilly — Unicode filename downloads (PR #378) Proper Content-Disposition with RFC 5987 filename*=UTF-8''... encoding so non-ASCII filenames download without crashing.

@lx3133584 — CSRF fix for reverse proxy (PR #360) A real-world blocker for anyone hosting behind Nginx Proxy Manager or similar on a port other than 80/443.

@betamod — Security audit (PR #171) A comprehensive CSRF / SSRF / XSS / env-race-condition audit that shipped in v0.39.0.

@TaraTheStar — Bot name + thinking blocks + login refactor (PRs #132, #176, #181) Configurable assistant display name, thinking/reasoning block display, and a login page refactor.

from  https://github.com/nesquena/hermes-webui

-----

相关帖子: https://briteming.blogspot.com/2026/11/hermes-agent.html