tembo/voxl

项目介绍

voxl 是一个 Rust 服务端：抓取 Linux X11 显示（含 Xvfb）、Mac 屏幕或 Windows 桌面，用 x264 在 CPU 上编码成 H.264，经单个 WebSocket 发给一个小型网页客户端，由浏览器用 WebCodecs 解码。除视频外，它还承载输入、剪贴板、桌面音频、浏览器麦克风通道、文件和文件夹传输，并能让桌面分辨率跟随查看者窗口变化。

它的目标场景是无头服务器、虚拟机和沙箱——CI 机器、computer-use 代理以及「软件工厂」——这类环境不希望在看的一端装任何客户端。进程自己提供页面，启动时会打印一个带登录 token 的链接。

快速使用

Linux 上构建需要 Rust、pkg-config、clang、x264、libyuv、libopus、libpulse 和 esbuild；nix-shell 会全部提供。在仓库目录中：

nix-shell
cargo build --release
DISPLAY=:1 ./target/release/voxl --port=6901
# 输出：open http://localhost:6901/?token=4f1c… to sign in

也可以安装已发布的 crate（包名为 voxl-server，二进制名为 voxl，见 crates.io）：

cargo install voxl-server
DISPLAY=:1 voxl

打开它打印的链接，桌面就出现在浏览器里。Xvfb 桌面启动时加 -shmem 可启用零拷贝抓屏；URL 加 ?stats 会显示 FPS 叠加层。macOS 和 Windows 有各自的构建步骤，见 macOS 与 Windows 两节；这两个平台上 voxl 串流的是本机自己的屏幕。

要接入自动化，截图和录像都是普通 HTTP 调用（代理接口示例）：

curl -u ":$VOXL_PASSWORD" -o shot.png localhost:6901/screenshot
curl -u ":$VOXL_PASSWORD" -o clip.mp4 "localhost:6901/record?seconds=10"

/wait 会阻塞到屏幕稳定或发生变化，脚本因此不必固定 sleep。

使用约束

• 浏览器与 HTTPS： 观看端需要支持 WebCodecs 的浏览器，而浏览器只在 HTTPS 页面或 localhost 上开放它。远程观看要放在 TLS 代理后面（Caddy、Cloudflare Tunnel、tailscale serve）并配置 --allowed-hosts，或通过 SSH 端口转发。支持 Chrome/Edge 94+、桌面 Firefox 130+、Safari 16.4+ 以及 iOS/iPadOS 浏览器；Firefox for Android 不支持。
• 登录： 默认要求密码，取自 --basic-auth-password 或 VOXL_PASSWORD，否则启动时随机生成并写进打印的链接。放在自行认证的代理后面时，可用 --enable-basic-auth=false 关闭。
• Host 与 Origin 限制： 服务默认只应答 IP 地址和 localhost，也只接受自己页面的连接；需要时用 --allowed-hosts 和 --allowed-origins 放行。curl 等非浏览器客户端不带 Origin，可正常连接。
• 平台： Linux 只支持 X11，尚不支持 Wayland。Windows 需要 Windows 10 及以上，且应运行在用户会话而非服务中，否则看不到锁屏和 UAC 提示。macOS 需要屏幕录制与辅助功能权限，麦克风还需安装回环音频设备。
• 文件与权限： Files 面板只能访问 --files-root（默认 $HOME）；--read-only 会禁止输入、剪贴板写入、麦克风、上传和调整分辨率。
• 编码： H.264 在 CPU 上编码；繁忙的 2560x1600 桌面连同 X 服务器约占用 1.3–1.7 个核，目前没有硬件编码。录像直接以 MP4 保存，不重新编码、不额外占 CPU，但不含光标，分辨率变化会结束录像。
• 传输： 走 TCP 上的 WebSocket，部署简单，但在丢包链路上会卡住，此时 WebRTC 可以跳过丢失部分。
• 许可证： voxl 自身代码是 MIT，但链接了 GPL-2.0 的 x264，因此分发出去的二进制按 GPL 处理。

性能基准

在一台无 GPU 的 16 vCPU AMD EPYC 虚拟机、2560x1600 Xvfb 桌面上，同一批负载下 voxl 平均 60 FPS，延迟中位数 12–99 ms；noVNC 平均不到 8 FPS。README 用 FPS 和 p50/p99 延迟对比了 selkies、KasmVNC、Neko、Sunshine 和 Daytona，并说明 Sunshine 面向 GPU 抓屏编码，这里的数字反映的是无 GPU 时的回退路径，而非其目标硬件。复现环境在 bench/ 目录。

HotRepo 点评

2026-11-05 的 Rust 日榜记录中，voxl 位列第 5，当日新增 285 Star，总数 1074。目前只有这一条快照，只能说明当天关注度高，不足以判断趋势；该仓库没有全部语言日榜的记录。

相比基准表，README 更有价值的信息是用单个 WebSocket 代替 WebRTC：流可以穿过反向代理、隧道和沙箱预览 URL，不需要 TURN 服务器，这正好贴合它瞄准的无头虚拟机和代理场景。面向代理的 /screenshot、/record、/wait 接口，以及 --read-only 和 files-root 控制，让这一定位落到了具体功能上，而不只是口号。代价也写得很直接：TCP 在丢包链路上会卡。读者如果拿它和 Sunshine 或 RustDesk 比较，要注意它只支持 Linux X11 且用 CPU 编码，不是面向 GPU 游戏串流的替代品。