맥미니 서버 SSH 환경에서 Claude Code 인증 유지하며 작업하기 (feat. tmux)
카페에서 맥북 열고 신나게 작업하려는데 또 인증이 풀려있으면 진짜 깊은 빡침이 밀려온다.
맥미니 서버에서 Claude Code를 쓸 때마다 툭하면 인증이 풀려서 뒷목을 잡곤 했다. 그러다 결국 tmux 하나로 이 지옥을 탈출한 이야기다.
SSH + AI CLI = 인증 지옥
현재 방구석에서 M2 맥미니와 M4 맥미니, 두 대를 홈 서버로 굴리고 있다. 로컬 LLM이나 덩치 큰 AI 에이전트들은 전부 이 녀석들에게 몰아주고, 밖에서는 가벼운 M1 맥북에어로 SSH 접속해서 코딩하는 구조다.
처음엔 이게 그렇게 꿀일 수가 없었다. 맥북에어는 가볍게 들고 다니면서 발열도 없고, 리소스 무지막지하게 퍼먹는 빌드나 모델 추론은 집에서 맥미니들이 묵묵히 처리해 줬으니까.
그런데 Claude Code를 메인 도구로 쓰기 시작하면서부터 아주 골 때리는 복병을 만났다.
“Not logged in · Please run /login”
진짜 이 망할 메시지를 하루에 몇 번이나 봤는지 모르겠다.
SSH로 붙어서 claude 띄워놓고 작업을 잔뜩 시켜뒀는데, 잠깐 화장실 다녀오거나 와이파이가 튀어서 SSH 연결이 끊기면? 다시 접속했을 때 로그인 인증을 맨 처음부터 다시 밟아야 한다.
특히 Claude Code 같은 CLI 툴은 브라우저를 띄워서 OAuth 승인을 받는 방식인데, 내 맥미니 홈서버는 모니터도 안 달린 Headless 환경이다. 터미널에 뜨는 기나긴 인증 링크를 복사해서 맥북 브라우저에 붙여넣고, 승인 버튼 누르고, 다시 터미널로 돌아오는 이 짓을 하루에 서너 번씩 반복하다 보면 멘탈이 나간다.
게다가 더 짜증 나는 건, 이 인증 링크가 쓸데없이 길다는 점이다. 터미널 창 너비를 넘어가면서 줄 바꿈이 생기는데, 이걸 마우스로 긁어서 복사하면 중간에 공백이 섞여 들어간다. 브라우저 주소창에 넣으면 깨진 URL이라고 에러가 뜨고, 터미널과 브라우저를 오가며 수동으로 공백 지우기를 반복하다 보면 혈압이 절로 오른다.
“아니, 서버는 방구석에서 멀쩡히 켜져 있는데, 내 SSH 창 좀 닫혔다고 너까지 로그아웃되는 게 말이 되냐고??”
iOS 개발할 때는 시뮬레이터가 뻗어도 Xcode 세션이 증발하진 않았는데, 서버 쪽 환경은 정말 호락호락하지 않았다.
원인: SSH 세션이 죽으면 자식 프로세스도 같이 증발한다
혼자서 머리 싸매다가 Gemini한테 물어봤더니 아주 명쾌한 답이 돌아왔다.
Claude Code는 OAuth 기반으로 동작한다. 브라우저에서 승인하면 OAuth 토큰을 받아오고, 이 토큰을 메모리에 들고 API와 통신하는 구조다. 그런데 문제는 SSH 세션이 끊어질 때 발생한다.
SSH로 접속해서 실행한 모든 프로세스는 그 SSH 세션의 ‘자식 프로세스’로 종속된다. 그런데 네트워크가 끊기거나 창을 닫아서 세션이 종료되면, OS는 그 아래에 매달려 있던 자식 프로세스들에게 SIGHUP(Hangup) 신호를 일제히 날려버린다. 당연히 Claude Code도 예외 없이 즉사한다. 프로세스가 강제 종료되니 메모리에 쥐고 있던 OAuth 인증 상태도 허공으로 날아가는 셈이다.
즉, “인증 유효기간이 끝난 것”이 아니라 인증을 쥐고 있던 프로세스 자체가 살해당한 것이었다.
답은 명확했다. SSH 접속이 끊기든 말든, 프로세스를 서버 백그라운드에 영원히 살려두면 된다.
해결책: tmux로 세션을 불사신으로 만들자
그래서 꺼내 든 카드가 바로 tmux다.
보통 터미널 창 쪼개는 화면 분할용으로 많이들 알고 있지만, 서버 환경에서 tmux의 진짜 진가는 ‘세션 유지(Session Persistence)’에 있다. tmux가 생성한 세션은 SSH 연결과 완전히 독립적으로 돌아간다. 내가 접속을 끊든 맥북을 덮든, tmux 세션 속의 프로세스들은 서버 안에서 숨 쉬며 계속 살아남는다.
한 줄로 비교하면 이렇다:
- tmux 없을 때: SSH 접속 → 열심히 작업 → 와이파이 끊김 → 작업하던 세션 공중분해(눈물)
- tmux 있을 때: SSH 접속 → tmux 세션 진입 → 작업 → 와이파이 끊김 → 세션은 서버에서 멀쩡히 생존 → 다시 접속해서 붙으면 끝(평화)
적용 방법
1단계: tmux 설치
맥미니 서버에 tmux가 안 깔려 있다면 Homebrew로 1초 만에 깔아준다.
brew install tmux
2단계: 작업용 세션 생성
SSH로 접속하자마자 바로 claude를 치지 말고, tmux 세션부터 띄운다.
tmux new -s claude
-s claude는 세션 이름이다. 본인이 알아보기 편한 이름(ai-agent, work 등) 아무거나 붙이면 된다.
화면 맨 아래에 초록색 상태바가 뜨면 tmux의 보호 구역 안으로 무사히 들어온 거다. 이제 마음 편히 Claude Code를 띄우고 최초 인증을 1회 진행한다.
claude
# (최초 1회 브라우저 인증 진행)
3단계: 세션 분리 (Detach)
작업을 걸어두고 카페를 나서야 할 때, 터미널 창의 X 버튼을 그냥 누르면 안 된다. 반드시 세션 분리(Detach)를 해줘야 한다.
Ctrl + b 누르고 → 손 뗀 다음 → d
터미널에 [detached (from session claude)]라는 메시지가 뜨면서 원래의 쉘로 쏙 빠져나온다.
이제 SSH 접속을 끊든, 맥북에어를 접어 가방에 넣든, 와이파이가 끊기든 아무 상관없다. 방구석 맥미니 속에서 Claude Code는 여전히 살아서 돌아가고 있다. 인증 상태도 고스란히 유지된다.
4단계: 다시 붙기 (Attach)
집에 도착해서 작업을 이어가고 싶다면, 다시 SSH 접속 후 명령어 한 줄만 치면 된다:
tmux attach -t claude
마치 타임머신을 탄 것처럼, 아까 작업하던 터미널 화면, 출력 로그, 로그인 인증 상태가 토씨 하나 안 틀리고 그대로 복원된다.
알아두면 요긴한 tmux 명령어
실전에서 쓰다 보면 attach/detach 말고도 손에 익혀두면 삶이 윤택해지는 명령어들이 있다.
# 현재 백그라운드에 살아있는 세션 목록 확인
tmux ls
# 특정 세션 강제 종료 (작업 다 끝나서 날릴 때)
tmux kill-session -t claude
# 세션이 딱 하나만 있을 때 초간단 복귀
tmux attach
# 또는 더 짧게
tmux a
자주 쓰는 단축키도 몇 개 외워두면 터미널 라이프가 편해진다:
| 단축키 | 동작 |
|---|---|
Ctrl+b → d |
세션 분리 (Detach) |
Ctrl+b → c |
새 창(Window) 생성 |
Ctrl+b → n |
다음 창으로 이동 |
Ctrl+b → p |
이전 창으로 이동 |
Ctrl+b → % |
화면 좌우 세로 분할 |
Ctrl+b → " |
화면 상하 가로 분할 |
나 같은 경우 tmux 안에서 윈도우를 여러 개 띄워두고, 1번 윈도우는 Claude Code, 2번은 git 로그 모니터링, 3번은 서버 로그 확인용으로 굴린다. 단축키 하나로 휙휙 넘나드니 작업 효율이 미쳤다.
실제 작업 흐름의 변화
tmux를 세팅하고 나서 내 외출 작업 루틴은 이렇게 바뀌었다:
- 카페에 도착해서 맥북에어로 SSH 접속 →
tmux a - Claude Code한테 무거운 리팩토링이나 테스트 코드 작성을 시켜둠
Ctrl+b, d누르고 맥북 덮은 뒤 여유롭게 커피 한 모금- 집에 와서 다시 SSH 접속 →
tmux a로 결과 확인 - 추가 지시 내리고 필요하면 다시 분리
SSH가 끊어질까 봐 조마조마하거나, 길거리에서 핫스팟 튀었다고 로그인 창 다시 복붙할 필요가 싹 사라졌다. 무엇보다 시간 오래 걸리는 AI 작업을 원격에 던져두고 내 할 일을 할 수 있다는 안정감이 진짜 최고다.
로컬 작업할 때도 필수인 이유
사실 tmux는 꼭 원격 SSH 환경이 아니더라도 로컬 맥북에서 쓸 때도 기가 막힌다.
맥북 기본 터미널에서 Claude Code를 돌리다가 Antigravity나 Ghostty 같은 다른 터미널 앱으로 넘어가고 싶을 때, tmux가 없으면 작업 세션을 그대로 옮겨 올 방법이 없다. 하지만 tmux 위에서 돌리고 있었다면? 그냥 새 터미널 앱 열고 tmux a만 치면 작업하던 상태 그대로 이어받을 수 있다.
실수로 터미널 창을 Cmd+W로 닫아버려도 패닉에 빠질 필요가 없다. tmux 세션은 백그라운드에서 멀쩡히 살아 숨 쉬고 있으니 다시 열어서 붙으면 그만이다(정신건강 보호용 보험).
팁: .zshrc에 단축 함수 걸어두기
매번 tmux attach -t claude 치는 것도 귀찮아서 .zshrc에 단축 함수를 하나 심어뒀다.
# ~/.zshrc
cc() {
tmux attach -t claude 2>/dev/null || tmux new -s claude
}
이렇게 세팅해 두면 터미널 열고 알파벳 딱 두 글자, cc만 치면 된다. 세션이 이미 있으면 알아서 붙고, 없으면 새로 파준다.
마지막 주의점
아무리 tmux가 든든해도 서버 자체가 재부팅되면 세션도 같이 날아간다. 맥미니 macOS 업데이트를 돌리거나 재부팅할 일이 있다면 중요한 세션은 미리 마무리해 두는 게 좋다. tmux-resurrect 같은 플러그인을 붙여서 세션 상태를 디스크에 저장하는 방법도 있긴 한데, 솔직히 홈서버 환경에선 그 정도까지 안 가도 충분했다.
홈서버나 원격 환경에서 AI CLI 도구를 쓴다면 tmux는 선택이 아니라 생존 필수템이다. 5분만 투자해서 세팅해 두면 이후 수백 시간의 스트레스가 날아가니, 아직 안 써봤다면 오늘 당장 써보는 걸 추천한다!