omtc 是设备上的常驻 agent：守护每一个 PTY 会话（客户端断开不影响任务）、维护到 omts 的 WebSocket 传输、执行签名验证的自升级。会话从客户端创建；omtc 负责让它们活着。 omtc is the resident agent on each managed machine: it guards every PTY session (a dropped client never touches the task), maintains the WebSocket transport to omts, and performs signature-verified self-updates. Sessions are created from the client; omtc keeps them alive.
安装与注册Install & registration
推荐路径：客户端「添加机器」生成一条一次性安装命令（Linux/macOS 为 install-v3.sh，Windows 为 install-v3.ps1），在目标机器执行——脚本换取一次性注册令牌、下载并校验二进制、完成 register 与 init，客户端界面随后显示设备上线。也可以手动执行 omtc register（见下表）。
Recommended path: the client's "Add a machine" generates a one-time install command (install-v3.sh on Linux/macOS, install-v3.ps1 on Windows) — run it on the target machine and the script exchanges the setup token, downloads and verifies the binary, then runs register and init; the client UI flips to online. Manual omtc register works too (see below).
命令Commands
注册与信任Registration & trust
| 命令Command | 说明Description |
|---|---|
omtc register | 向 omts 注册设备。常用参数：-n/--name（设备名）、-r/--reg-token（注册令牌）或 -c/--code（<server-url>/<token> 一体码）、-s/--server-url、--release-pubkey（升级通道公钥）、--insecure（自签 TLS 测试端点）。注册前打印解析出的服务器地址并要求交互确认（-y 跳过）。Register the device with omts. Common flags: -n/--name, -r/--reg-token or -c/--code (<server-url>/<token>), -s/--server-url, --release-pubkey (update-channel key), --insecure (self-signed TLS test endpoints). Prints the resolved server URL and asks for confirmation (-y skips). |
omtc init | 首装引导：记录升级公钥（--release-pubkey）、生成或复用 16 位 Bootstrap Commit 并展示（--bootstrap-only 只出指纹；--force 轮换；--identity 指定 SSH 私钥）。First-install bootstrap: records the release pubkey (--release-pubkey), creates or reuses the 16-hex Bootstrap Commit and displays it (--bootstrap-only prints the fingerprint only; --force rotates; --identity selects an SSH key). |
omtc re-register | 只清升级公钥，供可信安装器写入轮换后的 key；设备身份与令牌保留。Clears only the release pubkey so a trusted installer can write the rotated key; device identity and tokens are preserved. |
omtc passwd [--clear] | 可选的设备连接密码：免去 authorized_keys 仪式直接连接新浏览器。密码本身不上线——浏览器用 Argon2id 派生密钥 + HMAC 证明认证。设置 --clear 清除。请用长密码：录制的握手可被离线猜解。Opt-in device password: connect a new browser without the authorized_keys ceremony. The password never crosses the wire — the browser authenticates with an Argon2id-derived key + HMAC proof. Use a long password: a recorded handshake can be guessed offline. |
日常运维Everyday operations
| 命令Command | 说明Description |
|---|---|
omtc start | 启动到 omts 的常驻传输（幂等）：健康则 no-op，需恢复则自动接管，什么都没有则前台运行（开机自启执行的就是它）。Start the persistent transport to omts (idempotent): no-op when healthy, automatic takeover when recovery is needed, foreground run otherwise — this is what the autostart entries exec. |
omtc stop [-y] | 停传输并停 pty-holder——活会话会被终止。需确认，-y 跳过。Stop the transport AND the pty-holder — live sessions are terminated. Asks for confirmation; -y skips. |
omtc takeover | 保会话重启：只换传输，pty-holder 与全部活会话原地不动。升级后的标准动作。Session-preserving restart: replaces the transport while the pty-holder and every live session stay put. The standard move after an upgrade. |
omtc restart [-y] | 完整重启：传输与 holder 都回收，活会话丢失（保会话用 takeover）。Full restart: recycles transport and holder — live sessions are lost (use takeover to preserve them). |
omtc upgrade | 自升级：按 client.conf 里的服务器与公钥取 metainfo.json，验 Ed25519 签名与 SHA-256 后原子替换自身，必要时自动 takeover。-y 免确认；--from-manifest / --release-host 走旧版发布主机通道（覆盖需一次性确认并持久记录）。Self-update: reads the server + pinned key from client.conf, fetches metainfo.json, verifies the Ed25519 signature and SHA-256, atomically replaces itself, then takes over as needed. -y skips prompts; --from-manifest / --release-host use the legacy release-host channel (overrides need a one-time confirmation, persisted). |
omtc status | 一览：版本、注册的服务器、传输与 holder 进程、运行时新鲜度、自启条目状态。One glance: version, registered server, transport + holder processes, runtime freshness, autostart entry state. |
omtc ls | 列出本地 holder 里的会话（id 前缀、显示名、末行输出）。走本地 IPC，omts 不可达也能用。List the local holder's sessions (id prefix, display name, last screen line). Talks local IPC, so it works with omts unreachable. |
omtc attach [<id>] | 把会话接到当前终端——本地版的 web 终端，路径上没有 omts。本地 attach 与 web 客户端可同时观看同一会话。不带 id 时出交互选择器；detach 是 screen 式 Ctrl+A 前缀（见下）。Attach a session to the current terminal — the local counterpart of the web terminal with no omts in the path. A local attach and the web client can watch the same session at once. Without an id it opens the interactive picker; detach is screen-style via the Ctrl+A prefix (below). |
omtc autostart … | 开机自启管理：on/off/status/pause/resume。macOS 交互开启时可选 --system（登录前启动，推荐）或 --user（登录后启动）；Linux 用 crontab。Boot-start management: on/off/status/pause/resume. On macOS an interactive enable offers --system (starts before login, recommended) or --user (after login); Linux uses crontab. |
omtc uninstall | 关自启、从 omts 注销设备（尽力）、停本地进程、删除 ~/.omt/。Disables autostart, unregisters from omts (best effort), stops local processes, deletes ~/.omt/. |
omtc version | 打印版本号。Prints the version string. |
attach 的 Ctrl+A 前缀键（screen 习惯）The Ctrl+A prefix inside attach (screen habits)
| 按键Keys | 效果Effect |
|---|---|
| Ctrl+A D / Ctrl+A Ctrl+D | detach（打印 [detached]，退出码 0）detach (prints [detached], exit 0) |
| Ctrl+A A / Ctrl+A Ctrl+A | 向会话发送一个字面 Ctrl+Asend one literal Ctrl+A to the session |
| Ctrl+A ? | 一行按键提示one-line key reminder |
| Ctrl+A <other> | 两个键原样进会话both keys pass through to the session |
配置文件：~/.omt/client.confConfig: ~/.omt/client.conf
key=value 文本格式，权限 0600，由 register/init/upgrade 维护，一般不需要手改。可选键改完重启传输生效（omtc restart；takeover 不重读 holder 相关键）。
A key=value text file, mode 0600, maintained by register/init/upgrade — manual edits are rarely needed. Optional keys take effect after a transport restart (omtc restart; takeover does not re-read holder-scoped keys).
| key | 默认Default | 说明Description |
|---|---|---|
device_id / device_token | — | 注册时写入的设备身份与令牌。Device identity and token, written at registration. |
server_url_cache | — | 注册的 omts 地址缓存（自升级取 metainfo 的基准）。Cached omts URL (the base for metainfo during self-update). |
release_pubkey_b64 | — | 升级通道信任锚：Ed25519 公钥。manifest 轮换 key 时 upgrade 会自动采纳新值。The update-channel trust anchor: the Ed25519 pubkey. When a manifest rotates the key, upgrade adopts the new value automatically. |
output_flush_ms | 5 | holder→WS 终端输出合并窗口（毫秒，1–1000）。Holder→WS terminal output coalescing in ms (1–1000). |
activity_echo_window_secs | 5 | 浏览器触发的刷新/resize 后，该窗口内的输出视为回显、不计入 Working 状态（0 关闭，0–60）。Output within this window after a browser-driven resize/refresh counts as viewer echo, not Working activity (0 disables, 0–60). |
activity_idle_after_secs | 15 | 最后一次真实输出后多久从 Working 转为空闲（5–3600）。How long a session stays Working after its last real output (5–3600). |
snapshot_style_mode | visible | attach 快照样式：visible 只保留可见屏样式；full 保留整份快照（同字节上限下回放深度变浅）。Attach-snapshot styling: visible keeps styling for the restored screen only; full styles the entire snapshot (shallower retained history under the same byte cap). |
p2p_enabled | true | 设备侧 P2P 开关；false 拒绝一切 viewer 信令、立即走中继。环境变量 OMT_DISABLE_P2P=1 单次运行强制关闭。Device-side P2P switch; false refuses every viewer signal and falls back to the relay. OMT_DISABLE_P2P=1 forces it off for one run. |
file_max_upload_size / file_max_download_size | 0 | 文件上传/下载上限（字节，0=不限）——设备保护自己的盘，中继与 P2P 传输都生效。File upload/download caps in bytes (0 = unlimited) — the device protecting its own disk; applies to relayed and P2P transfers alike. |
max_alive_sessions | 64 | 并发活会话硬上限（0=不限），防失控创建循环；holder 启动时读取，改后需 omtc restart。Hard cap on concurrent alive sessions (0 = unlimited) against runaway create loops; read once at holder start — omtc restart picks up changes. |
identity_fp | — | 诊断键：传输最近一次使用的身份密钥指纹；变化时打告警（意味着浏览器会要求重新 TOFU）。Diagnostic: SSH fingerprint of the identity key the transport last used; a change logs a warning (browsers will demand TOFU re-verification). |
磁盘布局On-disk layout
| 路径Path | 内容Contents |
|---|---|
| ~/.omt/client.conf | 配置（上表）。Config (table above). |
| ~/.omt/bootstrap-commit | 16 位设备指纹（TOFU 校验用）。The 16-hex device fingerprint (for TOFU verification). |
| ~/.omt/identity.ed | 设备 Ed25519 身份密钥。The device's Ed25519 identity key. |
| ~/.omt/passwd | 可选的连接密码派生密钥（存在即启用，0600）。Optional password-derived key (its existence is the switch, 0600). |
| ~/.ssh/authorized_keys | 被授权连接本设备终端的浏览器公钥（与 SSH 同机制，独立于 ~/.omt）。Browser public keys authorized to connect to this device's terminals (same mechanism as SSH, separate from ~/.omt). |
| ~/.omt/takeover.lock 等 | 运行时文件：takeover 文件锁、pty-holder 版本戳、密码重放账本。Runtime files: the takeover lock, pty-holder version stamp, password replay ledger. |
自升级信任链The self-update trust chain
- 取
{server_url_cache}/metainfo.json，按平台与当前版本选出条目。Fetch{server_url_cache}/metainfo.jsonand select the entry for this platform and client version. - 验内联 manifest 的 Ed25519 签名（用钉住的
release_pubkey_b64），才信任其中的 SHA-256。Verify the inline manifest's Ed25519 signature (against pinnedrelease_pubkey_b64) before trusting its SHA-256. - 下载二进制、核对哈希、原子替换运行中的自身；manifest 轮换公钥时同步更新信任锚。Download the binary, verify the hash, atomically replace the running binary; adopt a rotated pubkey from the manifest.
- 运行时契约有变时询问（或
-y）后takeover，会话不中断。Take over (asking, or with-y) when the runtime contract changed — sessions survive.
常见问题FAQ
| 问题Question | 答案Answer |
|---|---|
| 关掉客户端，会话还在吗？Do sessions survive a closed client? | 在。会话由设备端 pty-holder 守护，与客户端生命周期解耦；只有 omtc stop/omtc restart 或机器关机才会终止。Yes. Sessions live in the device-side pty-holder, decoupled from the client; only omtc stop/omtc restart or host shutdown ends them. |
| 忘了设备连接密码？Forgot the device password? | 在设备上 omtc passwd --clear 清除，回到 authorized_keys 仪式；或重新设置。Run omtc passwd --clear on the device to fall back to the authorized_keys ceremony, or set a new one. |
| 怎么彻底移除设备端？Remove the device agent completely? | omtc uninstall：关自启、注销、停进程、删 ~/.omt/。omtc uninstall: disables autostart, unregisters, stops processes, deletes ~/.omt/. |