herdr-remote 0.2.3 → 0.2.5

package/README.md

@@ -1,103 +1,26 @@
 # herdr-remote
 
-Use your [Herdr](https://herdr.dev) terminal workspaces from a phone or any
-browser. A mobile-first web terminal with low-latency ANSI streaming, one-time
-pairing codes, and a bilingual configuration TUI.
+*[English](README.md) · [简体中文](README.zh-CN.md)*
+
+Web terminal client for [Herdr](https://herdr.dev) workspaces. Mobile-friendly UI, low-latency ANSI streaming, and bilingual configuration TUI.
+
+## Installation & Usage
 
 ```bash
 npm install -g herdr-remote
 herdr-remote
 ```
 
-That opens the setup wizard: pick a language, pick how you want to reach the
-machine, and it starts the services for you.
-
-## Two packages
-
-| Package | Runs on | Contains |
-|---|---|---|
-| **`herdr-remote`** | your workstation | Herdr plugin, host connector, configuration TUI |
-| **`herdr-remote-relay`** | wherever you want | the relay and the web terminal |
-
-The relay is completely separate: its only dependency is `ws`, so a server
-running one needs no compiler, no Herdr and no plugin. You do not have to
-install it yourself — `herdr-remote` starts one locally unless you point it at
-your own.
-
-## Three ways to connect
-
-| Mode | Who can reach it | Needs a server? |
-|---|---|---|
-| **This machine only** *(default)* | a browser on the workstation | no |
-| **Local network / Tailscale** | phones on your LAN or tailnet | no |
-| **Self-hosted relay** | anywhere, over the internet | yes — see [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay) |
-
-Without a relay configured, the web UI is served from a local address only.
-This already covers being away from home if you run Tailscale or WireGuard.
-Only a self-hosted relay opens access from outside your network.
-
-## The TUI
-
-`herdr-remote` with no arguments opens the interface. It is bilingual —
-Chinese or English, following `$LANG` unless you choose otherwise — and works
-with the keyboard or the mouse.
-
-```
- Herdr Remote  Remote browser access to your Herdr workspaces
-
- 1 Overview  2 Pair a device  3 Services  4 Relay  5 Keep-alive  6 Herdr  7 Language & about
- ╭──────────────────────────────────────────────────────────────────────╮
- │ Status                                                               │
- │                                                                      │
- │ Access mode         This machine only                                │
- │ Relay               ● local, 127.0.0.1:8787  pid 1239815             │
- │ Host connector      ● running  pid 1239816                           │
- │ Herdr socket        ● /home/you/.config/herdr/herdr.sock             │
- │ Web UI              http://127.0.0.1:8787                            │
- │ Keep-alive          ● systemd — running                              │
- │                                                                      │
- │ Workstations        1                                                │
- │ Browsers            0                                                │
- │ Relay uptime        4m 2s                                            │
- ╰──────────────────────────────────────────────────────────────────────╯
-  ↑↓ move  ·  ↵ select  ·  ← → switch tab  ·  m mouse off  ·  q quit
-```
-
-| Tab | |
-|---|---|
-| **Overview** | live service, socket and keep-alive status |
-| **Pair a device** | one-time code with a QR you can scan |
-| **Services** | start, stop, restart, recent logs |
-| **Relay** | access mode, port, listen address, browser access address, relay URL and password |
-| **Keep-alive** | install or remove the background service |
-| **Herdr** | socket path, arguments, plugin registration |
-| **Language & about** | Chinese / English / follow the system |
+Running `herdr-remote` without arguments launches the setup wizard and configuration TUI.
 
-Keys: `↑↓` move · `↵` select or edit · `←→` or `1`–`7` switch tab · `s` save ·
-`r` refresh · `m` toggle mouse · `q` quit.
+## Connection Modes
 
-Mouse tracking turns itself on where the terminal supports it. It takes over
-text selection while active, so press `m` when you want to copy something.
+- **This machine only** *(default)*: Local workstation browser (127.0.0.1).
+- **Local network / Tailscale**: Accessible over LAN or Tailnet (0.0.0.0).
+- **Official relay**: Public relay at `wss://herdr-remote.564616.xyz`.
+- **Self-hosted relay**: External access via standalone [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay).
 
-## Pairing
-
-Open **Pair a device** and press Enter. Scan the QR code, or enter the six
-characters on the page. The browser gets a long-lived token; the code is burned
-on first use and expires after ten minutes.
-
-## Keeping it running
-
-The **Keep-alive** tab installs a service that starts the relay and host
-connector at login and restarts them if they die — a systemd user unit on
-Linux, a LaunchAgent on macOS, and a supervised background process where
-neither is available.
-
-On Linux, "Enable start at boot" runs `loginctl enable-linger` so it also comes
-up before you log in.
-
-## Command line
-
-Everything the TUI does is scriptable:
+## CLI Commands
 
 ```bash
 herdr-remote start | stop | restart
@@ -109,46 +32,18 @@ herdr-remote plugin link | unlink | status
 herdr-remote --lang zh|en
 ```
 
-## Herdr plugin
+## Herdr Plugin
 
-The package is also a Herdr plugin. Register it from the **Herdr** tab, or:
+Register as a native Herdr plugin:
 
 ```bash
 herdr-remote plugin link
 ```
 
-Nothing is compiled at registration time — the npm package ships prebuilt.
-
-> Upgrading from a source checkout? Unlink the old one first:
-> `herdr plugin unlink herdr.remote.web`. Your settings are migrated
-> automatically on first run.
-
 ## Configuration
 
-`~/.config/herdr-remote/config.json`, edited through the TUI:
-
-```json
-{
-  "ui":        { "language": "auto" },
-  "relay":     { "mode": "local", "port": 8787, "lanHost": "", "publicUrl": "", "remoteUrl": "" },
-  "herdr":     { "socketPath": null, "args": [] },
-  "keepalive": { "manager": "auto" }
-}
-```
-
-Secrets are never stored here. The workstation's host token and the relay
-password live in `~/.local/state/herdr-remote/runtime.json`, mode 0600.
-
-## Security
-
-- The relay never runs a shell and never sees your Herdr socket; only the host
-  connector on your machine does.
-- Tokens are stored as SHA-256 hashes. Terminal content is never written to disk.
-- Pairing codes are single-use, expire in ten minutes, and are rate limited.
-- Secrets never appear in URLs or shell history; the web UI strips them from the
-  address bar after pairing.
-- One writable controller at a time, with explicit takeover; other devices watch
-  read-only.
+- Settings: `~/.config/herdr-remote/config.json`
+- Runtime state: `~/.local/state/herdr-remote/runtime.json` (mode `0600`)
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,50 @@
+# herdr-remote
+
+*[English](README.md) · [简体中文](README.zh-CN.md)*
+
+[Herdr](https://herdr.dev) 工作区的 Web 终端客户端。支持移动端触控、低延迟 ANSI 传输与双语配置 TUI。
+
+## 安装与运行
+
+```bash
+npm install -g herdr-remote
+herdr-remote
+```
+
+直接运行 `herdr-remote` 即可启动向导并进入配置 TUI。
+
+## 访问模式
+
+- **仅本机** *(默认)*：仅本机浏览器可访问 (127.0.0.1)。
+- **局域网 / Tailscale**：局域网或 Tailnet 内设备可访问 (0.0.0.0)。
+- **官方 Relay**：使用官方公开 Relay (`wss://herdr-remote.564616.xyz`)。
+- **自建 Relay**：连接独立部署的 [`herdr-remote-relay`](https://www.npmjs.com/package/herdr-remote-relay) 服务。
+
+## 常用命令
+
+```bash
+herdr-remote start | stop | restart
+herdr-remote status [--json]
+herdr-remote pair [--json]
+herdr-remote url
+herdr-remote keepalive install | uninstall | restart | status
+herdr-remote plugin link | unlink | status
+herdr-remote --lang zh|en
+```
+
+## Herdr 插件
+
+注册为 Herdr 插件：
+
+```bash
+herdr-remote plugin link
+```
+
+## 配置路径
+
+- 配置文件：`~/.config/herdr-remote/config.json`
+- 运行状态：`~/.local/state/herdr-remote/runtime.json` (权限 `0600`)
+
+## 开源协议
+
+MIT

package/bin/herdr-remote.js

@@ -24,29 +24,29 @@ const { preferredLanAddress } = require('../src/net-interfaces');
 
 const VERSION = require('../package.json').version;
 
-const USAGE = `herdr-remote ${VERSION} — remote browser access to your Herdr workspaces
+const USAGE = `herdr-remote ${VERSION} — browser access to Herdr workspaces
 
 Usage: herdr-remote [command] [options]
 
 Commands:
   (none)               Open the configuration TUI
-  start                Start the relay and host connector
-  stop                 Stop them
-  restart              Restart them
+  start                Start relay and host connector
+  stop                 Stop services
+  restart              Restart services
   status [--json]      Show service status
-  pair [--json]        Create a one-time pairing code
-  url                  Print the URL to open in a browser
-  run [--daemon]       Run the services in the foreground (used by keep-alive)
+  pair [--json]        Create pairing code
+  url                  Print browser access URL
+  run [--daemon]       Run services in foreground (keep-alive)
   keepalive <action>   install | uninstall | restart | status
-  plugin <action>      link | unlink | status  (Herdr plugin registration)
+  plugin <action>      link | unlink | status  (Herdr plugin)
 
 Options:
-  --lang <zh|en>       Force the interface language
-  --json               Machine readable output where supported
-  -h, --help           Show this help
-  -v, --version        Show the version
+  --lang <zh|en>       Interface language
+  --json               JSON output
+  -h, --help           Show help
+  -v, --version        Show version
 
-Self-hosting a relay: docs/self-hosted-relay.md
+Self-hosting: docs/self-hosted-relay.md
 `;
 
 function parseArgs(argv) {
@@ -97,8 +97,7 @@ async function runTui(options) {
   const bundle = path.join(__dirname, '..', 'dist', 'tui.mjs');
   if (!fs.existsSync(bundle)) {
     process.stderr.write(
-      'herdr-remote: the TUI bundle is missing.\n'
-      + 'If you are running from a source checkout, build it first:\n'
+      'herdr-remote: TUI bundle missing. Build first:\n'
       + '  npm run build -w herdr-remote\n',
     );
     process.exitCode = 1;

package/config.example.json

@@ -7,7 +7,11 @@
     "port": 8787,
     "lanHost": "",
     "publicUrl": "",
-    "remoteUrl": ""
+    "remoteUrl": "",
+    "maxHosts": 1024,
+    "maxPendingHandshakes": 1024,
+    "maxBufferedBytesPerClient": 4194304,
+    "hostReconnectGraceMs": 30000
   },
   "herdr": {
     "socketPath": null,