클라우드 VM 또는 헤드리스 Linux 서버에서 Claude Code를 실행하고 iPhone으로 제어하기

대부분의 Tactic Remote 사용자는 코드를 작성하는 Mac에서 서버를 실행합니다. 이것이 가장 자연스러운 출발점입니다. 하지만 호스트 컴퓨터가 반드시 노트북일 필요도, 같은 책상 위에 있을 필요도 없습니다.

npx tacticremote는 Node.js가 설치된 모든 Linux 머신에서 실행됩니다 — 클라우드 VM, 원격 개발 머신, TV 아래 헤드리스 박스, Docker 컨테이너 모두 가능합니다. 한 번 실행되면 iOS 앱이 Cloudflare Tunnel을 통해 연결되고, LAN 환경과 동일한 Chat Mode, Terminal Mode, Quick Prompts, 푸시 알림, 원탭 승인 기능을 제공합니다.

이 가이드는 바로 그 구성에 관한 것입니다: 원격 서버에서 지속적으로 실행되는 에이전트, 그리고 어디서나 이를 제어하는 폰.

에이전트를 원격 서버에서 실행하는 이유

호스트를 노트북에서 옮겨야 할 이유는 여러 가지입니다.

충전기에 묶이지 않고 장시간 작업 실행. 수 시간이 걸리는 리팩터링, 대규모 테스트 스위트 실행, 탐색적 코딩 세션은 노트북 뚜껑을 열어 둔 채로 기다리기 어렵습니다. 클라우드 VM은 계속 실행됩니다. 노트북을 닫아도 작업은 계속됩니다.

폰에서 항상 접근 가능. 서버가 항상 켜져 있다면, 외출 전에 따로 시작할 필요가 없습니다. 앱을 열면 세션이 그대로 있습니다.

CI 인접 워크로드. 일부 팀은 AI 에이전트를 이용해 패치 초안 작성, 브랜치 대상 테스트 스위트 실행, 풀 리퀘스트 사전 검토를 수행합니다. 개발자 개인 머신과 분리된 전용 Linux 서버는 이런 용도에 적합한 호스트입니다.

리소스 여유. CPU나 RAM이 더 많은 머신, 또는 API 엔드포인트와 가까운 머신에 에이전트 작업을 오프로드하면 큰 작업의 실제 소요 시간을 줄일 수 있습니다.

Mac 불필요. 주 개발 머신이 Windows 워크스테이션이더라도 Linux 서버가 있다면 거기서 에이전트를 실행하고 iPhone으로 제어할 수 있습니다.

사전 준비

아래 단계를 따르기 전에 다음이 필요합니다:

• 인터넷에서 접근 가능한 Linux 서버 또는 VM (어떤 배포판이든 가능; 테스트 기준은 Ubuntu 22.04 이상)
• Node.js 16 이상 설치됨 (node --version으로 확인)
• 사용하려는 AI 에이전트가 해당 서버에 설치 및 로그인 완료된 상태:
  • Claude Code: Anthropic의 설치 안내를 따른 뒤 claude login
  • Codex: OpenAI 문서에 따라 설치 및 인증
  • Amp: Amp 문서에 따라 설치 및 로그인
• iPhone에 iOS 앱 설치 (App Store)

Mac 메뉴 바 앱이나 Windows 앱은 필요하지 않습니다 — 이들은 데스크탑용 선택적 GUI 래퍼입니다. 헤드리스 서버에서는 npx tacticremote만으로 호스트 측 준비가 끝납니다.

서버 설치 및 실행

npx tacticremote는 글로벌 설치 없이 서버를 가져와 실행합니다. 새 서버에서:

npx tacticremote

최초 실행 시 다음과 같이 출력됩니다:

Tactic Remote server listening on port 8765
API Key: tr_xxxxxxxxxxxxxxxxxxxx
Pair with QR or enter the address manually in the iOS app

원격 서버의 경우 (LAN 없음, mDNS 없음) Cloudflare Tunnel을 통해 연결합니다. 위에 출력된 API Key가 iPhone 인증에 사용됩니다. 복사해 두세요 — 페어링 시 앱에서 입력해야 합니다.

항상 최신 버전 대신 특정 버전을 고정하고 싶다면:

npx tacticremote@latest

systemd로 상시 실행하기

셸에서 npx tacticremote를 실행하면 서버가 올라오지만, 셸 세션이 종료되면 프로세스도 함께 죽습니다. 부팅 시 자동 시작되고 크래시 시 재시작되는 제대로 된 백그라운드 서비스로 실행하려면 systemd를 사용하세요.

유닛 파일을 생성합니다. youruser를 프로세스를 소유할 Linux 사용자로 바꾸고, 에이전트를 특정 폴더에서 시작하려면 WorkingDirectory를 그 프로젝트 디렉터리로 조정하세요.

# /etc/systemd/system/tacticremote.service
[Unit]
Description=Tactic Remote server
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser
ExecStart=/usr/bin/npx tacticremote
Restart=on-failure
RestartSec=5
Environment=HOME=/home/youruser
 
[Install]
WantedBy=multi-user.target

활성화 및 시작:

sudo systemctl daemon-reload
sudo systemctl enable tacticremote
sudo systemctl start tacticremote
sudo systemctl status tacticremote

언제든 로그 확인:

journalctl -u tacticremote -f

유닛 파일에 관한 몇 가지 참고 사항:

• After=network-online.target은 서버 시작 전 네트워크가 준비되도록 보장합니다. 부팅 시 Cloudflare Tunnel 연결이 필요한 경우 중요합니다.
• Restart=on-failure와 5초 지연은 순간적인 오류에서 자동 복구되도록 하되, 즉각적인 재시작 루프를 방지합니다.
• npx가 /usr/bin/npx에 없다면 which npx로 올바른 경로를 찾아 ExecStart를 수정하세요. npx 대신 npm install -g tacticremote로 글로벌 설치한 경우 tacticremote 바이너리의 전체 경로를 사용할 수도 있습니다.
• Environment=HOME 줄은 sudo 권한 상승으로 실행할 때 Node/npm이 올바른 사용자 홈 아래에서 캐시와 글로벌 패키지를 찾을 수 있도록 합니다.

Cloudflare Tunnel로 iPhone 연결하기

원격 서버에는 공유 LAN이 없으므로 mDNS 검색이 작동하지 않습니다. 이 구성에서의 연결 방식은 Cloudflare Tunnel입니다.

Tactic Remote에는 Cloudflare Tunnel이 내장되어 있어 — 터널 자체를 위한 별도 cloudflared 설치가 필요 없습니다. 서버 시작 시 플래그를 전달해 활성화하세요:

npx tacticremote --tunnel --api-key YOUR_SECRET_KEY

또는 systemd로 실행 중이라면 유닛 파일을 수정하세요:

ExecStart=/usr/bin/npx tacticremote --tunnel --api-key YOUR_SECRET_KEY

Cloudflare Tunnel이 활성화되면 서버가 trycloudflare.com URL을 출력합니다:

Cloudflare Tunnel active: https://example-random-name.trycloudflare.com
API Key: tr_xxxxxxxxxxxxxxxxxxxx

iPhone에서:

1. Tactic Remote 열기
2. Add Host를 탭하고 Manual 선택
3. 호스트 주소에 trycloudflare.com URL 입력
4. 서버 출력의 API Key 입력
5. Connect 탭

연결은 Cloudflare를 통해 종단간 암호화됩니다. 코드와 터미널 출력은 Tactic Remote의 클라우드 릴레이를 전혀 거치지 않습니다 — 그런 릴레이는 존재하지 않습니다. 트래픽은 서버에서 Cloudflare 엣지로, 터널을 통해 iOS 앱으로 직접 전달됩니다.

영구적인 설정을 원한다면, 임시 trycloudflare.com 주소 대신 자체 도메인에 연결된 명명된 Cloudflare Tunnel 사용을 권장합니다. 이렇게 하면 재시작 후에도 페어링 URL이 유지됩니다. 해당 방법은 Cloudflare Tunnel 설정 가이드를 참고하세요.

보안 참고 사항

이 구성 — 원격 서버, Cloudflare Tunnel, API Key — 에서의 보안 특성:

• 서버의 포트 8765를 인터넷에 열 필요가 없습니다. Cloudflare Tunnel은 서버에서 Cloudflare 엣지로의 아웃바운드 연결을 생성하므로 인바운드 포트를 노출할 필요가 없습니다.
• API Key 인증을 통해 키를 아는 기기만 연결할 수 있습니다. 강력한 키를 설정하거나 자동 생성된 키를 사용하세요.
• LAN 모드는 일반 ws://를 사용합니다. 원격 서버에서는 LAN 모드를 사용하지 않으므로 해당 사항이 없습니다 — Cloudflare Tunnel 트래픽은 TLS입니다.

서버가 프라이빗 VPC 안에 있다면, Cloudflare Tunnel이 방화벽에 구멍을 뚫지 않고 접근하는 방법입니다.

서버에서 멀티 에이전트 사용

원격 서버 설정은 로컬 Mac이나 Windows 호스트와 동일한 에이전트 선택을 지원합니다. iOS 앱에서 새 세션을 생성할 때 세션별 선택기를 통해 서버에 설치된 에이전트 중 Claude Code, Codex, Amp 중 하나를 선택할 수 있습니다.

각 세션은 독립적입니다. Claude Code 세션이 장시간 테스트 작업을 실행하는 동시에 Codex 세션이 다른 브랜치에서 실행될 수 있습니다. iOS 앱에서 세션 간 전환이 가능합니다.

이 설정에서도 푸시 알림이 작동합니다. 에이전트가 완료되거나, 승인을 위해 일시 정지하거나, 예기치 않게 종료되면 iPhone으로 알림이 옵니다. 계속 지켜보기보다 간헐적으로 확인하는 장시간 작업에서 핵심 기능입니다 — 앱을 열어 두지 않아도 됩니다.

Docker에서 실행하기

서버 환경이 Docker 기반이라면 컨테이너 안에서 npx tacticremote를 실행할 수 있습니다. 주요 고려 사항:

• 컨테이너에 에이전트(Claude Code, Codex, Amp)가 설치되고 인증된 상태여야 합니다
• LAN 모드를 사용하는 경우 포트 8765를 노출해야 합니다 (Cloudflare Tunnel에는 불필요)
• Cloudflare Tunnel을 위해 컨테이너에 아웃바운드 인터넷 접근이 필요합니다
• 컨테이너 내 프로세스 관리는 systemd 대신 CMD 또는 수퍼바이저를 사용하세요

최소한의 Dockerfile 단편:

RUN npm install -g tacticremote
CMD ["tacticremote", "--tunnel", "--api-key", "YOUR_SECRET_KEY"]

에이전트의 영속 인증 정보(예: Claude Code의 ~/.claude 디렉터리)는 컨테이너 재시작 후에도 유지되도록 볼륨으로 마운트해야 합니다.

주의 사항

에이전트는 서버에 자체 인증 정보가 필요합니다. npx tacticremote는 Claude Code, Codex, Amp의 인증을 처리하지 않습니다. Tactic Remote가 세션을 시작하기 전에 해당 에이전트들이 서버 머신에 설치 및 로그인된 상태여야 합니다.

Cloudflare Tunnel은 약간의 지연을 추가합니다. 대화형 사용 시 대부분 체감되지 않습니다 (대부분 지역에서 100ms 미만). 처리량이 매우 높은 터미널 출력에서는 눈에 띌 수 있습니다. LAN 모드가 사용 가능한 경우 더 빠르지만, LAN 모드는 폰과 서버가 같은 네트워크에 있어야 합니다.

Node.js 버전이 중요합니다. 최소 Node 16이 필요하며, Node 20 LTS를 권장합니다. node --version으로 확인하세요.

npx는 최초 실행 시 패키지를 다운로드합니다. 서버에 엄격한 이그레스 규칙이 있다면 npm 레지스트리를 허용 목록에 추가하세요. 또는 npm install -g tacticremote로 글로벌 설치한 뒤 systemd 유닛 파일에서 tacticremote를 직접 사용하세요.

Linux에서는 세션 지속성을 위해 tmux를 사용합니다. tmux가 설치되어 있는지 확인하세요 (apt install tmux 또는 이에 상응하는 명령). tmux가 없으면 재연결 시 세션이 유지되지 않습니다.

이 설정에서 iOS 앱의 무료 플랜은 충분히 기능합니다. Chat Mode, Terminal Mode, 푸시 알림, 멀티 에이전트가 무료로 제공됩니다. Pro는 추가 기능을 제공합니다. 요금제: 무료 / Pro 월 $2.99 / 연 $19.99.

항상 켜진 서버에서 에이전트를 실행하는 것은 원격 제어 모델의 가장 효과적인 활용 방식입니다: 에이전트는 밤새, 회의 중에도, 비행 중에도 작업하고, 폰은 언제든 확인할 수 있는 창이 됩니다.

처음 설정하는 경우, 기본적인 npx tacticremote --tunnel --api-key YOUR_SECRET_KEY 방식으로 시작해 iPhone에서 종단간 연결을 확인한 뒤, 안정성을 위해 systemd 서비스를 추가하세요.

관련 문서

• iPhone으로 Claude Code 실행하기 — 기본 설정 가이드
• Cloudflare Tunnel 설정 — 명명된 터널, 커스텀 도메인, 영구 구성
• 크로스 플랫폼 설계 선택 — 동일한 iOS 앱이 Mac, Windows, Linux, CLI에서 작동하는 이유