bitbang-cli v0.5.0
포트 포워딩이나 계정 없이 브라우저 또는 CLI를 사용하여, 종단 간 암호화된 피어투피어 WebRTC를 통해 대화형 셸, 파일 전송, 웹 프록시를 제공하는 머신에 대한 안전한 원격 접속을 설정합니다.
BitBang CLI
bitbang은 단일 정적 바이너리 원격 접속 멀티툴입니다. 어떤 브라우저에서든 원격 머신에 대한 대화형 셸과 파일 브라우저에 접속할 수 있습니다. 또한 해당 머신의 네트워크에 있는 웹 앱에도 접근할 수 있습니다. 브라우저 외에도 TCP 포트 포워딩, 파일 복사, 터미널 공유를 지원합니다. 계정이나 구성이 필요 없으며, 그냥 바로 작동합니다.
접속하려는 머신에서:
curl -sSfL bitba.ng/install | sh
bitbang serve
serve는 URL을 출력합니다. 아무 브라우저에서나 열면 터미널, 파일 브라우저, 그리고 해당 머신의 네트워크로 향하는 프록시를 얻을 수 있습니다. 또는 다른 터미널에서 bitbang connect <url>로 같은 머신에 접속할 수 있으며, 이는 포트 포워딩(-L)과 파일 복사(bitbang cp)를 추가합니다. 연결은 종단 간 암호화되고 피어 투 피어 방식입니다. bitba.ng 서버는 양 끝을 소개한 뒤 물러납니다.
bitbang은 단일 정적 Go 바이너리입니다. 이는 BitBang 프로젝트의 일부이며, 이 백서에서 설계를 심층적으로 다룹니다.
비교
| ngrok | Tailscale | bitbang | |
|---|---|---|---|
| 첫 사용 전 설정 | 계정 + authtoken | 계정 + 각 기기에서 로그인 | 명령 하나 실행 |
| 무언가를 공유하려면 실행할 것 | 웹 서버, 그리고 ngrok | 양쪽 머신에 그들의 클라이언트 | bitbang serve |
| 반대편 브라우저가 얻는 것 | 이미 실행 중이던 웹 서버 | 아무것도 없음 -- 그들의 클라이언트가 필요 | 터미널, 파일 브라우저, 원격 네트워크의 웹 앱 |
| 데이터 경로 | 그들의 서버 | P2P (릴레이 폴백) | P2P (릴레이 폴백) |
| 종단 간 암호화 | 기본적으로 아님 | 예 | 예 |
간단 레시피
집에 있는 서비스에 접속하기
- 어디서나 집 NAS 마운트하기 (SMB)
- 어디서나 미디어 라이브러리 시청하기 (Jellyfin)
- 어디서나 자신의 LLM 사용하기 (Ollama, Open WebUI)
- 보안 카메라 확인하기 (Frigate)
- 노출 없이 홈 오토메이션에 접속하기 (Home Assistant)
- 집 프린터로 인쇄하기 (IPP, CUPS)
머신에 접속하기
- NAT 뒤에 있는 머신에서 셸 얻기
- 휴대폰에서 셸 얻기
- Windows 머신으로 원격 데스크톱 접속하기 (RDP)
- Linux 또는 Mac 데스크톱에 접속하기 (VNC)
- 열린 포트가 없는 머신에 SSH 접속하기 (OpenSSH)
- 헤드리스 Raspberry Pi 설정하기
다른 사람과 공유하기
공유란 누군가에게 접근 권한을 부여하는 고유한 URL이나 QR 코드를 건네는 것에 불과합니다. 권한은 맞춤 설정할 수 있으며 분, 시간 단위로 만료되도록 설정할 수 있습니다.
- 파일을 어디에도 업로드하지 않고 공유하기
- 누군가에게 프로젝트 보여주기
- 막혀 있는 오류를 누군가에게 보여주기
- 만료되는 액세스 권한 부여하기
- 휴대폰에서 에이전트 세션 확인하기 (Claude Code, tmux)
- 다른 사람의 라우터 고쳐주기
개발 및 기기
- 개발 머신에서 데이터베이스에 접근하기 (Postgres, MySQL)
- 서로를 찾지 못하는 기기 동기화하기 (Syncthing)
- 브라우저에서 로봇 관찰하기 (ROS, Foxglove)
기법
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에 대한 별도의 코드로, 리스너가 제공하는 것의 일부를 부여하며 선택적으로 고정된 시각에 만료됩니다: