
포트 포워딩이나 계정 없이 브라우저 또는 CLI를 사용하여, 종단 간 암호화된 피어투피어 WebRTC를 통해 대화형 셸, 파일 전송, 웹 프록시를 제공하는 머신에 대한 안전한 원격 접속을 설정합니다.
# BitBang CLI
[](https://github.com/richlegrand/bitbang-cli/actions/workflows/tests.yml)

`bitbang`은 단일 정적 바이너리 원격 접속 멀티툴입니다. 어떤 브라우저에서든 원격 머신에 대한 대화형 셸과 파일 브라우저에 접속할 수 있습니다. 또한 해당 머신의 네트워크에 있는 웹 앱에도 접근할 수 있습니다. 브라우저 외에도 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 | 계정 + 각 기기에서 로그인 | **명령 하나 실행** |
| 무언가를 공유하려면 실행할 것 | 웹 서버, 그리고 ngrok | 양쪽 머신에 그들의 클라이언트 | **`bitbang serve`** |
| 반대편 브라우저가 얻는 것 | 이미 실행 중이던 웹 서버 | 아무것도 없음 -- 그들의 클라이언트가 필요 | **터미널, 파일 브라우저, 원격 네트워크의 웹 앱** |
| 데이터 경로 | 그들의 서버 | 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 뒤에 있는 머신에서 셸 얻기](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [휴대폰에서 셸 얻기](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이나 QR 코드를 건네는 것에 불과합니다. 권한은 맞춤 설정할 수 있으며 분, 시간 단위로 만료되도록 설정할 수 있습니다.
- [파일을 어디에도 업로드하지 않고 공유하기](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)
- [휴대폰에서 에이전트 세션 확인하기 (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)
- [LAN의 다른 머신이 포워드를 사용하도록 허용하기](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
```
각각 QR 코드, URL, 페어링 코드를 출력합니다. 모드는 리스너가 애초에 무엇을 할 수 있는지를 결정합니다. `serve shell`은 부여할 포워딩이 없고, 포워딩 전용 리스너는 셸을 시작하지 않으므로 권한 상승할 대상이 없습니다.
알아둘 만한 기본값이 하나 있습니다. **포워딩과 프록시는 리스너가 도달할 수 있는 모든 host:port에 접근**하며, 생각했던 대상 하나에만 국한되지 않습니다. 따라서 데이터베이스용으로 발급한 링크는 해당 네트워크의 나머지에도 도달합니다. 대상을 단어 뒤에 지정하면 범위가 좁아집니다. `forward db.internal:5432`는 그 대상에만 도달하고 다른 곳에는 도달하지 않습니다.
### 실행 중인 세션 공유: `bitbang share`
`serve 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을 열 수는 있지만 공유를 호스팅할 수는 없습니다.
기본적으로 이 명령은 두 개의 베어러 URL을 출력합니다:
- **Control URL**은 로컬 키보드와 동일한 권한으로 입력할 수 있습니다. 한 번에 하나의 컨트롤러만 연결할 수 있습니다.
- **View URL**은 보기 전용입니다. 입력은 tmux에 도달하기 전에 버려지며, 최대 `--max-viewers`명의 뷰어가 동시에 연결할 수 있습니다(기본값 16).
`--read-only`는 컨트롤 자격 증명을 완전히 생략합니다. 뷰어 및 컨트롤러 제한은 셸을 열기 전이라도 각 연결의 수명 동안 유지됩니다.
공유는 기본적으로 중지할 때까지 실행됩니다. `--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
[
{"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`가 제공할 것과 동일한 메시지로 거부합니다.
링크를 식별하는 것은 조건이 아니라 레이블이므로, 두 사람이 동일한 grant와 만료를 가진 링크를 보유할 수 있으며, 여전히 다른 링크를 건드리지 않고 하나를 취소할 수 있습니다.
취소와 만료는 이미 열려 있는 세션에도 적용됩니다. 연결이 닫히고 보유자에게 이유가 통보되며, 조용히 끊기지 않습니다. 그리고 만료된 코드는 일시 중지되는 것이 아니라 폐기됩니다. 항목을 갱신하면 새 코드가 발급되므로, 이미 보낸 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=`에서 설정하므로 유닛에는 다른 것이 필요 없습니다 |
| `$XDG_STATE_HOME` | `$XDG_STATE_HOME/bitbang` |
| `$HOME` | `$HOME/.bitbang` |
| 어느 것도 없음 | 아무것도 없음: BitBang이 중지하고 그 사실을 알립니다 |
처음 세 개는 디렉터리 자체를 지정하고, 마지막 두 개는 그 디렉터리가 위치한 상위 디렉터리를 지정합니다.
마지막 행은 서비스 사용자에게 홈이 없는 환경에서 중요합니다. 이전 버전에서는 작업 디렉터리로 대체되었기 때문에, `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을 붙여넣거나 QR 코드를 스캔할 수 없을 때, 예를 들어 전화 중이거나 소리칠 수 있는 거리에 있을 때, `bitbang serve`는 짧은 **페어링 코드**도 출력합니다. 상대방은 `bitba.ng/<code>`를 열거나(`bitbang connect <code>`를 실행하거나) 화면에 표시된 두 번째 6자리 숫자를 읽어 *그* 숫자를 당신에게 알려줍니다. 당신이 그것을 입력하여 승인합니다. 중간자 공격자는 두 숫자를 일치시킬 수 없으며, 페어링은 다음 번을 위해 장치 연결 자격 증명을 저장합니다(예: `bitbang connect nas1`). [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole)을 안다면 형태가 비슷합니다 -- 두 머신을 안전하게 소개하는 구두 코드입니다.

### 자체 TURN 사용하기
대부분의 연결은 피어 투 피어로 직접 이루어집니다. 양쪽 끝이 홀 펀칭을 허용하지 않는 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** -- LAN 주소(`nas.local`, `192.168.1.10:8080`, `localhost:3000/admin`)를 입력하고 마치 로컬에 있는 것처럼 앱을 사용합니다. 로그인, 쿠키, 업로드, 스트리밍이 모두 작동합니다.
<!-- 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`은 `ssh -L`처럼 **TCP만** 전달합니다. `-L`은 `-g`를 전달하지 않는 한 `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 |
| ---------------------------------------- | :---: | :---: | :-----: |
| 셸, 파일, 프록시 (`bitbang serve`) | yes | yes | yes |
| TCP 포워딩 (`-L`) | yes | yes | yes |
| 액세스 링크 -- 부여, 만료, 폐기 | yes | yes | yes |
| 자체 TURN 사용 | yes | yes | yes |
| 6자리 코드로 페어링 | yes | yes | yes |
| 리스너 콘솔 (Enter) | yes | yes | yes |
| `bitbang connect`, `bitbang cp` | yes | yes | yes |
| 공유 세션 보기 | yes | yes | yes |
| **공유 호스팅** (`bitbang share`) | yes | yes | no * |
| **연결 중 터미널 크기 조정** | yes | yes | no ** |
\* `bitbang share`는 tmux 세션을 게시하므로, 호스팅하려면 tmux가 필요합니다 --
Linux, macOS 또는 WSL. 네이티브 Windows에서도 `bitbang connect`로
공유 URL을 열 수 있습니다.
\*\* Windows 커넥터는 터미널 크기 조정을 감지하지 못하므로, 다시 연결할 때까지
원격 셸은 시작할 때의 크기를 유지합니다. Unix는 이를 `SIGWINCH`에서 얻지만,
Windows에는 이에 해당하는 것이 없습니다.
## 보안
- **자기 인증 신원.** 첫 실행 시 `bitbang`은 `~/.bitbang/<program>/` 아래에 RSA 키 쌍을 생성합니다. 장치 UID는 공개 키에서 파생되므로, 장치를 사칭하려면 해당 UID의 두 번째 프리이미지를 찾아야 합니다.
- **비밀은 서버에 닿지 않습니다.** 액세스 코드는 URL 프래그먼트(`#…`)에 있으며, 브라우저는 이를 절대 전송하지 않습니다 -- `bitba.ng`는 연결을 중개하지만 이를 승인하는 자격 증명을 보지 못합니다.
- **종단 간 암호화.** 모든 트래픽은 WebRTC의 DTLS를 통해 전송됩니다. 시그널링 서버는 공개 키, 파생된 UID, 연결 메타데이터만 보며 -- 데이터는 절대 보지 못합니다. TURN 릴레이가 필요한 경우에도 암호문만 봅니다.
- **검증된 페어링.** 코드 페어링에서 소리 내어 읽는 숫자는 짧은 인증 문자열(SAS)로, 협상된 DTLS 지문과 두 개의 커밋된 논스로부터 양쪽 끝에서 독립적으로 계산됩니다 -- 지문이 반드시 달라야 하는 중간자 공격자는 두 숫자를 일치시킬 수 없습니다.
- **URL은 무기명 자격 증명입니다.** URL을 가진 사람은 당신이 제공하기로 선택한 무엇이든 얻습니다 -- `serve 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. OS와 아키텍처(`amd64`, `arm64`, Linux에서는 `armv7`)를 감지하고, 최신 [GitHub 릴리스](https://github.com/richlegrand/bitbang-cli/releases)에서 바이너리를 다운로드한 뒤, 릴리스의 `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에서 PC를 보호했습니다"* 가 표시됩니다 -- **추가 정보**를 선택한 다음 **실행**을 선택하세요.
릴리스 바이너리는 코드 서명되지 않았으므로 이는 문제가 있다는 신호가 아니라 예상된 동작입니다.
`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` 접두사가 없습니다(`v0.5.0`이 아니라 `0.5.0`).
### 설치 URL의 동작 방식
`bitba.ng/install`은 호스팅된 스크립트가 아니라 리다이렉트입니다. 그 체인은 다음과 같습니다:
1. `curl`이 `https://bitba.ng/install`에 요청하면, 이 저장소의 (`main` 브랜치에 있는) [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/main/install.sh)로 302 리다이렉트됩니다.
2. 스크립트가 셸에서 실행되어 OS와 아키텍처를 감지한 뒤, `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
```
셸 명령, 파일 공유, 프록시, CLI 클라이언트는 Windows에서 지원됩니다. 대화형 브라우저 및 CLI 셸은 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 셸 및 파일 공유" width="760">
---
[Read more](https://github.com/richlegrand/bitbang-cli)