Skip to content
Projects

riba2534/herdrx has 40 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 16:29 UTC. Last push 2026-11-02.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

自托管、多用户的 Herdr 远程终端工作台:SSH / Tailcat、多主机分屏、移动端与签名 CLI 更新。

Developer Tools

README.md

Original

herdrx Logo

herdrx

自托管、多用户的 Herdr Agent 工作台
在电脑和手机上用 Web 界面驱动多台主机上的 Claude Code,需要时切到完整终端。

Docker Hub Release Linux amd64 / arm64 GitHub Stars MIT License

快速开始 · 接入主机 · 日常使用 · 更新与数据 · 常见问题


herdrx 是 Herdr 的 Web 客户端,为 Agent 而生,适合个人和可信小团队。把运行 Herdr 的主机接入后,你可以在电脑和手机上用 Web UI 查看 Claude Code 的对话与工作过程、回答提问、批准计划、新建会话;需要完整终端时切到 Web Shell,继续分屏、快捷键和任何终端程序。

Herdr 和任务独立运行在远程主机上。 关闭浏览器、退出账号或重启网站后,远程任务继续运行;重新进入即可连接原有会话。远程主机自身的重启与任务恢复由 Herdr 和任务管理器负责。

当前为预发布阶段,版本与已知限制见 发布说明。

你可以做什么

功能 使用方式
用 Web UI 驱动 Claude 默认进入 Web UI:Claude 的对话、工作过程(读文件、命令、diff)折叠成一行可展开;提问、计划审批、信任目录用卡片作答;状态栏显示进度、权限模式和中断按钮
新建 Claude 会话 选目录和远程主机 ~/.zshrc 里的启动器 alias(显示是否免授权),在新工作区或标签页中启动;alias 正文不离开远程主机
管理多台主机 使用 SSH 或 Tailcat 接入,按名称和地址搜索,通过文件夹分组
在 Web Shell 中操作终端 切换工作区、标签页与终端,使用分屏、历史滚动、中文输入和 Shift+Enter;手机上点终端直接逐键输入(Tab 补全、方向键、Ctrl 组合键),点输入框则本地编辑、整段发送
跨主机查看 Agent Agent 总览汇总所有主机的 Agent,等待你处理和完成未看的排在最前,点一下进入对应终端
向 Agent 传图片 粘贴、拖入或上传 PNG/JPEG/WebP/GIF,单张最大 20 MB
在手机上继续任务 单终端视图、本地输入框、辅助键条;终端按屏幕自动选择完整显示、铺满宽度或可读字号,双指捏合调整字号,弹出键盘不改变远端尺寸
用画面视图阅读 读取 Herdr 已渲染的画面,按手机宽度折行、可直接选中复制,不改变远端尺寸;输入用本地输入框
调整外观 独立切换网站与工作台主题,选择终端配色
复用 SSH 密钥 导入或生成密钥,在多台主机中选择使用
邀请团队成员 管理员开启邀请注册;每个账号管理自己的主机和密钥
安装为应用、接收通知 通过浏览器安装到桌面或手机,按浏览器支持启用通知

快速开始

部署网站的机器需要 Linux(amd64 或 arm64)和 Docker Engine。运行任务的远程主机需要提前安装并运行 Herdr。

1. 一键 Docker 部署

下列命令创建部署目录、准备数据权限,并从 Docker Hub 拉取公开镜像启动网站:

mkdir -p herdrx && cd herdrx &&
sudo install -d -m 700 ./data &&
sudo chown 65532:65532 ./data &&
docker run -d \
  --name herdrx \
  --restart unless-stopped \
  --pull always \
  --security-opt no-new-privileges:true \
  -p 8080:8080 \
  -e HERDRX_PUBLIC_URL=http://localhost:8080 \
  --mount type=bind,source="$(pwd)/data",target=/data \
  riba2534/herdrx:latest

在另一台电脑或手机上访问时,先把命令中的 http://localhost:8080 改成工作台主机的实际 IP 地址和端口。 这个地址必须与你在浏览器中打开的地址一致。默认使用 HTTP,无需域名或证书。

镜像自动匹配 amd64 / arm64。数据保存在当前部署目录的 ./data 中。上面的 sudo 用于将目录交给镜像默认用户 65532:65532;这个数字并非固定要求,也可使用宿主机的普通用户运行,见 目录权限。

2. 创建管理员

在刚才的部署目录读取初始化令牌:

sudo cat ./data/bootstrap-token

打开 http://localhost:8080(远程访问使用你配置的地址),填写令牌并创建管理员。创建成功后令牌文件自动删除,之后使用邮箱和密码登录。

注册默认关闭。需要其他账号时,在「管理 → 用户注册」开启邀请注册,再创建邀请码交给成员。

3. 接入主机

登录后点击「添加主机」,选择下面任一方式。网站不会安装、升级或停止远程 Herdr;SSH 主机上的 Herdr 没有运行时,可以在工作台点「在远程主机启动 Herdr」。

接入远程主机

SSH

适合工作台主机能够直接通过 SSH 访问的远程主机。

  1. 在「添加主机」中选择 SSH,填写地址、端口和用户名。
  2. 选择密码或密钥认证;已有私钥可先在「密钥」页导入。
  3. 核对首次连接的 SSH 指纹,保存后打开主机。

连接用户应为运行 Herdr 的用户;远程 sshd 需允许 Unix socket 转发,全屏应用滚动还需要 Python 3。安装在特殊路径、密钥与证书配置见 安装说明。

Herdr 没有运行时,工作台会显示「在远程主机启动 Herdr」。点击后网站通过 SSH 在后台启动它:远程用户开启了 linger 时放进独立的用户服务,否则脱离本次 SSH 会话运行。关闭网页或网站重启都不影响已启动的 Herdr;已在运行的 Herdr 不会被重复启动或重启。

Tailcat 内网穿透

适合无法从工作台直接 SSH 访问的 Linux 主机。CLI 支持 x86_64 / ARM64。

在「添加主机 → Tailcat 内网穿透」中,按页面提供的三步引导操作:

  1. 以运行 Herdr 的同一用户,在远程主机复制并执行页面中的 GitHub 一行 CLI 安装命令,自动识别架构和校验。
  2. 执行 ~/.local/bin/herdrx setup && ~/.local/bin/herdrx status,按提示启用后台保活。
  3. 执行 ~/.local/bin/herdrx connect --plain,将一次性绑定凭据粘贴到页面并连接。

从网页复制连接命令时,会优先探测工作台自带中继;工作台具有公网 HTTPS 且中继握手成功时优先使用,连不通则在生成凭据前回退公共中继。默认 HTTP 部署直接使用公共中继,无需额外配置。已有绑定可通过主机卡片「更新连接端点」迁移。

绑定凭据 10 分钟内有效且只能使用一次,请勿公开分享。完整安装、后台运行、手动下载及排障见 Tailcat 接入教程。

日常使用

工作台有 Web UI 和 Web Shell 两种模式,用顶栏(手机在顶部右侧)的 UI / Shell 开关切换,默认 Web UI。两者看的是同一组工作区和终端,切换不会重启终端或影响远程任务。Web UI 中,Claude 终端显示对话视图:你的消息在右侧气泡,Claude 的工作过程折叠成一行可展开,需要你回答的提问、计划审批和信任目录以卡片替代输入框,输入框上方的状态栏显示进度、权限模式(点击切换,相当于 Shift+Tab)和中断按钮;其他终端显示只读画面和一行命令输入,「在 Shell 中打开」可切到完整终端。「新建 Claude 会话」按远程主机 ~/.zshrc 里的 alias 启动 Claude。第一版只为 Claude Code 提供对话视图,其他 Agent 请在 Web Shell 中使用。说明见 Web UI 与 Web Shell。

以下是 Web Shell 模式的操作说明。

进入主机后,选择原有工作区和标签页,在对应终端中继续操作。电脑上可拖动分屏分隔或用 Ctrl+B R 调整比例,Ctrl+B ? 查看快捷键;断线时顶部条幅可立即重连,不必整页刷新。手机上终端和底部输入框同时可用,点哪里就输入到哪里:点终端画面直接逐键输入,Tab 补全、方向键历史和 Ctrl 组合键立即生效,并自动展开辅助键(手动收起后不再自动展开;屏幕较矮时辅助键优先,输入框暂时收起、草稿保留,点顶栏键盘按钮即可切回);点输入框则在本地编辑,中文、粘贴和换行都在本地完成,点击「发送」后整段进入当前终端并提交一次。输入框左侧的图标显示当前输入去向,也可从这里切换。平板等触屏设备在电脑布局下也可从标签栏的键盘按钮打开辅助键。底部辅助键与 orca 手机端同序:Esc、Tab、Enter、Shift+Tab、空格、退格、Del、方向键,以及 Ctrl+C/D/L/Z/R/A/E/W/U,退格、Del 和方向键可长按连发;方向键后的 Ctrl、Alt、⇧ 是粘滞修饰键,点一下只作用于下一个键(键栏或软键盘输入),例如 Alt+← 按词左移,⇧+Enter 与实体键盘的 Shift+Enter 一样换行,再点一次取消;「粘贴」只送正文不追加回车。终端工具里可打开「选择文本」或「复制屏幕」。发送成功只表示输入已被接受,不代表远端程序已经执行完。电脑和手机的输入方式分开记住:缩小窗口不会把手机输入框留在电脑上,电脑上主动打开的本地输入也不会被窗口变化清掉。

画面视图读取 Herdr 已经渲染好的终端文字,默认按当前窗口宽度折行,手机上无需缩小字号即可阅读宽任务的输出,也可以直接选中复制;头部按钮可切换“原样排版”、调整字号或加载更早内容(最多最近 1000 行)。它不申请尺寸控制、不改变远端尺寸,输入使用底部本地输入框和辅助键。从终端工具栏的“画面视图”、手机终端角标菜单或切换面板进入;光标、鼠标点击和全屏程序的交互请切回终端。说明见 画面视图。

电脑上每个分屏标题栏、手机上顶栏都有 Terminal / Chat 开关,切换只改变网页视图,不重启终端或 Agent。Chat 从 Agent 自己的会话记录读取真实问答(Claude、Codex、DeepSeek Harness、Cursor Agent、Gemini CLI、Antigravity CLI、Pi、Grok CLI、Trae CLI;Antigravity 只能通过 Herdr 的 Agent 集成打开),用户在右、助手在左,支持 Markdown、代码复制和工具记录。远端装了 Herdr 的 Agent 集成时,Chat 直接打开 Herdr 上报的当前会话;否则需手动选择会话记录,即使只有一个候选也不会自动认领。已完成的一轮会把工具调用等中间过程折叠成一行,点开可看全部;Agent 工作中插入的消息也会显示。所选记录只用于查看,输入始终发送到当前终端。

会话读取支持本机、具备 Python 3 的 SSH 远程主机,以及受控端 CLI 已更新到 v0.1.0-rc.3 或更新版本的 Tailcat 主机;受控端版本过旧时提示更新后重试。未支持的 Agent 会提示切回终端,不会用屏幕文本伪造对话。遇到权限确认、交互菜单等 TUI 操作,也请切回 Terminal。读取暂时失败可重试,网站重启后可能需要重新选择记录。

Chat 输入框中 Enter 发送、Shift+Enter 换行,中文输入法确认候选时不会发送。断线时禁用发送,结果不确定时不自动重发。终端、远端任务及观察流不依赖 Chat 的开关状态。

本地输入框和 Chat 发送前会先读一次终端画面:Agent 正弹着选择对话框时不发送,改为显示可点选的对话框卡片;电脑上的输入框里有未发送的内容时,先询问再发送。Agent 状态为“需要你”时,工作台也会直接显示该卡片。说明见 发送防护与对话框卡片。

本地显示默认“自动”:先按字号上限完整显示远端画面;放不下时铺满宽度、上下滑动查看;字号需要小于 10 px(手机 9 px)时保留可读字号并四向滑动。电脑默认 14 px,手机默认 13 px,电脑布局、手机布局和手机横屏分别记忆。手机上终端画面右上角常驻一个角标,显示远端行列与控制状态;电脑上只在画面被裁切、由其他窗口控制或远端尺寸明显小于当前窗口时出现。点开角标可切换“自动 / 完整显示 / 固定字号”、调整字号,手机上还可直接切到对话视图。手机和平板在终端画面上双指捏合即调整字号,松手后生效;捏到最小以下切换为完整显示,页面其他区域仍可使用浏览器缩放。这些本地显示选项只改变当前页面,不改变远端尺寸。

打开、刷新、输入或重新打开 PWA 都保持远端任务尺寸。需要程序按当前窗口重新换行时,在角标菜单或终端工具的“任务尺寸”中选择“使用此窗口尺寸”,菜单会先说明远端将从多大改为多大,列数少于 50 时提示表格和 diff 可能折行;同一终端的其他窗口也会看到变化,并在角标上显示“其他窗口控制”,可确认“转到此窗口控制”。控制期间旋转屏幕或调整字号会重新排版,弹出软键盘只遮住画面、不改变远端行数。结束时可选“恢复为原尺寸并释放”,或“释放控制”保持当前尺寸;切离终端、进入后台或断线也会释放控制,但不会自动恢复。其他窗口释放控制后如果留下的尺寸比当前窗口小很多,角标提示“较小”,可一键“按此窗口尺寸恢复”,调整一次后继续观察。电脑上远端尺寸明显小于当前窗口时,角标也会提示“较小”;这可能是先前留下的尺寸,也可能受其他 Herdr 客户端(例如手机上的原生 Herdr)影响,可选择一次性恢复或“使用此窗口尺寸”并保持控制。一次性调整或恢复后,页面会继续观察 4 秒;如果观察到尺寸再次变化,会给出提示,并在较小尺寸的菜单中引导保持控制。输入不需要取得尺寸控制。

Chat 支持粘贴、拖入或选择图片:先显示可移除的缩略图并上传暂存,不会立即向终端输入路径;点发送后,文字和图片引用一起提交一次,也可以只发送图片。上传失败时先移除或重试失败附件。普通 Terminal 模式仍保留原有图片粘贴路径行为;Agent 是否能读取图片取决于其自身能力。

管理员配置语音网关后,Chat 显示麦克风按钮。首次使用需浏览器授权(HTTPS 或 localhost);转写只追加到当前草稿,不会自动发送或执行命令。可选的语音回复来自独立语音助手,不代表终端 Agent。停止录音、离开 Chat 或退出登录会释放麦克风和连接。配置方法见 语音网关。

在主机列表通过文件夹整理主机;在「密钥」页管理可复用的 SSH 密钥。详细步骤见 SSH 密钥与文件夹。

从浏览器菜单安装 herdrx,可作为独立窗口使用。启用通知后,Agent 等待输入时立即提醒;完成后 60 秒内没有在工作台看过才提醒,点通知直接打开对应 pane。安装后的应用图标提供“Agent 总览”“主机列表”快捷方式(需系统支持)。安装和后台通知需要浏览器支持;普通 HTTP/IP 可以使用网站和终端,PWA 与通知通常需要 HTTPS 或本机 localhost。需要 HTTPS 时可接入自己的反向代理,见 运维说明。

更新与数据

riba2534/herdrx:latest 提供最新通过验证的主分支镜像。已有容器不会自动更新;先按 备份说明 备份,再在原部署目录执行下面的命令,并保留原来的访问地址、端口和其他配置:

docker pull riba2534/herdrx:latest &&
docker stop herdrx && docker rm herdrx &&
docker run -d \
  --name herdrx \
  --restart unless-stopped \
  --security-opt no-new-privileges:true \
  -p 8080:8080 \
  -e HERDRX_PUBLIC_URL=http://localhost:8080 \
  --mount type=bind,source="$(pwd)/data",target=/data \
  riba2534/herdrx:latest

重建容器复用原 ./data,保留账号、主机和密钥。不要删除数据目录,也不要让两个实例同时使用它。 备份必须包含完整数据库、master.key 和通知身份;固定版本、回退与恢复见 更新与恢复。

常用管理命令:

docker logs --tail 100 herdrx                       # 查看日志
docker exec herdrx /app/herdrx-server healthcheck   # 检查健康状态
docker stop herdrx                                 # 停止网站
docker start herdrx                                # 启动网站

需要额外配置时,在 docker run 中加入 -e 变量名=值 后重建容器:

配置 用途
HERDRX_PUBLIC_URL 浏览器实际访问的网站地址
HERDRX_COOKIE_SECURE=true 自行配置 HTTPS 后启用
HERDRX_ALLOWED_ORIGINS 额外允许的完整访问地址,多个用逗号分隔
HERDRX_TRUSTED_PROXIES 反向代理的出口 IP/CIDR,直接访问时留空
HERDRX_MAX_HOST_CONNECTIONS=20 全实例同时连接的主机上限
HERDRX_DERP_RELAY=auto 公网 HTTPS 工作台自动提供受限中继;off 关闭
HERDRX_DERP_STUN_ADDR=off 可选 UDP STUN,开启方式见运维文档
HERDRX_HOST_DIAL_CONCURRENCY=4 同时建立连接的数量上限
HERDRX_SESSION_TTL=720h Web 登录有效期

常见问题

登录提示 origin_forbidden? 检查 HERDRX_PUBLIC_URL 是否与浏览器地址一致,包括协议和端口。修改环境变量后需要重建容器。

忘记密码? 请管理员在「管理 → 用户」中重置密码,用临时密码登录后按提示设置新密码。

8080 端口已占用? 把 -p 8080:8080 改成例如 -p 18080:8080,同时把 HERDRX_PUBLIC_URL 的端口改为 18080。

Docker 中如何接入宿主机 Herdr? 使用 SSH 或 Tailcat。网站的「本机」指容器内部,不能直接访问宿主机上的 Herdr。

关闭网站会停止任务吗? 远程 Herdr 与任务继续运行;网站恢复后重新连接原会话。网站与 Herdr 同机运行时,共享整机故障边界。

SSH 支持跳板机、alias 和 Kerberos 吗? 密码/密钥连接支持单跳 ProxyJump(如 user@jump-host:22),跳板与目标共用网站保存的凭据,仅固定目标主机密钥。管理员也可显式启用 System OpenSSH,复用工作台服务账号的 SSH alias、ProxyJump/ProxyCommand 和 Kerberos/GSSAPI;该模式不使用网站凭据、不转发 ssh-agent,跳板配置由服务账号的 SSH 配置提供。Docker 不会自动继承宿主机 ticket,详见 System OpenSSH 安装说明。

可以共享主机或部署多个网站副本吗? 当前每台接入记录归属一个账号,使用单实例部署。请在可信环境中使用:实例管理员能够接触终端内容和解密后的连接凭据。

更多使用说明

致谢与许可

感谢 Herdr 和 Tailcat;Web UI 对话界面的设计与部分代码改编自 Cindy(Apache-2.0)。herdrx 使用 MIT 许可证,第三方依赖声明见 THIRD_PARTY_NOTICES.md。