BitBang CLI

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#give-someone-access-that-expires)
- [从手机查看你的代理会话（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，因此也就没有可提升的权限。

一个值得了解的默认行为：转发和代理可以到达监听器能到达的任何主机:端口，而不仅仅是你原本设想的那一个，因此为数据库分发的链接也能到达该网络的其余部分。在单词后指定目标名称可缩小范围——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：

- **控制 URL** 可以输入，权限与本地键盘相同。一次只能连接一个控制器。
- **查看 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"} ]

(empty)```
  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 会给出的相同消息予以拒绝。

标签用于标识链接，而非其条款，因此两个人可以持有授权和过期时间完全相同的链接，而你仍可撤销其中一个而不影响另一个。