# BitBang CLI
[](https://github.com/richlegrand/bitbang-cli/actions/workflows/tests.yml)
`bitbang` 是一个单一静态二进制文件的远程访问多功能工具。从任意浏览器即可：对远程机器进行交互式 shell 和文件浏览器访问。你还可以访问该机器所在网络上的 Web 应用。除浏览器之外，它还支持 TCP 端口转发、文件复制和终端共享。它无需账户或配置——开箱即用。
在你想访问的机器上：
```
curl -sSfL bitba.ng/install | sh
bitbang serve
```
`serve` 会打印一个 URL。在任意浏览器中打开它，你就会得到一个终端、一个文件浏览器，以及一个通往该机器网络的代理——或者从另一个终端使用 `bitbang connect <url>` 连接到同一台机器，这会增加端口转发（`-L`）和文件复制（`bitbang cp`）功能。连接是端到端加密且点对点的；`bitba.ng` 服务器负责介绍两端认识，然后便退到一旁。
`bitbang` 是一个单一的静态 Go 二进制文件。它是 [BitBang 项目](https://github.com/richlegrand/bitbang)的一部分；这份[白皮书](https://github.com/richlegrand/bitbang/blob/main/whitepaper.md)深入介绍了其设计。
## 对比
| | ngrok | Tailscale | `bitbang` |
| ------------------------------ | ---------------------- | ------------------------------ | ------------------- |
| 首次使用前的设置 | 账户 + authtoken | 账户 + 在每台设备上登录 | **运行一条命令** |
| 要共享内容，你需要运行 | 一个 Web 服务器，外加 ngrok | 在两端机器上运行他们的客户端 | **`bitbang serve`** |
| 远端浏览器获得的内容 | 你原本就在运行的 Web 服务器 | 什么都没有——它需要他们的客户端 | **一个终端、一个文件浏览器，以及远程网络上的 Web 应用** |
| 数据路径 | 他们的服务器 | P2P（中继回退） | **P2P（中继回退）** |
| 端到端加密 | 默认不加密 | 是 | **是** |
## 快捷配方
**访问家中的服务**
- [从任何地方挂载你的家庭 NAS（SMB）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#mount-your-home-nas-from-anywhere-smb)
- [从任何地方观看你的媒体库（Jellyfin）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-your-media-library-from-anywhere-jellyfin)
- [从任何地方使用你自己的 LLM（Ollama、Open WebUI）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#use-your-own-llm-from-anywhere-ollama-open-webui)
- [查看你的安防摄像头（Frigate）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-security-cameras-frigate)
- [在不暴露的情况下访问你的家庭自动化系统（Home Assistant）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-your-home-automation-without-exposing-it-home-assistant)
- [打印到你的家用打印机（IPP、CUPS）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#print-to-your-home-printer-ipp-cups)
**进入某台机器**
- [在 NAT 后面的机器上获取 shell](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [从你的手机获取 shell](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-from-your-phone)
- [远程桌面连接到 Windows 机器（RDP）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#remote-desktop-into-a-windows-machine-rdp)
- [访问 Linux 或 Mac 桌面（VNC）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-linux-or-mac-desktop-vnc)
- [SSH 连接到没有开放端口的机器（OpenSSH）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#ssh-to-a-machine-with-no-open-port-openssh)
- [设置无头 Raspberry Pi](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#set-up-a-headless-raspberry-pi)
**与他人共享**
共享只需给某人一个唯一的 URL 或二维码，即可让他们获得访问权限。权限可以定制，并设置为在几分钟、几小时等时间后过期。
- [无需上传即可共享文件](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#share-files-without-uploading-them-anywhere)
- [向他人展示你的项目](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-your-project)
- [向他人展示你卡住的错误](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-the-error-you-are-stuck-on)
- [授予他人会过期的访问权限](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#give-someone-access-that-expires)
- [从手机查看你的 agent 会话（Claude Code、tmux）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-agent-session-from-your-phone-claude-code-tmux)
- [修复他人的路由器](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#fix-someone-elses-router)
**开发与设备**
- [从你的开发机访问数据库（Postgres、MySQL）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-database-from-your-dev-machine-postgres-mysql)
- [同步无法互相发现的设备（Syncthing）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#sync-devices-that-cannot-find-each-other-syncthing)
- [从浏览器观看机器人（ROS、Foxglove）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-a-robot-from-a-browser-ros-foxglove)
**技巧**
- [转发监听器会暴露什么](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#what-a-forwarding-listener-exposes)
- [让局域网中的其他机器使用转发](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#let-other-machines-on-your-lan-use-a-forward)
- [已知不可用的情况](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#known-not-to-work)
## 使用 `bitbang`
每个连接都有两端：一个**监听器**（`bitbang serve`，运行在被访问的机器上）和一个**连接器**（浏览器，或执行访问的机器上的 `bitbang` CLI）。一个监听器 URL 可同时服务这两种连接器。
### 监听器：`bitbang serve`
```
bitbang serve # everything: shell + proxy + files + forward
bitbang serve shell # just a terminal
bitbang serve files ~/share # just a directory (-files-upload to allow uploads)
bitbang serve proxy localhost:8080 # just one web app, straight at the URL
bitbang serve proxy a.lan:80,b.lan:80 # ...or several, chosen in the browser
bitbang serve forward 127.0.0.1:22 # just TCP, for `connect -L`
bitbang serve shell files ~/share proxy nas.lan:8096 # any combination
```
每个都会打印一个二维码、URL 和一个配对码。模式决定了监听器能做什么：`serve shell` 没有可授予的转发权限，而仅转发的监听器永远不会启动 shell，因此没有可提升的权限。
有一个值得了解的默认行为：**转发和代理可以访问监听器能到达的任何 host:port**，而不仅仅是你心中所想的那个，因此为数据库分发的链接也能访问该网络中的其他部分。以该词命名目标可以缩小范围——`forward db.internal:5432` 只能访问该目标，不能访问其他任何内容。
### 共享正在运行的会话：`bitbang share`
`serve shell` 会启动一个新的 shell。`share` 则发布一个已经在运行的 tmux 会话：
```
bitbang share # publish the current tmux session
bitbang share --read-only # publish without a control URL
bitbang share status|stop|rotate
```
该命令在发布后返回，因此 `Ctrl-Z`、`bitbang share`、`fg` 可用于已在进行的任务。托管需要 Unix 或 WSL 上的 tmux 3.2+。原生 Windows 客户端可以打开 URL，但无法托管共享。
默认情况下，该命令会打印两个 bearer URL：
- **Control URL** 可以以与本地键盘相同的权限进行输入。一次只能连接一个控制器。
- **View URL** 是仅观看模式。输入会在到达 tmux 之前被丢弃，最多可同时连接 `--max-viewers` 个观看者（默认 16）。
`--read-only` 会完全省略控制凭据。观看者和控制器限制会在每个连接的整个生命周期内保持，甚至在它打开 shell 之前也是如此。
默认情况下，共享会一直运行直到停止；`--ttl` 可设置生存时间（例如 `--ttl 1h`）。共享 URL 是临时的，绝不会保存到 `devices.json`。`share stop`、TTL 到期或移除源会话会断开远程对等端，但不会停止源会话。
重新运行 `bitbang share` 会重新打印正在运行的共享的 URL。如果你传入的某个标志与当前运行状态不一致（比如对一个已有控制 URL 的共享使用 `--read-only`），它会明确说明，而不是返回旧 URL；`bitbang share rotate` 会用使用新标志的共享替换当前共享。
后台工作进程运行在一个分离的 `_bbshare_*` tmux 管理会话中，因此没有守护进程或 PID 文件需要管理。
共享不会更改任何 tmux 选项。在 tmux 默认的 `window-size latest` 下，窗口会跟随活动的读写客户端；单独的观看者仍然会提供唯一可用的尺寸。如果 `window-size` 已被覆盖，`share` 会报告这一点，但不会更改用户的配置。
### 分发受限访问权限：`bitbang link`
一个监听器、一个 URL，以及任意数量的**访问链接**。每个链接都是同一 URL 上的独立代码，授予监听器所提供权限的子集，并可选地在固定时间失效：
```
bitbang link edit # add entries in $EDITOR
bitbang link ls # what you have handed out
bitbang link rm <label> # revoke one
bitbang link qr <label> # its URL and QR code
```
`~/.bitbang/bitbang/links.json` 中的每个条目都是一行 JSON。无需编写代码即可写入一条，在其控制台重新加载监听器，它便会生成一条：
```json
[
{"label": "ana", "grant": "files", "expires": "2026-09-01T00:00:00Z"},
{"label": "ben", "grant": "files /srv/photos"},
{"label": "dev", "grant": "shell forward 127.0.0.1:5432"}
]
```
```
0) owner files forward proxy shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#_vtQ0JCPe7s
1) ana files expires in 6d
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#T-Ty_HhvLfY
2) ben files /srv/photos
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#L6La8OzBO74
3) dev forward 127.0.0.1:5432 shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#8kmI3LYzB7E
```
`owner` 是身份自身的代码，授予监听器所提供的一切；请改为发送其他身份之一。控制台接受标签或旁边的编号，因此 `rm 2` 和 `rm ben` 效果相同。
`grant` 以 `serve` 接受的措辞书写，并且它只能收窄监听器已经提供的内容。这意味着链接并不局限于挑选能力：它可以指定共享文件夹的子目录、转发目标的子集，或 `shell` 的单条命令。省略 `grant`，链接就授予监听器所做的一切。如果请求超出监听器的范围，控制台会以与 `serve` 相同的消息拒绝。
标签才是标识链接的依据，而非其条款，因此两个人可以持有具有相同授权和到期时间的链接，而你仍然可以撤销其中一个而不影响另一个。
撤销和到期会作用于已经打开的会话：连接会关闭，持有者会被告知原因，而不是悄无声息。过期的代码会被作废而非暂停——续期条目会生成一个新的，因此你已经发送的 URL 会保持失效。
### BitBang 将文件保存在何处
BitBang 存储的关于自身的一切都位于一个目录中：固定你 URL 的身份密钥对、链接表、`connect` 和 `cp` 读取的已保存设备表，以及共享状态。默认情况下是 `~/.bitbang`。
服务通常无法使用 `~`。`-home` 设置该目录，而 `BITBANG_HOME` 也能做到这一点，无需在每条命令上重复该标志：
```
bitbang serve shell -home /var/lib/bitbang
BITBANG_HOME=/var/lib/bitbang bitbang link ls
```
这个标志出现在每条命令上，而不只是 `serve`，因为该目录并非 serve 专属——在 `bitbang link` 上忘记一次，就会编辑到另一张表。
完整顺序如下，先匹配者胜出：
| 设置 | 使用的目录 |
|---|---|
| `-home <dir>` | 正是该目录 |
| `$BITBANG_HOME` | 正是该目录 |
| `$STATE_DIRECTORY` | 正是该目录——systemd 从 `StateDirectory=` 设置它，因此 unit 无需其他配置 |
| `$XDG_STATE_HOME` | `$XDG_STATE_HOME/bitbang` |
| `$HOME` | `$HOME/.bitbang` |
| 以上均无 | 无：BitBang 停止并说明原因 |
前三项直接指定目录本身；后两项指定其挂载的父目录。
最后一行在服务用户没有 home 目录的机器上很重要。早期版本会回退到工作目录，因此未设置 `HOME` 启动的监听器会把密钥对写到它恰好启动的位置——对于 init 脚本就是 `/`。现在它会拒绝，而不是把私钥放到没人选择的位置。
监听器在启动时指明目录，因此你永远不必推断这些规则中哪一条胜出：
```
Home: /home/you/.bitbang
Home: /var/lib/bitbang (STATE_DIRECTORY)
```
因此，systemd 单元完全不需要针对此功能进行任何 BitBang 专属配置：
```ini
[Service]
StateDirectory=bitbang
ExecStart=/usr/local/bin/bitbang serve shell
```
### 使用 6 位配对码进行配对
当你无法粘贴 URL 或扫描二维码时——比如你正在通电话，或者彼此在喊话能听到的范围内——`bitbang serve` 还会打印一个简短的**配对码**。对方打开 `bitba.ng/<code>`（或运行 `bitbang connect <code>`），其屏幕上会显示另一个 6 位数字，然后对方把*那个*数字读给你听。你输入该数字以批准连接。中间人无法让这两个数字匹配，并且配对会保存设备连接凭据以供下次使用，例如 `bitbang connect nas1`。如果你了解 [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole)，其形式类似——一个口头说出的配对码，安全地介绍两台机器相识。
### 自带 TURN 服务器
大多数连接会直接点对点进行。当两端都位于无法进行 NAT 打洞的 NAT 之后时，流量需要中继，默认情况下使用的是我们的中继。`-ice-servers` 可将监听器指向你自己的中继：
```
bitbang serve -ice-servers ~/turn.json
```
监听器在注册时把配置交给信令服务器，服务器再把它交给任何连接的一方——因此两端都使用你的中继，而我们的中继从不参与。任何 coturn，或像 Cloudflare、Twilio 这样的托管服务商，都可以使用。
该文件为 JSON 格式，采用你的服务商提供给你的以下三种形式之一：
```json
[{"urls": ["turn:turn.example.net:3478"], "username": "user", "credential": "pass"}]
```
```json
{"ice_servers": [{"urls": "stun:stun.example.net:3478"}]}
```
```json
{"iceServers": [{"urls": ["turn:turn.example.net:3478"], "username": "u", "credential": "p"}]}
```
`urls` 接受字符串或列表；`username` 和 `credential` 用于 TURN，在仅使用 STUN 的条目中可以省略。路径可以是绝对路径、相对路径或以 `~` 为根。无法解析的文件会在启动时停止监听器，而不是悄悄回退。
如果会话在未被要求的情况下最终被中继，`bitbang connect` 会明确告知，而不是让你疑惑为什么感觉慢。监听器无论如何都会记录（`via RELAY`），而在诊断路径时，`-relay` / `-norelay` 会强制将问题导向某一方。
值得一提的是：这关乎谁承载字节，而不是谁能读取它们。中继只能看到 DTLS 密文，包括我们的。当你需要比我们能提供的更多 TURN 时，请运行你自己的（我们目前限制时间）。
### 从浏览器连接
打开 URL。根据所提供的内容，你会得到：
- **Shell** -- 页面中的完整终端（颜色、调整大小、复制/粘贴）。
- **Files** -- 浏览、预览、下载和上传。
- **Proxy** -- 输入局域网地址（`nas.local`、`192.168.1.10:8080`、`localhost:3000/admin`），然后像在本地一样使用应用。登录、Cookie、上传和流媒体都能正常工作。
<!-- TODO: per-feature demos -->
<!-- Remote shell in a browser tab -->
<!-- Streaming Jellyfin through the proxy -->
### 从 CLI 连接
```
bitbang connect <url> # interactive shell
bitbang connect <url> -- tail -f /var/log/syslog # one-shot command
bitbang connect <url> -L 15432:db.internal:5432 # local TCP forwarding
bitbang connect <url> -L 14450:nas.local:445 -L 15900:[fd00::20]:5900
bitbang cp <url>:/var/log/app.log ./app.log # copy files, scp-style
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin # stdin/stdout work too
```
`-L` 仅转发 **TCP**，与 `ssh -L` 类似。除非传入 `-g`，否则 `-L` 绑定 `127.0.0.1`；`-g` 会使转发的端口可从你的本地网络访问——任何能访问该端口的人都能获得该隧道所能访问的内容，且前面没有 BitBang 凭据保护。
监听端需要 `bitbang serve forward` 或 `bitbang serve`。默认情况下，`forward` 链接可到达**监听端能访问的任意 host:port**，而不仅仅是你原本设想的那个，因此为某个数据库分发的链接也能到达该网络中的其他部分。通过指定其可到达的范围来缩小它：
```
bitbang serve forward db.internal:5432 # this link reaches one service
```
每次成功连接或配对都会保存到 `~/.bitbang/devices.json`，因此此后只需使用简短名称即可：`bitbang connect nas1`。
## 平台支持
每个平台一个二进制文件，无运行时依赖。除下面列出的两行外，所有功能在所有平台上均可使用。
| | Linux | macOS | Windows |
| ---------------------------------------- | :---: | :---: | :-----: |
| Shell、文件、代理（`bitbang serve`） | 是 | 是 | 是 |
| TCP 转发（`-L`） | 是 | 是 | 是 |
| 访问链接——授予、过期、撤销 | 是 | 是 | 是 |
| 自带 TURN | 是 | 是 | 是 |
| 使用 6 位代码配对 | 是 | 是 | 是 |
| 监听器控制台（Enter） | 是 | 是 | 是 |
| `bitbang connect`、`bitbang cp` | 是 | 是 | 是 |
| 查看共享会话 | 是 | 是 | 是 |
| **托管共享**（`bitbang share`） | 是 | 是 | 否 * |
| **连接期间调整终端大小** | 是 | 是 | 否 ** |
\* `bitbang share` 会发布一个 tmux 会话，因此托管共享需要 tmux——Linux、macOS 或 WSL。原生 Windows 仍可通过 `bitbang connect` 打开共享 URL。
\*\* Windows 连接端不会察觉其终端被调整大小，因此远程 shell 会保持启动时的尺寸，直到你重新连接。Unix 通过 `SIGWINCH` 获得此能力，而 Windows 没有等价机制。
## 安全性
- **自认证身份。** 首次运行时，`bitbang` 会在 `~/.bitbang/<program>/` 下生成 RSA 密钥对；设备 UID 由公钥派生，因此冒充设备意味着要找到其 UID 的第二个原像。
- **密钥永远不会接触服务器。** 访问代码位于 URL 片段（`#…`）中，浏览器从不发送该片段——`bitba.ng` 在代理连接时始终看不到授权该连接的凭据。
- **端到端加密。** 所有流量都通过 WebRTC 的 DTLS 传输。信令服务器只能看到公钥、派生出的 UID 和连接元数据——永远看不到你的数据。如果需要 TURN 中继，它也只能看到密文。
- **经过验证的配对。** 代码配对中朗读的数字是一个短认证字符串（SAS），由两端根据协商出的 DTLS 指纹和两个已承诺的 nonce 独立计算得出——中间人攻击者的指纹必然不同，因此无法让两个数字匹配。
- **URL 是一种持有者凭据。** 任何拥有它的人都能获得你所选择提供的任何内容——如果你运行了 `serve shell`，那就是一个 shell。请相应地分享它。
- **可选 PIN**（`--pin`）用于永久或无头设置，**一次性模式**（`-ephemeral`）用于每次运行都使用全新身份。
- **服务器仍然能看到什么。** 并非什么都没有。它代理双方的引荐，因此会观察到两端的 IP 地址、它们连接的时间以及交换的数据量。端到端加密使其无法接触你的数据，但无法使其脱离周围的元数据——*最小信任*比*无信任*是更准确的描述。
- **浏览器信任它加载的页面。** 浏览器客户端是由信令服务器提供的 JavaScript，因此打开 URL 意味着信任该服务器提供诚实的代码。`bitbang connect` 没有这种依赖：它是你安装并校验过的二进制文件。如果这种区别对你很重要，请使用 CLI 连接。
两端如何相互认证，从而使信令服务器无法插入连接，详见此处：[*Trustless Signaling: Authentication Without a Central Authority*](https://github.com/richlegrand/bitbang/blob/main/trustless-signaling.md)。
## 为什么？
- **无需开放或配置任何东西。** 可在 NAT、CGNAT 或受限网络后方工作——无需更改路由器、无需 VPN、无需隧道守护进程。
- **连接端无需安装任何东西。** 有浏览器就足够。当你需要脚本、管道和文件复制时，可以使用 CLI。
- **设计上即私密。** 流量为 WebRTC/DTLS，点对点。信令服务器永远看不到它；如果无法建立直接路径，TURN 中继仅承载密文。
- **无账户，无遥测。**
### 为什么不直接用 SSH？或者 Tailscale？
简短回答：对于你已经能通过 SSH 登录的机器，或者你自己可以安装的一批设备，继续使用你现有的方案。`bitbang` 适用于远端是一个人而不是一台设备的情况，或者当你无法在你所在的位置安装任何东西时。这两个问题在 **[FAQ](https://github.com/richlegrand/bitbang-cli/blob/main/FAQ.md)** 中有详细解答。
## 安装
```
curl -sSfL bitba.ng/install | sh
```
Linux 和 macOS。检测你的操作系统和架构（Linux 上为 `amd64`、`arm64` 和 `armv7`），从最新的 [GitHub release](https://github.com/richlegrand/bitbang-cli/releases) 下载二进制文件，对照该 release 的 `checksums.txt` 校验其 SHA-256，并安装到 `~/.local/bin/bitbang`。
Windows 构建以 `bitbang-windows-amd64.exe` 和
`bitbang-windows-arm64.exe` 发布。从 Releases 下载相应的二进制文件，
将其重命名为 `bitbang.exe`，并放到你的 `PATH` 中。
**从源码构建：** 参见[下文](#building-from-source)。
**macOS 与 Gatekeeper。** 上述安装一行命令不受影响：`curl` 不会
设置 `com.apple.quarantine` 属性，因此它获取的二进制文件可以正常
运行。如果你改为在浏览器中从 Releases 页面下载 `bitbang-darwin-arm64`，
macOS 会将其隔离并拒绝打开，因为发布版二进制文件未经过公证。用以下任一方式清除：
```
xattr -d com.apple.quarantine ./bitbang-darwin-arm64
```
或者在 Finder 中右键点击该文件并选择“打开”，这会提供一次性的
覆盖选项。或者，从源码构建，这种方式永远不会被隔离。
**Windows 与 SmartScreen。** Windows 上也会发生同样的情况，原因相同。浏览器下载会附加 Mark-of-the-Web 标记，因此首次运行时会显示
*“Windows 已保护你的电脑”*——选择 **更多信息**，然后选择 **仍要运行**。发布
二进制文件未进行代码签名，因此这是预期行为，而非出现问题的迹象。使用 `curl` 或 PowerShell 的
`Invoke-WebRequest` 获取 `.exe` 不会附加该标记，从源码构建也不会。
### 安装选项
固定版本、更改位置，或在运行脚本前先阅读它：
```
curl -sSfL bitba.ng/install | sh -s -- --version 0.5.0
curl -sSfL bitba.ng/install | sh -s -- --prefix /usr/local/bin
curl -sSfL bitba.ng/install -o install.sh && less install.sh && sh install.sh
```
发布标签不带 `v` 前缀（`0.5.0`，而非 `v0.5.0`）。
### 安装 URL 的工作原理
`bitba.ng/install` 是一个重定向，而非托管的脚本。其链路如下：
1. `curl` 访问 `https://bitba.ng/install`，该地址会 302 重定向到本仓库（`main` 分支）中的 [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/main/install.sh)。
2. 该脚本在你的 shell 中运行，检测操作系统和架构，并从 `https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>` 下载二进制资源。
3. 它从同一发布版本中获取 `checksums.txt`，并校验二进制的 SHA-256。
4. 安装到 `~/.local/bin`（可覆盖）。
安装脚本就位于本仓库中，与它所安装的代码相邻——因此你可以将其与二进制一并审查，而规范的 bitba.ng 主机仅持有该短 URL。自托管者可以将自己主机的 `/install` 指向他们发布的任意脚本：信令服务器的 `INSTALL_URL` 环境变量控制重定向目标（为空 → 404）。
## 命令参考
每个子命令和标志都记录在 **[CLI.md](https://github.com/richlegrand/bitbang-cli/blob/main/CLI.md)** 中，`bitbang <command>
--help` 会在终端打印相同的内容。
## 从源码构建
需要 Go 1.25+。纯 Go 实现，静态链接（`CGO_ENABLED=0`）——交叉编译轻而易举，无运行时依赖。
```
go build ./cmd/bitbang/
# cross-compile:
GOOS=linux GOARCH=arm64 go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux GOARCH=arm GOARM=7 go build -o bitbang-armv7 ./cmd/bitbang/
GOOS=windows GOARCH=amd64 go build -o bitbang.exe ./cmd/bitbang/
GOOS=darwin GOARCH=arm64 go build -o bitbang-macos ./cmd/bitbang/
```
从 Windows 命令提示符：
```bat
go build -o bitbang.exe .\cmd\bitbang
go test .\...
run_tests.cmd unit
```
Windows 上支持 Shell 命令、文件共享、代理以及 CLI 客户端。交互式浏览器和 CLI shell 使用 Windows ConPTY，包括终端输入回显、行编辑、VT 输出和调整大小事件。ConPTY 需要 Windows 10 版本 1809 或 Windows Server 2019 或更高版本。
## 示意图
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/47068/d68fcddad62ab84f11a549906a2b5abf2330fb25f39b3c1a1266eac7257a080d.png" alt="bitbang CLI shell 与文件共享" width="760">
<img src="https://assets.kitploit.com/production/public/readmes/47068/55bb6866c22504a6434e3dee8cb998e747cd73cb9d0bfa5e0bc0ede7b90ce262.png" alt="bitbang CLI 代理操作" width="720">
</p>
## 路线图
目前已发布：**shell、文件和代理**，可从浏览器或 CLI 访问，此外还有 **TCP 端口转发**、scp 风格的文件复制、带已保存设备表的**临时配对**、**终端共享**（`bitbang share`），以及**访问链接**（`bitbang link`），后者可缩小 URL 所授予的权限并使其过期。已设计并正在开发中：
- **串口桥接** -- 从本地虚拟端口驱动远程 `/dev/ttyUSB0`（例如通过互联网运行 Arduino IDE）。相关 issue 已在此处开启 [here](https://github.com/richlegrand/bitbang-cli/issues/3)。
- **远程桌面** -- 通过 WebRTC 视频轨道传输屏幕，通过数据通道传输键盘/鼠标。
## 许可证
MIT -- 参见 [LICENSE](https://github.com/richlegrand/bitbang-cli/blob/main/LICENSE)。
## 贡献
欢迎提交 issue 和 PR。
配方（Recipe）则不同：它们位于 [cookbook](https://github.com/richlegrand/bitbang/blob/main/cookbook.md)，
在 [bitbang](https://github.com/richlegrand/bitbang) 仓库中，因为它们跨越
所有项目，而非仅此项目。添加配方是在那里提交 PR。
将其*列出*则是每个项目的一个小型 PR，其 README 应展示该配方 -- 上方的 [Recipes](#recipes) 列表在此处手动维护。这是有意为之：每个项目自行决定哪些配方值得呈现给其读者，而不是让每个 README 都不断添加所有配方。
