PocketShell v1.9.0

v1.9.0 — 2026-08-05

新增

• 在线演示站：demo.pocketshell.net 无需安装 agent、无需常开的机器即可试用完整界面（真实前端 + 模拟后端，数据均为假数据，刷新即还原）。手机打开是全屏 App，桌面打开是展台页（手机框内嵌真实界面）。
• 演示站「试试断网」：一键真实断开连接并触发重连补齐，用于演示断线期间输出如何回填（演示站专有，正式版无此按钮）。

变更

• 调试接口默认关闭：window.pocketshell 自动化接口不再随正式构建发布，需构建时显式设置 VITE_POCKETSHELL_DEV_HELPERS=1 才启用。此前默认开启，正式版会暴露该接口。

修复

• 演示站空闲自动断线：模拟传输层在 send() 调用栈内同步回帧，导致握手超时定时器失去引用，连接约每 8 秒自行断开一次。改为异步投递（仅影响演示站，正式版走真实 WebSocket，不受影响）。

已知问题

• 演示站不注册 Service Worker，不支持「添加到主屏幕」；其余功能与正式版一致，但写操作、上传下载、通知接线等返回「演示环境不支持」。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

v1.9.0 — 2026-08-05 (English)

Added

• Live demo site: demo.pocketshell.net runs the full interface with no agent install and no always-on host (real frontend, simulated backend; all data is fake and resets on reload). On a phone it opens fullscreen; on a desktop it appears inside a phone frame alongside an overview.
• "Try going offline" in the demo: drops the connection for real and replays the output missed while disconnected (demo only — not present in release builds).

Changed

• Debug interface off by default: the window.pocketshell automation surface is no longer included in release builds. Set VITE_POCKETSHELL_DEV_HELPERS=1 at build time to opt in. It was previously enabled by default and shipped in release builds.

Fixed

• Demo site disconnected while idle: the simulated transport delivered its handshake reply synchronously inside send(), orphaning the handshake-timeout timer and dropping the connection roughly every 8 seconds. Delivery is now asynchronous (demo only; release builds use a real WebSocket and were never affected).

Known issues

• The demo does not register a Service Worker and cannot be added to the home screen. Everything else matches the release build, except that writes, uploads/downloads and notification wiring return "not available in the demo sandbox".

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

Restart after upgrading a service install: sudo systemctl restart pocketshell (launchd relaunches it automatically on macOS).

PocketShell v1.8.0

v1.8.0 — 2026-08-03

变更

• devices remove 对常驻 Agent 即时生效：Agent 每 3 秒轮询设备表，命令行删除设备后数秒内该设备失去授权、在线连接被断开、推送订阅被清除，无需重启。
• 应用内更新只从官方仓库安装：POCKETSHELL_UPDATE_REPO 指向其他仓库时，检查更新照常工作，但不再自动替换二进制。

修复

• devices remove 对运行中的 Agent 无效：命令行删除的设备仍能连接，且 Agent 的下一次心跳会把该设备写回设备表、静默撤销这次删除 → 现在删除立即生效且不会被写回。

移除

• 网页管理页（/admin、/admin-api/*）：改用命令行 pocketshell-agent pair / devices list / devices remove <指纹>，功能一一对应。
• POCKETSHELL_ADMIN 环境变量：已不再被读取，保留在配置里不影响启动。

安全

• 管理页可被公网匿名访问（高危）：管理页唯一的凭证是「请求来自 127.0.0.1」，而同机反向代理（Caddy / Nginx / Cloudflare Tunnel / frp，即部署文档推荐的全部四种）正是从该地址连入，因此公网请求也能通过。任何人 POST /admin-api/pair 即可取得可用配对串，完成配对后获得完整操作员权限 → 管理页整体移除。在 v1.7.x 或更早版本上跑过反向代理部署的用户请自查：<keyDir>/audit.log 中有无自己未触发的 admin_pair_new 事件，以及 pocketshell-agent devices list 中有无不认识的设备。
• 管理接口 CSRF：管理接口的 POST 端点无 CSRF 防护，可被恶意页面跨域触发 → 随管理页移除一并消失。
• 文件预览允许任意来源跨域读取：预览响应带 access-control-allow-origin: *，预览地址一旦泄露即可被任意站点跨域读取 → 移除该响应头（App 通过 <img>/<video>/<iframe> 加载，不受影响）。
• 应用内更新的校验链自引用：二进制与其校验文件来自同一 Release，改写 POCKETSHELL_UPDATE_REPO 即可让 Agent 自动安装任意二进制 → 自动更新限定为官方仓库。

已知问题

• 预览地址中的令牌仍在 URL 路径里（有效期 30 分钟，响应已带 no-referrer 与 no-store）。改为请求头传递会破坏视频的分段请求，暂不改动。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

升级后如需管理设备，改用命令行（在 Agent 所在机器上执行）：

pocketshell-agent pair                          # 生成配对串
pocketshell-agent devices list                  # 查看已配对设备
pocketshell-agent devices remove <指纹>          # 吊销设备

---

v1.8.0 — 2026-08-03

Changed

• devices remove now takes effect on a running Agent: the Agent polls the device registry every 3 seconds, so a device removed from the command line loses its authorization, has its live connection closed, and has its push subscriptions dropped within seconds — no restart required.
• In-app updates install only from the official repository: with POCKETSHELL_UPDATE_REPO pointing elsewhere, update checks keep working but the binary is no longer replaced automatically.

Fixed

• devices remove did nothing to a running Agent: a device removed from the command line could still connect, and the Agent's next heartbeat wrote it back into the registry, silently undoing the removal → removal now applies immediately and is not written back.

Removed

• The web admin page (/admin, /admin-api/*): use pocketshell-agent pair / devices list / devices remove <fingerprint> instead — the commands cover the same functions.
• The POCKETSHELL_ADMIN environment variable: no longer read; leaving it in a service config does not affect startup.

Security

• The admin page was reachable anonymously from the public internet (high severity): its only credential was a check that the request came from 127.0.0.1, but a same-host reverse proxy (Caddy / Nginx / Cloudflare Tunnel / frp — all four setups the deployment guide recommends) connects from exactly that address, so requests from the internet passed it too. Anyone could POST /admin-api/pair, obtain a working pairing string, and pair into full operator access → the admin page has been removed entirely. If you ran a reverse-proxied deployment on v1.7.x or earlier, check for unauthorized access: look for admin_pair_new events you did not trigger in <keyDir>/audit.log, and unfamiliar devices in pocketshell-agent devices list.
• Admin API CSRF: the admin POST endpoints had no CSRF protection and could be triggered cross-origin by a malicious page → gone with the admin page.
• File previews were readable cross-origin by any site: preview responses carried access-control-allow-origin: *, so a leaked preview URL could be read from any origin → the header has been removed (the app loads previews via <img>/<video>/<iframe>, which are unaffected).
• The in-app update verification chain was self-referential: the binary and its checksum file come from the same release, so changing POCKETSHELL_UPDATE_REPO was enough to make the Agent install an arbitrary binary → auto-apply is now restricted to the official repository.

Known issues

• Preview tokens still travel in the URL path (30-minute lifetime; responses carry no-referrer and no-store). Moving them to a request header would break ranged requests for video, so this is unchanged for now.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

To manage devices after upgrading, use the command line on the Agent host:

pocketshell-agent pair                          # mint a pairing string
pocketshell-agent devices list                  # list paired devices
pocketshell-agent devices remove <fingerprint>  # revoke a device

PocketShell v1.7.4

v1.7.4 — 2026-08-02

新增

• Web Push 发送失败提示：Agent 发送推送失败时，设置 → 通知 → Web Push 下方显示失败原因，不再只是「开关是开的但收不到推送」。连不上推送服务与推送密钥不匹配各有对应说明；未识别的错误原样显示原文。

修复

• 发送失败原因丢失：推送失败时只记录成功与否，具体原因（HTTP 状态码与服务端返回内容）被丢弃 → 现在完整保留并写入配置，Agent 重启后仍可查看。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

v1.7.4 — 2026-08-02

Added

• Web Push delivery failures are now reported: when the agent fails to send a push, the reason appears under Settings → Notifications → Web Push instead of leaving the toggle silently on with nothing arriving. Unreachable push service and mismatched push keys each get their own explanation; unrecognized errors show their original text.

Fixed

• Send failure reasons were discarded: a failed push only recorded success or failure, dropping the HTTP status and server response → both are now preserved and persisted, so the reason survives an agent restart.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

PocketShell v1.7.3

v1.7.3 — 2026-08-02

修复

• 更新后 Web Push 静默失效：每次版本更新后，设置里的 Web Push 开关仍显示「开」却收不到任何推送，必须手动关一次再打开 → 现在每次连上 Agent 时自动校对并补回订阅。仅对本机通知权限已授予的设备生效，不会替从未开启过推送的设备订阅，也不会弹出权限框。
• 关闭推送残留订阅：关闭 Web Push 时只通知 Agent 停止发送，浏览器侧订阅仍然存活 → 现在一并退订。

已知问题

• 订阅自愈需经历完整的「更新 → 重连」流程才会触发，尚未在真机上验证。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

v1.7.3 — 2026-08-02

Fixed

• Web Push silently stopped working after an update: the Web Push toggle in Settings still showed "on" after every version update while no notification arrived, requiring a manual off/on cycle → the subscription is now checked and restored automatically on each connection to the agent. This only applies to devices that already granted notification permission; it never subscribes a device that has not opted in, and never raises a permission prompt.
• Stale subscription after turning push off: turning Web Push off only told the agent to stop sending, leaving the browser subscription alive → it is now unsubscribed as well.

Known issues

• The self-heal path requires a full update-then-reconnect cycle to trigger and has not yet been verified on a physical device.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

PocketShell v1.7.2

v1.7.2 — 2026-08-02

修复

• Web Push 开启失败看不懂：设置里开启 Web Push 失败时，原先直接显示浏览器抛的英文原文 Registration failed - push service error → 现在给出可读原因，指明这不是配置问题，并列防火墙/代理拦截、浏览器不带推送后端（如 Brave）、FCM 需 VPN 的地区三种可能；Service Worker 未就绪单独提示并指向「清除缓存并重载」。未识别的错误仍原样显示原文，不吞错。

已知问题

• Web Push 依赖浏览器自带的推送服务（Chrome 走 Google FCM）。连不上该服务时无法订阅，这是浏览器与网络层面的限制，Agent 侧无法绕过；此时可改用「出站 Webhook」（企业微信/飞书/Slack/Discord）接收通知。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

v1.7.2 — 2026-08-02

Fixed

• Unreadable Web Push failure: enabling Web Push in Settings used to surface the browser's raw Registration failed - push service error → it now explains the cause, states that this is not a misconfiguration, and lists the three likely reasons (a firewall or proxy blocking it, a browser without a push backend such as Brave, or a region where FCM needs a VPN); a not-ready service worker gets its own message pointing at "Clear cache and reload". Unrecognized errors still show their original text verbatim.

Known issues

• Web Push depends on the browser's own push service (Chrome uses Google FCM). If that service is unreachable, subscription is impossible — a browser/network limitation the agent cannot work around; use an outbound Webhook (WeCom / Feishu / Slack / Discord) instead.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

PocketShell v1.7.1

PocketShell v1.7.1

修复

• 多开窗口后终端花屏：同时开着多个终端标签页时，切换或从后台切回后部分标签页文字错乱、缺字或整屏空白，关掉单个标签页和重开 App 都无效，只有关掉全部标签页才恢复 → 现在只有当前可见的标签页占用 GPU 渲染上下文，切走即释放，不再触发浏览器的上下文数量上限。
• 看不见输入光标：手机上终端里的光标是一个一像素宽的空心细框，几乎不可见，只能靠直觉移动光标 → 改为实心块，且不再需要先聚焦才显示。
• 字形错位：多个终端共用同一份字形图集时，图集内部合并后部分字符可能画到错误位置（上游 xterm.js 问题）。

变更

• xterm.js 升级至 6.1.0：包含上述字形错位的上游修复。

已知问题

• 本版依赖 xterm.js 的 beta 版本（@xterm/xterm@6.1.0-beta.292、@xterm/addon-webgl@0.20.0-beta.291）。字形错位的上游修复目前只存在于 beta 线，最近的正式版（addon-webgl@0.19.0）尚未包含。依赖已锁定为精确版本号，不会自动漂移到未经验证的构建；待上游发布含该修复的正式版后会切回正式线。
• 前端资源包体积因此增加约 69 KB（gzip 后）。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

PocketShell v1.7.1

Fixed

• Garbled terminals with several tabs open: with multiple terminal tabs open, switching tabs or returning from the background left some tabs with scrambled, missing or entirely blank text; closing an individual tab or restarting the app did not help, and only closing every tab restored it → only the visible tab now holds a GPU rendering context, released as soon as you switch away, so the browser's context limit is never reached.
• Invisible input cursor: on a phone the terminal cursor was a one-pixel outline, effectively invisible, leaving you to move it by guesswork → it is now a solid block, and no longer requires focus before it appears.
• Misplaced glyphs: when several terminals shared one glyph atlas, some characters could be drawn at the wrong position after the atlas merged internally (an upstream xterm.js issue).

Changed

• xterm.js upgraded to 6.1.0: includes the upstream fix for the misplaced glyphs above.

Known issues

• This release depends on beta builds of xterm.js (@xterm/xterm@6.1.0-beta.292, @xterm/addon-webgl@0.20.0-beta.291). The upstream fix for misplaced glyphs exists only on the beta line; the latest stable release (addon-webgl@0.19.0) does not yet contain it. The versions are pinned exactly, so they cannot drift onto unverified builds, and this will move back to the stable line once upstream ships a release containing the fix.
• Frontend bundle size grows by roughly 69 KB gzipped as a result.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

PocketShell v1.7.0

PocketShell v1.7.0

新增

• 上下文用量显示：跑 AI 时分割条右侧显示当前会话的上下文用量（如 ⊙ 142k/1M · 14%），替换原本的延迟 + 吞吐；没跑 AI 时维持原样。支持 Claude Code、Kimi Code、Codex、opencode 四家。在设置 → 通知 → 上下文用量里开启。
  • 数据来自各 AI CLI 自身的「一轮跑完」钩子（PocketShell 已用它来发通知），因此数字只在每轮结束时更新，AI 正在跑的那一轮显示上一轮的值。
  • Claude Code 的记录文件里没有上下文窗口总量、模型名也被去掉了 [1m] 后缀，因此单独走状态栏接口拿官方数字；已配置自定义状态栏脚本的会被套在外面运行，原有内容照常显示。
• Kimi Code 通知接入：第四个接入的工具，开启后一轮跑完推送到手机，锁屏也能收到。在设置里打开 Kimi 开关，需新建一个会话才生效（已开着的会话读不到新注入的环境变量）。
• 视频预览：文件面板里点开 mp4、webm、mov 直接播放，支持拖动进度条。
• Git 面板刷新按钮：在终端里切了分支后，点分支行右边的 ⟳ 即可更新，不用关掉重开。

变更

• 文件预览改为流式读取：拖进度条需要服务端支持分段传输，整个文件预览的读取方式一并改为流式，打开大图不再把整个文件读进内存。
• 配对省一步：首次配对时若配对串已在剪贴板里，打开配对弹窗会自动填好，只需起个设备名。iOS 上会多弹一次系统的「粘贴」确认（Safari 限制），Android 上一步到位。
• 编辑器自动折行：手机上编辑长行代码不再需要左右滚动。

已知问题

• Codex 和 opencode 的上下文数字未在真机上验证，是照文档实现的。取不到数据时分割条不显示，不会显示错误的数字。若发现数字只涨不降，请提 issue。

升级

应用内点更新徽标，或：

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

装成服务的升级后需重启：sudo systemctl restart pocketshell（macOS 上 launchd 会自动拉起）。

---

PocketShell v1.7.0

Added

• Context usage on the split bar: while an AI is running, the right side of the split bar shows the session's context usage (e.g. ⊙ 142k/1M · 14%) in place of latency + throughput; without an AI running it is unchanged. Supports Claude Code, Kimi Code, Codex and opencode. Enable it under Settings → Notifications → Context usage.
  • The data comes from each AI CLI's own end-of-turn hook (the same one PocketShell already uses for notifications), so the number updates only when a turn ends — during a running turn it shows the previous turn's value.
  • Claude Code's transcript carries no context-window total and strips the [1m] suffix from the model name, so it reads the official figure from the status line interface instead. If you already have a custom status line script, it is wrapped rather than replaced, and your own output still displays.
• Kimi Code notifications: the fourth supported tool. Once enabled, a finished turn pushes to your phone, including on the lock screen. Turn on the Kimi switch in settings; you need to start a new session for it to take effect, as an already-running session won't pick up the newly injected environment variables.
• Video preview: mp4, webm and mov files play directly in the file panel, with a working seek bar.
• Git panel refresh: after switching branches in the terminal, tap ⟳ next to the branch row to update without closing and reopening the panel.

Changed

• File preview reads streamed: seeking requires server-side range support, and the whole file-preview read path moved to streaming, so opening a large image no longer reads the entire file into memory.
• One less step when pairing: on a first pairing, if the pairing string is already on your clipboard, the dialog pre-fills it and you only need to name the device. iOS shows an extra system paste confirmation (a Safari restriction); Android needs no extra tap.
• The editor wraps long lines: editing long lines of code on a phone no longer requires horizontal scrolling.

Known issues

• The context figures for Codex and opencode are not verified on real devices — they were implemented from those tools' documentation. When no data can be read the split bar shows nothing rather than a wrong number. If you see a figure that only ever grows, please open an issue.

Upgrade

Tap the update badge in the app, or:

curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh

If installed as a service, restart after upgrading: sudo systemctl restart pocketshell (launchd restarts it automatically on macOS).

PocketShell v1.6.1

PocketShell v1.6.1

修复

• Linux 上应用内更新失败：v1.6.0 的 install 子命令把二进制装在 root 拥有的 /usr/local/bin，而服务以你自己的用户身份运行。更新时需在二进制旁写临时文件再原子替换，要求的是目录写权限，因此失败并报 EACCES: permission denied, copyfile '…' -> '/usr/local/bin/.pocketshell.new'。本版把二进制改放 /opt/pocketshell/（归服务用户所有），/usr/local/bin/pocketshell-agent 变为指向它的符号链接，命令仍在全局 PATH 上，sudo pocketshell-agent uninstall 照常可用。macOS 不受此问题影响（LaunchAgent 装在用户目录下，本就有写权限）。

升级

已安装 v1.6.0 的，在服务器上重跑一次安装命令即可迁移，密钥目录不受影响、已配对的手机不掉线：

sudo pocketshell-agent install --advertise wss://your.domain --name 我的服务器

---

PocketShell v1.6.1

Fixed

• In-app updates failed on Linux: the install subcommand shipped in v1.6.0 put the binary in root-owned /usr/local/bin while running the service as your own user. An update writes a temporary file next to the binary and renames it into place, so it needs write access to the directory — hence EACCES: permission denied, copyfile '…' -> '/usr/local/bin/.pocketshell.new'. The binary now lives in /opt/pocketshell/, owned by the service user, and /usr/local/bin/pocketshell-agent is a symlink pointing at it, so the command stays on the global PATH and sudo pocketshell-agent uninstall keeps working. macOS was never affected — a LaunchAgent installs under your home directory, which you can already write.

Upgrade

If you already installed v1.6.0, re-run the install command on your server to migrate. Your key directory is untouched and paired phones stay paired:

sudo pocketshell-agent install --advertise wss://your.domain --name my-server

PocketShell v1.6.0

PocketShell v1.6.0

新增

• install 子命令：一条命令装成开机自启的服务

  # 先把二进制装到位
  curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh
  
  # 再做成开机自启的服务
  sudo pocketshell-agent install --advertise wss://your.domain --name 我的服务器

  该命令写好 systemd 服务配置 → 注册开机自启 → 立刻启动 → 首次安装时直接打印配对串。macOS 写的是 launchd 配置且不要加 sudo（LaunchAgent 属于用户域，加 sudo 会装进 root 的会话里，命令会直接拦下并说明）。

  • 服务身份：默认取 sudo 的发起者而非 root，手机连上后拿到的是你自己的 shell（dotfiles、Claude/Codex 配置、SSH 密钥都在）。用 --user 可指定其他用户。
  • Restart=always / KeepAlive：崩溃自动拉起，也是应用内 OTA 更新能重启成功的前提。
  • macOS PATH：安装时探测本机 tmux 的真实位置写进配置，不假设 Apple Silicon + Homebrew（launchd 环境极简，找不到 tmux 会启动即退出）。
  • 改参数直接重跑：原配置先备份，密钥目录不动，已配对的手机不掉线。
  • 不修改 Caddy/Nginx 配置、不动 DNS、不代装 tmux（缺失时打印对应发行版的安装命令并退出）。

• uninstall 子命令：停服务、删配置，保留密钥目录（内含密钥与已配对设备；确需清除时命令会告知路径）。

• 一行安装脚本：校验 SHA256，不匹配立即中止；VERSION=1.5.0 curl -fsSL … | sh 可装指定版本。

修复

• pair 子命令在服务启动 5 分钟内失效：进程启动时铸的配对码尚未过期，会盖住新生成的码，报错为 bad_code，看起来像配对串抄错。采纳规则改为磁盘上更新的码抢占仍存活的启动码，任何时刻跑 pair 都即刻生效。

---

PocketShell v1.6.0

Added

• install subcommand: set up a boot-start service in one command

  # get the binary in place
  curl -fsSL https://raw.githubusercontent.com/Big-Pony/pocketshell/main/install.sh | sh
  
  # turn it into a service that starts on boot
  sudo pocketshell-agent install --advertise wss://your.domain --name my-server

  It writes the systemd unit → registers it to start at boot → starts it now → and prints the pairing string on a first install. macOS writes a launchd config instead, and there you should not use sudo — a LaunchAgent belongs to your user domain, and the command stops and tells you rather than installing into root's session.

  • Which user the service runs as: whoever invoked sudo, not root, so the shell your phone gets is yours (dotfiles, Claude/Codex config, SSH keys). Use --user to pick someone else.
  • Restart=always / KeepAlive: it comes back after a crash, and it's what lets in-app OTA updates restart cleanly into the new binary.
  • PATH on macOS: the installer probes where tmux actually lives instead of assuming Apple Silicon plus Homebrew (launchd's environment is bare, and an agent that can't find tmux exits at startup).
  • Changing a setting: just run it again — the old config is backed up first, your key directory is untouched, and paired phones stay paired.
  • It won't touch your Caddy/Nginx config, your DNS, or your package manager (missing tmux gets you the right install command for your distro and a clean exit).

• uninstall subcommand: stops the service and deletes the config while keeping your key directory (it holds your keys and paired devices; if you really want it gone the command tells you the path).

• One-line installer: verifies SHA256 and aborts on a mismatch. Pin a version with VERSION=1.5.0 curl -fsSL … | sh.

Fixed

• pair did nothing for the first five minutes after the service started: the code minted at boot hadn't expired yet and quietly took precedence over the one you'd just generated, returning bad_code, which reads like you mistyped the pairing string. The adoption rule now prefers whichever code was minted more recently, so pair takes effect immediately no matter when you run it.

PocketShell v1.5.1

PocketShell v1.5.1

修复

• 老 CPU 的 Linux 服务器启动即 Illegal instruction：linux-x64 二进制此前用到 AVX2 指令集，在 2013 年前后的 Intel CPU（Ivy Bridge 及更早，如 Xeon E5 v1/v2）上会立即崩溃，而报错完全看不出是指令集问题。本版改用 Bun 的 baseline 目标编译，只要求 SSE4.2，新老 CPU 都能跑。文件名不变（仍是 pocketshell-agent-linux-x64），自动更新照常工作。
  • 实测：Xeon E5-2680 v2（Ivy Bridge，有 AVX 无 AVX2）上 v1.5.0 崩溃，本版正常启动并 serve。

升级

撞上过该崩溃的重新下载 linux-x64 即可；已经跑起来的机器不受影响，正常更新即可。

---

PocketShell v1.5.1

Fixed

• Illegal instruction on Linux servers with older CPUs: the linux-x64 binary emitted AVX2 instructions and crashed immediately on Intel CPUs from around 2013 and earlier (Ivy Bridge and older, e.g. Xeon E5 v1/v2), with an error that said nothing about instruction sets. This release compiles linux-x64 with Bun's baseline target, which only requires SSE4.2 and runs on both old and new CPUs. The filename is unchanged (pocketshell-agent-linux-x64), so auto-update keeps working with no action needed.
  • Verified on a Xeon E5-2680 v2 (Ivy Bridge, AVX but no AVX2): v1.5.0 crashes, this build starts and serves normally.

Upgrade

If you hit the crash, re-download linux-x64. Machines already running are unaffected — update as usual.