Heeler로 아이폰에서 코딩 에이전트를 원격 관리한다

Heeler를 쓰면 아이폰에서 여러 기기의 코딩 에이전트를 확인하고, 실행 중인 터미널을 열어 입력을 보낼 수 있다. 에이전트 상태에 따라 목록을 정렬하며, 막힌 에이전트를 먼저 보여준다.

오픈소스 iOS 앱 Heeler가 Herdr용 동반 앱으로 공개됐다. 코딩 에이전트를 여러 기기에서 실행하는 사람은 아이폰이나 아이패드로 에이전트 상태를 살피고 작업에 개입할 수 있다.

Heeler는 어떤 앱인가?

Heeler는 각 기기에서 실행 중인 코딩 에이전트를 모아 보여주는 대시보드다. 작업 현황판을 떠올리면 쉽다. 상태별 목록에서 에이전트를 고르면 실제 터미널을 열어 내용을 읽고 조작할 수 있다.

에이전트 콘솔은 호스트별 필터를 제공하고 실시간으로 갱신된다. 터미널 화면은 libghostty로 표시하며, 스크롤 기록과 터치 스크롤, 길게 눌러 텍스트 선택하기를 지원한다. 오래된 터미널 연결을 이어받는 기능과 나중에 열 수 있도록 웹 링크를 모으는 기능도 있다.

메시지는 iOS 키보드로 작성한 뒤 한 번에 전송한다. 자동 수정, 입력기, 받아쓰기 기능을 쓸 수 있고, 도구 키보드에는 에이전트 제어 키와 에이전트 스킬, 재사용 가능한 문구, 터미널 모양 설정이 포함된다. 에이전트 작업 디렉터리에서 일반 셸을 열 수 있으며, 텍스트 입력 모드와 키 입력 모드, 워크스페이스마다 재사용하는 탭을 제공한다.

사진이나 최대 64 MiB 크기의 파일을 SFTP(SSH를 이용한 파일 전송 방식)로 호스트에 올리고, 파일 경로를 작성 중인 메시지에 넣을 수 있다. QR 페어링에서는 키를 기기에서 생성하고 개인 키를 키체인에 보관한다. 페어링 코드는 호스트 키 지문을 고정한다.

에이전트가 차단되거나 작업을 마치면 종단 간 암호화된 푸시 알림을 받을 수 있다. 실시간 에이전트 상태는 잠금 화면과 다이내믹 아일랜드의 라이브 액티비티로 표시된다. 알림 중계 서버는 알림 내용을 읽을 수 없다고 프로젝트는 설명한다. 자세한 내용은 개인정보 보호 문서에 있다.

그 밖에 저장소의 깨끗한 작업 트리에서 에이전트를 시작하는 기능, 시스템·밝은색·어두운색 테마, 밝은색과 어두운색을 따로 설정할 수 있는 터미널 테마 30종, JetBrains Mono와 IBM Plex Mono 글꼴, 확대·축소 제스처를 지원한다. SSH 점프 호스트를 거쳐 직접 연결할 수 없는 기기에 접속하며, 두 연결 구간의 키를 확인한다.

연결하려면 무엇이 필요한가?

macOS와 Linux 호스트에서는 Heeler가 SSH를 통해 herdr의 JSON API에 연결한다. 각 요청은 herdr.sock으로 가는 직접 stream-local 채널을 열고, 이벤트 스트림에는 장시간 유지되는 채널 하나를 쓴다. 대화형 터미널은 SSH 의사 터미널에서 herdr agent attach --takeover를 실행한다.

필요한 것은 SSH 접속 권한과 실행 중인 herdr뿐이다. 서버 변경이나 추가 패키지는 필요하지 않다. SSH 서버에서 stream-local 전달을 허용해야 하며, OpenSSH의 기본 설정에서는 허용된다. 이 설정이 꺼져 있으면 초기 설정 과정에서 안내한다. herdr 0.9.3 이상을 사용하는 네이티브 Windows 호스트도 SSH로 연결할 수 있지만, 앱에 수동으로 추가해야 한다.

직접 연결할 수 없는 기기는 SSH 점프 호스트 뒤에 둘 수 있다. 프로젝트는 원격 접속 설정 안내와 아키텍처·보안 경계·VPS 운영 안내를 제공한다.

기기를 추가하려면 무엇을 할까?

Heeler는 App Store 또는 TestFlight에서 설치할 수 있다. macOS나 Linux에서는 먼저 herdr를 설치하고 SSH를 활성화한다. 네이티브 Windows 호스트는 Windows 설정 안내를 따른다.

herdr를 실행하는 macOS 또는 Linux 기기는 Node 20 이상, herdr 0.7.5 이상, OpenSSH 서버가 필요하다. macOS에서는 시스템 설정의 ‘일반’에서 ‘공유’를 열고 ‘원격 로그인’을 켠다. 이어서 다음 명령을 실행한다.

herdr plugin install ZingerLittleBee/Heeler/plugin --ref main --yes
herdr plugin action invoke heeler.pair

표시되는 페어링 코드의 QR을 스캔하면 기기가 호스트로 추가된다. 코드에는 주소와 호스트 키 지문, SSH 키 등록 정보가 담긴다. 같은 플러그인은 앱에서 호스트 알림을 활성화할 때 암호화된 알림도 전달한다.

다른 앱에서 링크를 열어 Heeler의 특정 에이전트로 이동할 수도 있다.

heeler://agent?host=my-mac&session=work&pane=w1%3Ap1

host에는 해당 세션에서 저장된 호스트의 주소를 넣는다. 주소가 일치하는 저장된 호스트가 없을 때는 호스트 이름으로 찾는다. 대소문자는 구분하지 않는다. session은 herdr 세션 이름이며, 생략하거나 default를 지정하면 기본 세션을 연다. pane은 herdr의 창 식별자다. 생략하면 콘솔을 연다.

각 값은 퍼센트 인코딩해야 하며, 공백에는 %20을 쓴다. +는 더하기 기호로 유지되므로 JavaScript의 URLSearchParams 같은 폼 인코딩 방식은 Build Box 같은 이름을 처리하지 못한다. 해당 세션에서 일치하는 저장된 호스트가 없거나 둘 이상이면 링크는 콘솔을 연다.

설치 환경과 제약은?

Heeler는 SwiftUI로 만든 iOS 18 이상용 앱이며 아이폰과 아이패드를 지원한다. 프로젝트에 따르면 아이패드 지원은 0.1.8에서 다시 제공됐으며, Magic Keyboard 단축키와 여러 창, 드래그 앤 드롭을 포함한다. SSH에는 저장소 내부의 Packages/HeelerSSH(libssh2와 OpenSSL 기반)를 사용하고, 터미널 에뮬레이션과 Metal 렌더링에는 libghostty-spm을 쓴다. 설계 결정은 저장소의 docs/adr/에서 확인할 수 있다.

프로젝트는 App Store에 출시됐지만 모든 국가와 지역에서 제공되지는 않는다. 이용할 수 없는 지역에서는 TestFlight 빌드를 받을 수 있다. 개인 사용을 먼저 염두에 두고 개발했으며, 거친 부분과 빠른 업데이트가 있을 수 있다고 프로젝트는 안내한다. Heeler는 herdr 프로젝트와 제휴하지 않았다. 기여 방법은 CONTRIBUTING.md에 있다.

설치 전에는 기기의 iOS 버전과 호스트의 운영체제·herdr 버전을 확인하고, SSH 접속과 stream-local 전달이 가능한지 살펴야 한다. 원문은 App Store에서 제공되지 않는 국가·지역의 구체적인 목록이나 앱의 가격을 밝히지 않는다.