ColliePWA

ColliePWA는 Herdr를 위한 오픈 소스 (MIT) 모바일 클라이언트이며, tmux와 zellij에 대한 실험적인 지원을 제공합니다. 이는 휴대폰에서 Claude Code, Codex 및 OpenCode와 같은 터미널 AI 에이전트를 구동하기 위한 자체 호스팅 웹 앱 (PWA)입니다. 각 인스턴스는 하나의 터미널 멀티플렉서에 연결되며, 그 옆에 사용자의 에이전트가 지속적으로 작동하는 모습을 보여줄 수 있습니다. 기본적으로 Tailscale을 통해 서비스됩니다.

iPhone 또는 Android 휴대폰에서 URL을 열면 어떤 에이전트가 입력을 필요로 하는지 확인하고 모바일 키보드에서 직접 응답할 수 있습니다.

Herdr를 사용하시나요? Herdr 모바일 클라이언트에 대해 읽어보세요.

입력 상자는 시스템 음성 받아쓰기와 호환되는 표준 텍스트 필드를 사용합니다. Collie는 또한 명시적으로 구성될 때까지 비활성화 상태로 유지되는 내장 음성 입력을 포함하고 있습니다.

기능

• React Router + Vite에 TypeScript, Tailwind, shadcn, 그리고 Bun 브리지를 사용
• 사용자 입력이 필요한 경우 어떤 부분이 도움이 필요한지 보여주는 상태 대시보드(Status dashboard); 나머지 패널들은 자체 작업 공간(workspace) 아래에 배치되며, 행마다 탭을 가집니다.
• 에이전트가 사용자 입력을 기다릴 때 푸시 알림
• 에이전트별로 구성 가능한 빠른 동작 및 슬래시 명령어(slash commands)
• 사용자가 직접 배열하는 키보드: Esc, Ctrl+C, 화살표 키 및 수정자 조합 외에도 더 넓은 키, 자신만의 코드와 시퀀스, 고정된 Ctrl/Alt/Shift, 프리셋(Claude Code, Prefix, Vim) 및 공유할 수 있는 레이아웃 코드를 제공합니다.
• 휴대폰에서 시작: + 새 작업 버튼을 누르면 기기, 에이전트 또는 명령어, 폴더, 그리고 선택적 새로운 작업 공간을 지정하는 페이지가 열립니다. 각 기기는 어떤 에이전트를 가지고 있는지 보여주고, 놓친 답변은 두 번째 패널을 열지 않으며, 휴대폰에서 자체 런처를 추가할 수 있습니다.
• 출력 검색 및 표준 터미널 스크롤백 이상의 전체 대화 기록
• 파일 화면: 에이전트 작업 공간 폴더의 파일들이 변경 사항과 함께 표시되며, Git 저장소에서 무엇을 변경했는지 diff 형태로 구문 색상과 함께 보여주는 '변경 사항(Changes)' 섹션과 마지막 커밋 정보가 읽기 전용으로 제공됩니다.
• 파일 첨부: 카메라 롤의 이미지와 마크다운, 텍스트 및 코드 파일
• 항상 활성화되는 장치 페어링(Device pairing): 장치는 모든 요청에 대해 토큰이 필요하며, 읽기와 쓰기를 수행하고, 페어링되지 않은 브라우저는 페어 화면만 볼 수 있습니다.
• 크루(Crews): 하나의 URL 뒤에 여러 기기의 Collie를 배치하고 운영자가 트리거하는 장애 조치(failover) 기능을 제공합니다.
• 내구성 에이전트(Durable agents): 장기간 실행되는 내구성 에이전트는 승인 및 기록을 포함하는 휴대폰 세션입니다 (실험적).
• 12가지 UI 언어와 기기별 글꼴 설정
• 웹 인터페이스에서 관리하는 Herdr 세션 전환(session switching)
• 외부 계정이나 클라우드 종속성 없이 로컬 루프백에서 실행되는 PWA 지원
• 텔레메트리 없음: 앱은 분석, 사용 통계 또는 충돌 보고서를 전송하지 않습니다. 유일하게 예고 없이 호출하는 것은 GitHub의 업데이트 확인입니다 (자세히 보기)## 데모

휴대폰에서 Collie 사용하기: 대시보드는 입력이 필요한 에이전트를 상단에 배치합니다. 스페이스(spaces), 탭(tabs), 페인(panes)을 검사할 수 있습니다. 페인 필이나 탭 칩을 길게 누르면 이름을 바꾸거나 닫을 수 있으며, Claude 페인은 /rename으로 설정한 이름이 반영됩니다. 대시보드 행 또는 페인 필을 길게 누르거나 마우스 오른쪽 버튼을 클릭하면 해당 페인을 대시보드의 상단과 스위처(switcher)에 고정할 수 있습니다. 탭하여 AskUserQuestion 프롬프트에 답변하고, 서드(herds) 간 전환하며, 에이전트가 입력으로 인해 블록될 때 푸시 알림을 받을 수 있습니다.

interactive demo에서는 설치 없이 브라우저에서 모의 데이터(mock data)를 사용하여 웹 클라이언트를 실행합니다.

개발 동기 (Motivation)

저는 휴대폰으로 에이전트들을 확인하고 싶었습니다. 일반적인 경로는 Termux를 통해 SSH로 접속한 다음 tmux나 zellij 세션에 연결하는 것입니다. 화면 제어 장치(TUI)를 온스크린 컨트롤러로 구동하는 것은 불편합니다. 특수 키가 까다롭고, Ctrl/Esc/화살표는 어색한 조합을 요구하며, 단순 텍스트 입력은 소프트웨어 키보드와 충돌하기 때문입니다. 저는 터미널을 강제로 태블릿 화면에 넣는 방식 대신 모바일 인터페이스를 원했습니다. Collie는 사용자가 입력을 필요로 하는 에이전트를 탭하고, 평소처럼 타이핑하며, 엄지손가락 하나로 Esc 또는 Ctrl+C를 보낼 수 있게 해줍니다.

누가 사용해야 할까요 (Who is this for)

Collie는 터미널 멀티플렉서(terminal multiplexer)에서 AI 에이전트를 실행하는 개발자 중 휴대폰으로 세션을 재개하고 싶은 사람들을 위한 것입니다. 1.0 버전에서 주로 지원되는 대상은 Herdr입니다. tmux와 zellij에 대한 지원은 실험적입니다: 둘 다 작동하지만, 테스트는 단일 운영자가 하나의 기기에서만 제한적으로 수행할 수 있습니다. 만약 이 둘 중 어느 것을 사용한다면, 버그 보고(bug reports)를 환영합니다. 작동하는 설정 사례도 포함하여 보고해 주세요.

이 설정은 Tailscale tailnet을 전제로 합니다. 사용자의 휴대폰과 호스트는 하나의 tailnet을 공유해야 하며, tailscale serve가 기본 인그레스(ingress)로 구성되어야 합니다. Collie는 **단일 사용자용(single-user)**입니다: 단일 운영자가 하나의 tailnet에서 사용할 수 있으며, 다중 테넌트 인증은 지원하지 않습니다. 공유되거나 공개적인 접근을 위해 사용해서는 안 됩니다. 실행하기 전에 아래 보안 섹션을 읽어보세요.

보안 (Security) — 이것부터 읽으세요

Collie는 설계상 장치에 원격 셸 액세스를 제공합니다. 단일 Collie API 호출만으로 임의의 키 입력을 실시간 터미널 창(pane)으로 직접 전송할 수 있습니다. 이 URL에 접근할 수 있는 사람은 누구나 해당 창의 출력(소스 코드, 비밀 정보, 환경 변수, 에이전트 출력)을 읽고, 사용자의 모든 권한으로 임의 명령을 실행할 수 있습니다. 핵심 워크플로우를 무력화시킬 것이므로 샌드박스나 명령어 허용 목록은 없습니다. 이 URL을 루트 로그인처럼 취급하고, 반드시 tailnet에 바인딩하며, COLLIE_TRUSTED_USER를 설정하고, 사용 중인 물리적 휴대폰만 페어링하세요. 서비스를 실행하기 전에 보안 모델, 방어 계층, 장치 게이팅에 대한 자세한 내용은 docs/security.md를 읽으십시오.

🚫 절대 tailscale funnel로 사용하지 마세요: funnel은 포트를 공개 인터넷에 노출하는 반면, serve는 접근을 사설 tailnet으로 제한합니다. 어떤 경우에도 Collie를 funneled 해서는 안 됩니다.

빠른 시작 (Quickstart)

Tailscale이나 Herdr가 처음이신가요? 5분 만에 설치하기 가 빈 컴퓨터에서 휴대폰의 Collie까지 전체 설정을 안내합니다.

이 명령어는 휴대폰이 아닌 호스트(host)에서 실행해야 합니다. curl, tar, 그리고 sha256 유틸리티가 필요합니다. 컴파일러 툴체인은 필요하지 않으며 sudo를 요구하지 않습니다:

curl -fsSL https://colliepwa.dev/install.sh | sh

이 스크립트는 플랫폼에 맞는 최신 버전을 다운로드하고, sha256 체크섬을 검증하며, 파일을 설치하고, collie를 PATH에 추가합니다. 그런 다음 남아 있는 수동 단계를 출력합니다: 설정(config) 시딩 후, collie start를 실행합니다. 미리 멀티플렉서(multiplexer)를 지정할 필요가 없습니다. 첫 실행 시, collie start는 Herdr, tmux, zellij를 감지한 다음 선택을 요청합니다. 소스에서 빌드하는 것을 선호한다면, docs/install.md 가 수동 빌드, 각 시스템 및 패키지, Herdr 라우트, 그리고 iPhone 또는 Android 휴대폰의 홈 화면에 Collie를 추가하는 방법을 다룹니다.

ColliePWA는 App Store나 Google Play에 없습니다. 브라우저에서 홈 화면에 추가해야 하며, 이것이 휴대폰에 설치할 수 있는 유일한 방법입니다.

문서 (Documentation)

가이드 (Guides)

세션 (Sessions)

내구성 있는 에이전트 (Durable agents)

참고 자료 (Reference)

배포 변형 (Deployment variants)

Collie는 항상 loopback만 바인딩합니다. 배포 간에 변경되는 것은 그 앞에 무엇이 놓여 있는지와 요청이 자신이 누구인지 어떻게 증명하는지입니다. Variant A가 기본값이며 아래에 위치하고, 나머지 네 가지는 docs/deployment.md에 있습니다. 하나를 선택하세요.

Variant A — tailscale serve + 사용자 신원 (기본값)

설치에서 오는 정상적인 경로입니다. tailscale serve는 MagicDNS 이름에서 TLS를 종료하고 Tailscale-User-Login을 주입하며, COLLIE_TRUSTED_USER를 사용자의 tailnet 로그인으로 설정하면 Collie는 다른 모든 사람을 거부합니다.

# .env 파일에
[email protected]