Tactic Remote의 아키텍처: 분산 코딩 플랫폼 구축기

원격 개발 플랫폼을 구축하는 것은 문서상으로는 간단해 보입니다: 한 머신에서 코드를 실행하고 다른 머신에 표시하면 됩니다. 실제로는 엔지니어링 과제가 깊습니다. 1밀리초의 지연이라도 신뢰를 잠식합니다. 연결이 끊길 때마다 작업 손실의 위험이 있습니다. 보안의 어떤 지름길이라도 재앙을 초래합니다.

이 글에서는 Tactic Remote의 아키텍처를 다룹니다 — 우리가 내린 결정, 수용한 트레이드오프, 그리고 기술적 방향을 이끄는 원칙들입니다.

핵심 문제

개발자들은 Claude Code 같은 AI 지원 코딩 도구에 점점 더 의존하고 있지만, 이러한 도구는 데스크톱 터미널에 묶여 있습니다. 책상을 떠나면 AI 어시스턴트가 무엇을 하고 있는지 볼 수 없습니다. Tactic Remote는 이를 해결합니다: Mac이 실행 엔진으로 유지되고, iPhone이 일급 제어 표면이 됩니다.

핵심 과제는 이것을 투박한 원격 데스크톱 세션이 아닌 매끄러운 경험으로 만드는 것입니다.

계층화된 아키텍처

Tactic Remote는 각각 명확한 책임 경계를 가진 네 개의 구별되는 레이어로 구축되었습니다:

레이어 1: 실행 엔진 (Mac)

기반에는 tmux 세션 안에서 Claude Code를 실행하는 Mac이 있습니다. 우리는 의도적으로 tmux를 선택했습니다 — 프로세스 지속성, 세션 멀티플렉싱, 프로그래밍 방식의 터미널 제어를 위한 잘 알려진 인터페이스를 제공하기 때문입니다. Mac 컴패니언 앱은 tmux 라이프사이클을 관리하고, 세션 상태를 모니터링하며, 상위 소비자를 위한 경량 HTTP API를 노출합니다.

이 레이어의 핵심 설계 결정:

• 프로세스 격리: 각 Claude Code 세션은 자체 tmux 윈도우에서 실행되어 프로젝트 간 오염을 방지합니다.
• 상태 지속성: tmux 세션은 앱 재시작, 네트워크 끊김, 심지어 시스템 슬립 사이클에서도 살아남습니다.
• 최소 풋프린트: 컴패니언 앱은 유휴 시 무시할 수 있는 수준의 CPU와 메모리 오버헤드만 추가합니다.

레이어 2: 전송 레이어

Mac과 iPhone 사이에는 전송 레이어가 있습니다 — 직접 로컬 네트워크 연결 또는 원격 접근을 위한 Cloudflare Tunnel입니다.

로컬 모드는 기기 검색을 위해 mDNS/Bonjour를, 데이터 전송을 위해 직접 HTTP를 사용합니다. 좋은 네트워크에서 10ms 미만의 왕복 시간을 제공하여 터미널 스트리밍이 즉각적으로 느껴집니다.

Cloudflare Tunnel 모드는 Cloudflare의 에지 네트워크를 통해 트래픽을 라우팅합니다. 지연이 추가되지만(일반적으로 30-80ms) 어디서든 접근할 수 있습니다 — 카페, 통근 열차, 또는 지구 반대편에서도. Mac 측의 Cloudflare cloudflared 데몬을 활용하며, 아웃바운드 전용 연결을 설정하므로 방화벽에서 포트를 열 필요가 없습니다.

┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│   iPhone    │◄───────►│  Transport Layer  │◄───────►│     Mac     │
│  (Control)  │   HTTP  │  Local / CF Edge  │   HTTP  │ (Execution) │
└─────────────┘         └──────────────────┘         └─────────────┘

레이어 3: 세션 매니저

세션 매니저가 운영의 두뇌입니다. Mac에서 실행되며, 활성 tmux 세션의 레지스트리를 유지하고, 상태(유휴, 실행 중, 입력 대기)를 추적하며, 재연결의 복잡한 조율을 처리합니다.

네트워크 중단 후 iPhone이 재연결할 때 세션 매니저는 밀리초 안에 여러 질문에 답해야 합니다:

1. 연결 끊김 전에 어떤 세션이 활성 상태였는가?
2. 중단 기간 동안 터미널 출력이 축적되었는가?
3. 민감한 작업에 대한 사용자 승인을 기다리는 세션이 있는가?
4. 각 Claude Code 인스턴스의 현재 프로세스 상태는?

이를 이벤트 소싱(상태 전환을 불변 이벤트로 기록)과 스냅샷 캐싱(빠른 복원을 위해 터미널 버퍼 상태를 주기적으로 캡처)의 조합으로 해결합니다.

레이어 4: 모바일 인터페이스

iPhone 앱은 의도적으로 터미널 에뮬레이터가 아닙니다. 전체 터미널을 휴대폰 화면에 욱여넣는 것은 끔찍한 사용자 경험을 만들 것이라는 초기 결정을 내렸습니다. 대신 모바일 레이어는 다음을 제공합니다:

• 대화 뷰: Claude의 추론과 출력을 읽기 쉬운 형식으로 볼 수 있습니다.
• 터미널 미리보기: 필요할 때 원시 터미널 출력을 빠르게 엿볼 수 있습니다.
• 승인 컨트롤: 인간 확인이 필요한 작업을 원탭으로 승인/거부할 수 있습니다.
• 알림 브릿지: 작업 완료 및 승인 요청에 대한 푸시 알림입니다.

회복력 패턴

실제 네트워크는 불안정합니다. 엘리베이터에서 신호가 끊기고, 방 사이를 이동하면 Wi-Fi가 끊깁니다. 우리의 회복력 전략은 세 가지 원칙 위에 구축되어 있습니다:

연결 끊김을 정상으로 가정합니다. 모든 구성 요소는 네트워크 파티션 중에도 독립적으로 작동하도록 설계되었습니다. Mac은 실행을 계속합니다. iPhone은 마지막으로 알려진 상태를 캐시합니다. 재연결은 전체 재시작이 아닌 상태 조정 프로토콜을 트리거합니다.

작업을 절대 잃지 않습니다. 터미널 출력은 Mac 측에서 설정 가능한 보존 기간으로 버퍼링됩니다. iPhone이 한 시간 동안 오프라인이어도 재연결하면 그동안 일어난 모든 것을 볼 수 있습니다.

장애를 눈에 보이게 만듭니다. 문제가 발생하면 사용자에게 영원히 돌아가는 스피너가 아닌 솔직한 에러 메시지를 보여줍니다. 현실을 초 단위로 반영하는 연결 상태 인디케이터에 많은 투자를 했습니다.

설계에 의한 보안

원격으로 AI 생성 코드를 실행하는 것은 심각한 보안 문제를 제기합니다. 보안 모델은 보안 모델 문서에서 자세히 다루고 있으며, 아키텍처의 주요 특징은 다음과 같습니다:

• 제로 트러스트 전송: 로컬(TLS)이든 터널(Cloudflare 암호화 레이어)이든 모든 통신이 암호화됩니다.
• 승인 게이트: 민감한 작업(파일 쓰기, 셸 명령, 네트워크 접근)은 실행 전에 모바일에서 명시적 승인이 필요합니다.
• 클라우드 의존성 없음: 코드는 Mac을 떠나지 않습니다. Tactic Remote는 데이터 플레인이 아닌 컨트롤 플레인입니다.

다음 단계

아키텍처는 결코 완성되지 않습니다. 멀티 Mac 지원(하나의 iPhone을 여러 개발 머신에 연결), 협업 세션(여러 팀원이 같은 Claude Code 실행을 모니터링), 더 깊은 IDE 통합을 활발히 개발 중입니다. 각각은 우리가 구축한 안정성을 훼손하지 않으면서 아키텍처를 확장해야 합니다.

분산 개발 도구를 구축하는 분들에게 이 개요가 유용하길 바랍니다. 그리고 이 아키텍처를 직접 경험하고 싶다면 여기에서 시작하세요.