원문 캡처 · github.com
원문 캡처 · github.com

Muxer는 안드로이드폰에서 cmux 터미널을 확인하고 조작하는 독립 프로젝트다. 워크스페이스와 에이전트 세션을 살펴보고, 터미널에 입력하거나 코딩 에이전트의 알림에 답할 수 있다.

cmux 계정에 로그인할 필요는 없다. 휴대폰과 사용자의 컴퓨터 사이에서 사용자가 관리하는 사설 네트워크를 통해 작동하며, 중간에 클라우드 서비스가 들어가지 않는다. 프로젝트는 Tailscale을 가장 간편한 설정 방법으로 안내하고, 다른 VPN이나 신뢰할 수 있는 로컬 네트워크, Cloudflare Access 뒤에 둔 Cloudflare Tunnel도 지원한다. Muxer는 Manaflow나 cmux 팀이 만들거나 보증·지원하는 프로젝트가 아니다.

  • 알림이나 홈 화면 위젯에서 에이전트의 권한 요청·질문·계획에 답하고, Claude Code, Codex, Pi 세션에서 텍스트·음성·@ 파일 멘션·사진을 주고받을 수 있다.
  • 새 에이전트 작업을 폴더나 열린 워크스페이스에서 시작하거나 이전 세션을 이어갈 수 있다. cmux 알림을 휴대폰으로 받고 인라인 답장, 말풍선, 백그라운드 전달 기능을 쓸 수 있다.
  • 워크스페이스를 만들고 이름 변경·고정·색상 변경·그룹화할 수 있으며, 에이전트 상태와 읽지 않은 항목 수도 확인할 수 있다.
  • 고정 보조 키, 로컬 스크롤백, 복사 기능이 있는 실시간 터미널을 제공한다. 다른 앱에서 텍스트와 링크를 에이전트에 공유할 수도 있다.
  • 컴퓨터별 CPU와 RAM을 확인하고 컴퓨터가 절전 상태가 되지 않도록 하며, cmux Cloud VM과 자동화를 관리할 수 있다. Tailscale을 통해 터미널이 사용하는 포트를 휴대폰 브라우저에서 열 수도 있다.
  • 지문·얼굴 인식 또는 화면 잠금으로 앱을 잠글 수 있다.

컴퓨터와 휴대폰 연결하기

컴퓨터에는 cmux 0.65 이상이 필요하며, 휴대폰이 컴퓨터에 HTTPS로 접속할 수 있어야 한다. 아래 설정 절차는 컴퓨터와 휴대폰 모두 Tailscale에 로그인한 경우를 기준으로 한다. 다른 연결 방법은 릴레이에 접속하는 방법을 참고하면 된다.

컴퓨터에 릴레이를 설치한다. Homebrew를 이용하는 방법은 다음과 같다.

sh
brew install gantoine/tap/muxer

다른 방법으로는 릴리스 페이지에서 Apple silicon용 muxer-<version>-darwin-arm64.tar.gz 또는 Intel용 -darwin-amd64.tar.gz를 내려받는다. SHA256SUMS와 대조해 확인한 뒤 압축을 풀고, muxer를 PATH에 있는 폴더로 옮긴다. 바이너리는 Apple의 공증을 받지 않았다. 브라우저로 내려받았다면 처음 실행하기 전에 다음 명령을 실행해야 한다.

sh
xattr -d com.apple.quarantine muxer

cmux가 릴레이의 접속을 허용하도록 설정한다. 기본 설정에서는 cmux 터미널 안에서 시작된 프로그램만 cmux에 접속할 수 있지만, 릴레이는 백그라운드에서 실행된다. 따라서 소켓 접근 모드를 Password(권장) 또는 automation으로 바꿔야 한다. cmux에서 Settings › Automation을 열어 소켓 접근을 Password로 설정하고 암호를 지정하면 된다. 릴레이는 cmux CLI와 같은 파일인 ~/.local/state/cmux/socket-control-password에서 암호를 읽는다. 다른 방법으로 ~/.config/cmux/cmux.json에 다음 설정을 넣을 수 있다. 이 모드에서는 같은 사용자 계정으로 실행되는 모든 프로그램이 암호 없이 cmux를 제어할 수 있다.

json
"automation": { "socketControlMode": "automation" }

로그인할 때 릴레이가 시작되도록 설정하고, Tailscale을 이용해 휴대폰에서만 접근할 수 있도록 한다. 이어서 설정을 점검한다.

sh
muxer install
tailscale serve --bg --https=8765 http://127.0.0.1:8765
muxer doctor

휴대폰에는 릴리스 페이지의 APK를 설치한다. 설치 파일을 확인하려면 컴퓨터에서 다음 명령을 실행하고, 표시된 SHA-256 인증서 지문을 아래 값과 비교한다.

sh
apksigner verify --print-certs muxer-<version>.apk
text
9D:6C:85:65:17:81:34:51:CF:1D:82:8F:BC:A0:AE:91:B0:D4:C5:92:B0:74:04:0F:72:19:19:DB:C5:61:5C:8B

컴퓨터에서 muxer pair를 실행한다. 이 명령은 컴퓨터의 Tailscale 이름을 사용한다. 다른 방식으로 릴레이에 접속한다면 주소를 지정할 수 있다.

sh
muxer pair
muxer pair --url https://muxer.example.com

휴대폰 카메라로 QR 코드를 스캔하거나 앱에서 Pair a computer를 눌러 주소와 코드를 입력한다. 페어링 코드는 한 번만 쓸 수 있고 10분 뒤 만료된다. 연결한 컴퓨터는 앱의 Computers 목록에 표시된다.

릴레이 접속과 터미널 포트

앱은 HTTPS로만 릴레이에 접속하며, 공인 인증 기관이 발급한 인증서만 허용한다. 따라서 일반 HTTP와 자체 서명 인증서는 사용할 수 없다. 릴레이는 127.0.0.1에서만 수신하도록 두고, 앞단에 HTTPS를 제공하면서 사용자의 기기만 접근할 수 있게 하는 프록시를 둬야 한다.

  • Tailscale의 tailscale serve는 컴퓨터의 tailnet 이름에 인증서를 연결하고 릴레이를 tailnet 안에 둔다. muxer pair와 muxer doctor가 설정을 도와준다.
  • WireGuard나 ZeroTier 같은 다른 VPN 또는 로컬 네트워크에서는 컴퓨터에서 Caddy 같은 리버스 프록시를 실행할 수 있다. 소유한 도메인을 컴퓨터의 사설 주소로 연결하고 DNS 챌린지로 Let's Encrypt 인증서를 발급받는다. 이 방법은 모든 기기를 신뢰할 수 있는 네트워크에서만 사용해야 한다.
  • Cloudflare Tunnel을 쓸 때는 Cloudflare Access 뒤에 릴레이를 두어 사용자의 기기만 통과하도록 한다. 앱은 브라우저 로그인을 완료할 수 없으므로, 예를 들어 Zero Trust 조직에 등록한 Cloudflare One(WARP) 클라이언트처럼 다른 방식으로 Access가 휴대폰을 인식해야 한다.

그런 다음 muxer pair --url에 해당 주소를 전달해 페어링한다.

휴대폰이 Tailscale을 통해 컴퓨터에 접속하면 터미널 메뉴에서 Open ports in Tailscale을 선택할 수 있다. 이 메뉴는 해당 터미널의 프로그램이 수신 중인 포트를 보여준다. 포트를 누르면 컴퓨터의 Tailscale 이름을 사용해 휴대폰 브라우저에서 연다. 예를 들어 주소는 http://my-mac.tailnet.ts.net:3000과 같은 형태다. 이때 휴대폰은 릴레이를 거치지 않고 tailnet을 통해 포트에 직접 접속한다.

127.0.0.1에서만 수신하는 서버는 이런 방식으로 접속할 수 없으므로 포트별 스위치가 제공된다. 스위치를 켜면 tailscale serve로 포트를 공개하고 같은 포트의 https:// 주소를 만든다. 그러면 휴대폰뿐 아니라 tailnet에 있는 모든 기기가 해당 포트에 접속할 수 있다. 공개를 중단하려면 스위치를 끈다. 앱의 컴퓨터 설정에는 터미널을 닫은 뒤에도 Muxer가 공개한 포트가 모두 표시된다. 현재 이 기능은 Tailscale에서만 작동한다.

알림과 cmux 자동화

앱은 cmux가 보내는 모든 알림을 표시한다. 따라서 notify 동작을 포함하는 cmux 자동화도 휴대폰에 알림을 보낼 수 있다. 다음 규칙은 과부하 뒤 cmux가 에이전트에 continue를 입력했을 때 알리도록 하는 예시다. 규칙은 ~/.cmuxterm/automations.json에 둔다.

json
{
 "version": 1,
 "rules": [
 {
 "id": "phone-auto-resume",
 "when": { "event": "agent.auto_resume.sent" },
 "then": [
 {
 "action": "notify",
 "title": "Agent resumed",
 "body": "{{payload.agent}} was resumed after a temporary error (attempt {{payload.attempt}})."
 }
 ]
 }
 ]
}

파일을 편집한 뒤 cmux automation reload를 실행해 다시 불러온다. 알림을 실제로 보내지 않고 규칙을 확인하려면 다음 테스트 명령을 사용할 수 있다.

sh
cmux automation test phone-auto-resume --event '{"name":"agent.auto_resume.sent","category":"agent","payload":{"agent":"claude","attempt":1}}'

휴대폰 앱에서 컴퓨터 설정을 열고 Automations를 누르면 규칙을 볼 수 있다. 각 규칙을 켜거나 끄고, 규칙이 반응하는 이벤트와 수행할 동작, 최근 활동을 확인할 수 있다. 파일을 편집한 뒤 다시 불러오는 작업도 앱에서 할 수 있지만, 새 규칙은 컴퓨터의 파일에 작성해야 한다.

릴레이 업데이트와 기기 관리

Homebrew로 릴레이를 업데이트한 뒤 muxer install을 다시 실행하면 새 버전으로 백그라운드 릴레이가 재시작된다.

sh
brew upgrade muxer
muxer install

페어링된 휴대폰을 확인하거나 특정 기기의 연결을 끊어 다시 페어링하게 할 수 있다. 릴레이를 중지하고 로그인 항목에서 제거하려면 muxer uninstall을 실행한다.

sh
muxer devices # list paired phones
muxer revoke DEVICE_ID # disconnect a phone and make it pair again
muxer uninstall # stop the relay and remove it from login items

보안과 제한

페어링된 휴대폰은 cmux에서 사용자가 할 수 있는 작업, 즉 모든 터미널 읽기와 입력을 할 수 있다. 따라서 본인이 관리하는 휴대폰만 페어링하고, 분실한 기기는 연결을 해제해야 한다. 휴대폰마다 무작위 토큰을 발급한다. 컴퓨터에는 토큰 자체가 아니라 SHA-256 해시를 ~/Library/Application Support/muxer/devices.json에 권한 모드 0600으로 저장한다. 휴대폰에서는 Android Keystore의 키를 사용해 토큰을 암호화해 보관한다.

앱 설정에서 Lock Muxer를 켜면 앱을 열 때 또는 1분 이상 자리를 비운 뒤 돌아왔을 때 지문·얼굴 인식·화면 잠금을 요구하도록 설정할 수 있으며, 더 긴 시간도 선택할 수 있다. 휴대폰에서 잠금 화면 알림의 민감한 내용을 숨기도록 설정하면 알림에는 일반 문구만 표시된다. 알림에서 답장하려면 휴대폰 잠금을 풀어야 한다. 위젯에는 개수만 표시되고 앱은 최근 앱 화면에 나타나지 않는다.

페어링 코드는 한 번만 쓸 수 있고 10분 뒤 만료되며, 잘못된 코드를 10회 입력하면 더 이상 사용할 수 없다. 릴레이는 127.0.0.1에서만 수신한다. tailscale serve처럼 사용자의 기기만 접속할 수 있는 HTTPS 프록시 뒤에 둬야 한다. tailscale funnel, 외부에 열린 포트, 접근 제어가 없는 터널을 통해 릴레이를 공개해서는 안 된다.

127.0.0.1에서만 수신하는 포트를 공개하면 tailscale serve가 작동해 공개를 중단할 때까지 tailnet의 모든 기기에서 접속할 수 있다. 릴레이는 cmux 터미널이 수신 중인 포트에 대해서만 이를 설정하고, 릴레이 자체 포트에는 적용하지 않으며, tailscale funnel도 사용하지 않는다. Muxer가 만든 serve 항목만 삭제한다.

페어링·기기 목록 조회·연결 해제는 사용자만 열 수 있는 Unix 소켓을 통해 처리되므로 네트워크를 통해 실행할 수 없다. 릴레이는 릴레이 프로토콜에 열거된 명령만 전달하며, 일반적인 cmux 소켓 프록시는 아니다.

개발·테스트·릴리스 절차와 릴레이 프로토콜은 DEVELOPMENT.md에서 확인할 수 있다. 라이선스는 MIT이며, 자세한 내용은 LICENSE를 참고하면 된다. 로고는 cmux 아이콘의 갈매기 모양을 변형해 사용한다. cmux와 로고의 소유자는 Manaflow, Inc.이며, 이 프로젝트에서 사용했다고 해서 Manaflow가 프로젝트를 만들거나 보증·지원한다는 뜻은 아니다. Manaflow 관계자가 로고 변경을 원하면 이슈를 열어 달라고 프로젝트는 안내한다.