Claude Code를 원격 VPS와 tmux에서 실행하는 방법

문제는 노트북 덮개이지 CLI가 아닙니다

Claude Code는 노트북을 닫기 전까지는 정상적으로 작동합니다. 하지만 노트북을 닫으면 SSH 세션이 종료되고 셸은 SIGHUP 신호를 받으며, 테스트 실행 3분 만에 에이전트도 함께 종료됩니다. CLI는 절전 모드로 전환되지 않는 기기에서 실행해야 하며, SSH 세션의 자식 프로세스가 아닌 터미널 멀티플렉서 내부에서 실행해야 합니다. 이것이 전부이며, 설치 과정보다 tmux를 사용하는 것이 핵심입니다.

이 페이지는 에이전트를 계속 실행해 둘 서버를 운영하는 방법에 관한 내용입니다. 항상 켜 둘 수 있는 Linux 서버가 없다면 이 내용은 적용되지 않습니다. 이것이 유일하고 정직한 전제 조건입니다.

tmux의 실제 동작 원리

SSH로 접속하면 sshd은 셸을 포크(fork)하고 의사 터미널(pseudo-terminal)을 할당합니다. 해당 셸에서 실행하는 모든 프로세스는 그 셸의 자식 프로세스가 됩니다. 연결이 끊기면 커널은 pty를 해제하고, 셸은 SIGHUP 신호를 받으며, 이어서 자식 프로세스들도 종료됩니다. 따라서 오래 실행되는 포그라운드 프로세스도 함께 죽게 됩니다.

tmux는 이러한 소유 구조를 뒤집습니다. 사용자가 입력하는 tmux 명령어는 유닉스 소켓을 통해 터미널과 분리되어 실행 중인 tmux 서버와 통신하는 얇은 클라이언트일 뿐입니다. 세션 내부의 셸은 sshd이 아닌 tmux 서버의 자식 프로세스입니다. SSH 연결을 종료해도 클라이언트는 사라지지만, 서버와 세션, 그리고 작업 중인 에이전트는 계속 실행됩니다. 다시 접속하여 tmux attach를 실행하면 이전과 동일한 셸과 스크롤백 상태로 돌아올 수 있습니다. nohup 또한 연결 끊김에서 살아남을 수는 있지만, 다시 접속할 방법이 없으므로 백그라운드로 전환된 TUI에 다시 붙을 수 없습니다. Claude Code는 대화형 도구이므로, tmux(또는 screen)가 적합한 도구입니다.

서버 사양 산정

CLI는 Node 프로세스일 뿐이며, 서버 자원을 모두 점유하지 않습니다. 서버 자원을 점유하는 것은 빌드, 전체 테스트 스위트, tsc, 언어 서버, Docker 내의 데이터베이스 등 에이전트가 사용자를 대신해 실행하는 작업들입니다. CLI가 아닌 툴체인에 맞춰 사양을 산정하십시오. 스왑을 사용할 계획이 없더라도 반드시 추가하십시오. 스왑은 OOM(Out of Memory)으로 인한 강제 종료를 방지하고 빌드 속도를 늦추는 방식으로 동작하게 합니다.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

디스크 용량도 주의 깊게 살펴야 합니다. 저장소, node_modules, Docker 이미지는 빠르게 쌓입니다. 툴체인이 컨테이너를 넘어 전체 가상 머신, KVM 게스트, 로컬 Kubernetes 노드까지 확장된다면, 도입 전에 해당 환경이 CPU 가상화 확장을 지원하는지 확인하십시오. VPS에서 중첩 가상화 실행하기는 게스트 내부에서 설정하는 것이 아니라 제공자가 활성화해 주어야 하는 기능이기 때문입니다.

루트가 아닌 사용자 우선 생성

전용 홈 디렉터리를 가진 사용자를 생성하고 공개 키를 배치합니다.

sudo adduser --disabled-password --gecos "" agent
sudo install -d -m 700 -o agent -g agent /home/agent/.ssh
sudo cp ~/.ssh/authorized_keys /home/agent/.ssh/authorized_keys
sudo chown agent:agent /home/agent/.ssh/authorized_keys
sudo chmod 600 /home/agent/.ssh/authorized_keys

비밀번호 인증이 백업 수단으로 남아 있는 동안, 두 번째 터미널에서 로그인이 정상적으로 수행되는지 확인하십시오. 만약 Permission denied (publickey) 오류가 발생한다면, 이는 키 자체의 문제라기보다 .ssh 디렉터리의 소유권이나 권한 설정이 잘못되었을 가능성이 큽니다.

의도적으로 agent 사용자는 sudo 그룹에 포함하지 않습니다. 시스템 패키지가 필요한 경우 그때마다 설치하십시오. 이러한 결정 하나만으로도 잘못 입력된 셸 명령어가 호스트 시스템을 손상시킬 수 있는 대부분의 경로를 차단할 수 있습니다.

상시 가동 서버를 위한 SSH 보안 수칙

공용 인터넷에 상시 연결되어 있고, 에이전트와 소스 코드를 보관하는 서버에서 비밀번호 인증을 사용하는 것은 감수할 가치가 없는 위험입니다. 비밀번호 인증을 비활성화하십시오. Ubuntu 24.04와 Debian 13에서는 /etc/ssh/sshd_config가 /etc/ssh/sshd_config.d/*.conf을 포함하므로, 메인 설정을 직접 수정하는 대신 별도의 파일을 생성하십시오:

# /etc/ssh/sshd_config.d/10-hardening.conf
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no

현재 세션을 유지한 채 두 번째 터미널에서 새로운 세션을 테스트하여 설정을 검증하고 다시 불러오십시오:

sudo sshd -t && sudo systemctl restart ssh

Ubuntu 24.04의 주의 사항: sshd는 소켓 활성화 방식으로 동작합니다. 인증 설정은 systemctl restart ssh에 적용되지만, 수신 대기하는 Port를 변경하려면 systemctl daemon-reload 설정과 ssh.socket의 재시작이 필요합니다.

다음은 방화벽입니다. SSH를 활성화하기 전에 허용 규칙을 추가하십시오. 그렇지 않으면 서버 접속이 차단됩니다:

sudo ufw allow OpenSSH
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable

fail2ban을 설치할 때는 이 도구가 제공하는 이점을 명확히 이해하십시오. 비밀번호 인증이 비활성화되면 무차별 대입 공격은 성공할 수 없으며, 이 도구는 실패한 시도 기록이 시스템 저널에 남지 않도록 방지합니다.

# /etc/fail2ban/jail.local
[sshd]
enabled = true
backend = systemd
maxretry = 5
bantime = 1h

마지막으로 sudo apt install unattended-upgrades와 sudo dpkg-reconfigure -plow unattended-upgrades을 사용하여 자동 패치를 설정하십시오. tmux와의 상호작용에 주의하십시오. Unattended-Upgrade::Automatic-Reboot을 켜두면 커널 업데이트 시 서버가 재부팅되어 모든 세션이 종료됩니다. 이 기능을 끄고 작업 중인 프로세스가 없을 때 직접 재부팅 일정을 관리하십시오. 동일한 주의 사항이 릴리스 업그레이드에도 적용됩니다. Ubuntu 24.04에서 26.04로 서버를 이전하면 sshd와 커널이 재시작되므로, 중요한 작업이 포함된 tmux 세션이 없을 때 수행해야 합니다.

Ubuntu에 Node.js 및 Claude Code 설치하기

Claude Code는 Node CLI이므로 최신 버전의 Node가 필요합니다. 배포판 패키지는 버전이 뒤처지는 경우가 많습니다. Ubuntu와 Debian에서는 일반적으로 NodeSource를 사용하며, 서명된 저장소를 제공합니다(apt-key는 더 이상 사용되지 않으므로 사용하지 마십시오).

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version

이제 많은 사용자가 실수하는 부분입니다. CLI는 반드시 agent 사용자로 설치해야 하며, sudo npm -g 권한으로 설치해서는 안 됩니다. root가 소유한 전역 접두사(global prefix)를 사용하면 나중에 권한 오류가 발생하며, npm 캐시에 root 소유 파일이 남게 됩니다. 먼저 npm의 접두사를 사용자 홈 디렉터리로 지정하십시오.

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
claude --version

export 설정은 ~/.profile이 아닌 ~/.bashrc에 추가해야 하며, 파일 상단에 있는 "대화형으로 실행되지 않으면 아무것도 하지 마십시오(If not running interactively, don't do anything)" 가드 코드 위쪽에 위치해야 합니다. tmux는 ~/.bashrc을 읽고 ~/.profile을 건너뛰는 비로그인 셸을 시작할 수 있으며, ~/.profile는 로그인 셸에서만 실행되기 때문입니다. nvm과 같은 버전 관리자를 통해 사용자별 Node를 설치해도 동일한 결과를 얻을 수 있습니다. 어떤 방법을 사용하든 핵심은 npm install -g이 sudo를 필요로 하지 않게 만드는 것입니다. npm은 여전히 정상적으로 작동하며, 현재 문서화된 기본값인 Anthropic의 기본 설치 스크립트를 사용할 수도 있습니다. 설치 방법은 변경될 수 있으므로 붙여넣기 전에 Anthropic의 설치 문서를 확인하십시오.

저장소 내부에서 claude을 실행하여 시작하십시오. 첫 실행 시 인증 과정을 안내합니다. 헤드리스(headless) 환경에는 브라우저가 없으므로, 본인의 로컬 머신에서 열 수 있는 URL과 터미널에 입력할 코드를 제공합니다. (환경 변수에 API 키를 설정하는 방법도 있습니다.) 어떤 방법을 선택하든 자격 증명은 서버에 저장되며, 이제 많은 사용자가 간과하는 부분으로 넘어갑니다.

폭발 반경에 대한 논의

셸 접근 권한을 가진 에이전트는 곧 셸 그 자체입니다. 해당 에이전트가 실행되는 사용자가 읽을 수 있는 모든 것을 읽을 수 있고, 해당 사용자가 쓰기 권한을 가진 모든 곳에 데이터를 밀어 넣을 수 있습니다. 이는 도구에 대한 비판이 아니라 도구의 정의이며, 개별 설정보다 에이전트가 실행되는 계정이 더 중요한 이유입니다.

• 전용 비권한 사용자. sudo 그룹에 포함되지 않아야 하며, 본인의 계정과 홈 디렉터리를 공유해서는 안 됩니다.
• 서버 내 운영 환경 자격 증명 금지. 운영용 키를 보관하는 ~/.aws/credentials가 없어야 하고, 운영 환경에서 복사해 온 .env도 없어야 하며, 중요한 데이터에 쓰기 권한을 가진 데이터베이스 비밀번호도 없어야 합니다. 에이전트에는 스테이징 환경용 자격 증명이나 읽기 전용 자격 증명을 부여하십시오.
• 범위가 제한된 토큰. 단일 저장소로 제한된 세밀한 GitHub 토큰을 사용하거나, 읽기 권한만 필요할 때는 deploy key를 사용하십시오.

Claude Code는 권한 확인 메시지를 완전히 건너뛰는 플래그를 제공합니다. 개인 노트북이나 일회성 프로젝트라면 사용자가 결정할 문제이지만, 토큰이 보관된 서버에서 이 플래그를 사용하면 잘못 해석된 명령과 git push --force 사이를 막아주는 마지막 방어선이 사라집니다. 건너뛰게 될 확인 메시지는 단순히 모든 것을 허용하거나 거부하는 방식이 아니며, 새로운 기본값으로 도입되는 자동 모드를 고려할 때, 모니터링하지 않는 서버가 어떤 권한 모드로 고정되어야 하는지 파악하는 것이 중요합니다. 해당 플래그가 실제로 무엇을 변경하는지, 그리고 내장 샌드박스부터 일회용 VPS까지 플래그를 사용하는 에이전트를 어떻게 격리할 것인지는 서버에서 Claude Code를 안전하게 실행하는 방법에서 다룹니다.

Deploy key와 SSH agent forwarding 비교

노트북의 키를 git이 사용할 수 있도록 ssh -A을 사용하고 싶은 유혹이 들 수 있습니다. 이것이 무엇을 허용하는지 이해해야 합니다. agent forwarding은 로컬 SSH 에이전트의 소켓을 서버에서 해당 사용자로 실행 중인 프로세스에 노출합니다. 에이전트를 포함하여 agent로 실행되는 모든 프로세스는 사용자가 연결되어 있는 동안 접근 가능한 모든 호스트에 대해 키 서명을 요청할 수 있습니다. 이는 단순히 "git이 특정 저장소를 pull하게 한다"는 수준을 훨씬 넘어섭니다.

대신 서버에서 키를 생성하고, 이를 저장소별 deploy key로 등록하십시오(에이전트가 push해야 하는 경우에만 쓰기 권한 부여). 또한 서버에서 생성된 커밋을 식별할 수 있도록 git identity를 설정하십시오.

ssh-keygen -t ed25519 -C "agent deploy key" -f ~/.ssh/id_ed25519_repo
cat ~/.ssh/id_ed25519_repo.pub   # paste into the repo's Deploy Keys
git config --global user.name "Agent (build box)"
git config --global user.email "agent@example.com"

tmux 워크플로우

설치 후(sudo apt install tmux), 최소한의 ~/.tmux.conf 설정을 적용합니다:

set -g mouse on
set -g history-limit 50000
set -g default-terminal "tmux-256color"

일상적인 사용은 다음 네 가지 명령어로 충분합니다:

tmux new -A -s claude     # attach to session "claude", creating it if absent
# ...run `claude` inside it, work normally...
# Ctrl-b then d           -> detach; everything keeps running
tmux ls                   # list sessions
tmux attach -t claude     # reattach, from this machine or any other
tmux kill-session -t claude

tmux new -A -s claude는 반드시 기억해야 할 명령어입니다. 세션이 존재하면 연결하고, 없으면 새로 생성하므로 하루를 시작할 때나 연결이 끊긴 후 복구할 때 모두 유용합니다. 이 명령어를 별칭(alias)으로 등록하십시오. 세션 내부에서 Ctrl-b c은 창을 열고, Ctrl-b n와 Ctrl-b p는 창을 전환하며, Ctrl-b [은 복사 모드로 진입하여 이전 내용을 스크롤할 수 있게 합니다(q로 종료).

종료하지 않고 유지하는 세션에 대해 한 가지 주의할 점이 있습니다. 에이전트는 매 턴마다 전체 대화 내용을 다시 전송하므로, 일주일 내내 세션을 띄워두기 전에 장기 실행되는 Claude Code 세션의 토큰 소모 원인을 먼저 확인하십시오.

실패 유형

"세션이 사라졌습니다." tmux ls에서 no server running on /tmp/tmux-1000/default가 출력됩니다. 이는 거의 항상 프로세스가 tmux 내부에서 실행되지 않았음을 의미합니다. SSH로 접속한 뒤 claude를 직접 실행하면 연결이 끊길 때 프로세스도 함께 종료됩니다. 복구할 방법은 없습니다. 이를 방지하는 습관은 다음과 같습니다. 로그인할 때마다 가장 먼저 tmux new -A -s <project>를 실행하십시오.

창이 아주 작게 줄어듭니다. tmux는 세션 크기를 가장 작게 연결된 클라이언트에 맞춥니다. 따라서 다른 기기에서 연결된 상태로 방치된 클라이언트가 있다면 화면이 찌그러집니다. 연결할 때 다른 클라이언트를 강제로 종료하십시오: tmux attach -d -t claude.

빌드 도중 Killed가 출력됩니다. 스택 트레이스 없이 단 한 단어만 출력됩니다. sudo dmesg -T | grep -i -E 'out of memory|killed process'로 확인하십시오. 커널의 OOM killer가 가장 큰 프로세스를 강제 종료한 것입니다. Node의 경우 FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory가 나타날 수도 있습니다. 해결 순서는 다음과 같습니다. 스왑을 추가하고(위 참조), 테스트 및 컴파일러 병렬 처리를 제한하며, NODE_OPTIONS=--max-old-space-size=...로 Node의 힙 크기를 늘리거나, VPS 사양을 높이십시오. OOM killer는 빌드 프로세스 대신 tmux server를 선택할 수도 있으며, 이 경우 세션 전체가 사라집니다. systemd-oomd이 실행 중이라면 사용자 슬라이스 전체를 종료하여 같은 결과를 초래할 수 있습니다.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. root 소유의 경로에 전역으로 설치된 경우입니다. 위에서 설명한 ~/.npm-global 경로를 사용하십시오. 이미 sudo npm를 실행한 적이 있다면 Your cache folder contains root-owned files가 나타날 수 있습니다. sudo chown -R $(id -u):$(id -g) ~/.npm으로 복구하십시오.

claude: command not found가 간헐적으로 발생합니다. PATH 내보내기(export) 설정이 ~/.bashrc 파일 내 "대화형으로 실행되지 않으면 아무것도 하지 마라"는 가드 문구 아래에 위치하여, 비대화형 셸이 이를 건너뛰기 때문입니다. 해당 설정을 가드 문구 위로 옮기고 ~/.profile이 아닌 ~/.bashrc에 유지하십시오. tmux는 비로그인 셸을 시작할 수 있는데, 이 셸은 ~/.bashrc를 읽고 ~/.profile는 전혀 참조하지 않기 때문입니다.

연결 후 색상이 깨집니다. TERM 설정이 일치하지 않는 경우입니다. 위에서 설명한 default-terminal 줄을 추가하면 해결됩니다.

재부팅 후 세션이 사라집니다. 버그가 아닙니다. tmux 서버는 하나의 프로세스이므로 재부팅 시 종료됩니다. uptime을 확인하십시오.

규모가 커질 때 발생하는 문제

더 많은 프로젝트. 저장소마다 하나씩 tmux 세션을 만들고 이름을 지정하십시오. 그러면 tmux ls가 대시보드 역할을 합니다. 명명 규칙을 지키지 않으면 세션이 0, 1, 2처럼 무질서하게 늘어납니다. 여러 세션을 동시에 실행할 때 이들은 격리된 상태로 작동할 필요가 없습니다. 같은 서버 내의 한 세션에서 다른 세션으로 메시지를 전달할 수 있기 때문입니다. 이는 긴 리팩토링 작업을 수행 중인 에이전트가 다른 에이전트에게 테스트 실행을 요청할 때 유용합니다. 포트도 마찬가지로 무분별하게 늘어납니다. 6개의 저장소가 모두 :3000 포트를 사용하려 한다면, 수동으로 포트를 할당하는 것을 멈추고 Docker Compose 기반의 Traefik 리버스 프록시를 사용하여 호스트 이름별로 요청을 분기해야 합니다.

더 많은 인원. tmux 소켓은 사용자별로 생성되므로, 같은 서버에 접속한 두 개발자는 각자의 tmux 서버를 가지며 서로의 세션을 볼 수 없습니다. 공유 소켓을 통해 하나의 세션을 공유하면 모든 사용자가 동일한 Unix 사용자로 같은 셸에 입력하게 되며, 이는 감사 및 권한 측면에서 문제를 야기합니다. 사용자를 분리하는 것이 가장 지루하지만 올바른 해결책입니다.

비대면 작업. tmux는 사용자가 직접 접속(attach)하는 대화형 세션을 위한 도구입니다. 아무도 지켜보지 않는 상태에서 일정에 따라 실행되는 작업은 systemd 유닛과 타이머로 관리해야 합니다. 이를 통해 로깅, 재시작 정책, 부팅 시 자동 실행 기능을 기본적으로 제공받을 수 있습니다. cron 형태의 작업을 실행하기 위해 tmux를 사용하는 것은 해당 작업이 서비스로 전환되어야 한다는 신호입니다.

마지막으로, 에이전트가 시작하는 개발 서버는 0.0.0.0이 아닌 127.0.0.1에 바인딩하고, ufw에서 포트를 개방하는 대신 SSH 터널(ssh -L 3000:127.0.0.1:3000 agent@your-server)을 통해 접속하십시오. 6개 이상의 포트를 포워딩하거나 스마트폰과 노트북 모두에서 동일한 미리보기 화면을 확인해야 한다면, 그 앞에 VPS에 직접 호스팅하는 WireGuard VPN을 두십시오. 개발 서버는 사설 인터페이스에 바인딩되고, ufw는 공용 인터페이스로부터의 모든 접근을 차단합니다. 방화벽은 구멍을 뚫지 않을 때만 효과가 있습니다.

Claude Code만이 유일한 선택지는 아닙니다. VPS에서 코딩 AI 에이전트 실행하기를 통해 Aider나 Goose와 같은 다른 도구들도 비교해 보십시오.

FAQ

SSH 연결이 끊겨도 Claude Code는 계속 실행되나요?

tmux 내부에서 실행했을 경우에만 그렇습니다. SSH 셸에서 직접 실행한 프로세스는 해당 셸의 자식 프로세스이므로, 연결이 끊기면 pty와 함께 종료됩니다. tmux 내부에서 실행하면 셸은 분리된 tmux 서버에 속하게 되므로, 에이전트는 작업을 계속 수행하며 tmux attach를 통해 다시 접속하면 이전 스크롤 기록을 그대로 확인할 수 있습니다. 로그인할 때마다 tmux new -A -s <project>을 첫 번째 명령어로 실행하면 이 문제는 해결됩니다.

sudo npm install -g를 사용하여 CLI를 설치해야 하나요?

아니요. root 소유의 전역 접두사를 사용하면 나중에 설치할 때 EACCES 오류가 발생하며 npm 캐시에 root 소유 파일이 생성됩니다. npm의 접두사를 ~/.npm-global으로 설정하거나 nvm 같은 버전 관리자를 사용하십시오. 권한이 없는 agent 사용자로 설치하고, ~/.bashrc의 대화형 가드 위쪽에 ~/.npm-global/bin를 PATH으로 내보내십시오. 이미 sudo npm를 한 번 실행했다면 sudo chown -R $(id -u):$(id -g) ~/.npm으로 캐시를 복구하십시오.

에이전트가 실행 중인 서버에서 ssh -A 에이전트 포워딩을 사용하는 것이 안전한가요?

이는 작업에 필요한 것보다 훨씬 많은 권한을 부여합니다. 포워딩을 사용하면 로컬 SSH 에이전트의 소켓이 해당 사용자로 실행 중인 모든 프로세스에 노출되므로, 서버에 있는 어떤 프로세스든 사용자가 연결되어 있는 동안 접근 가능한 모든 호스트에 대해 키 서명을 요청할 수 있습니다. 서버에서 ed25519 키를 생성하고 이를 저장소별 배포 키로 등록하십시오. 에이전트가 실제로 푸시를 수행해야 하는 경우에만 쓰기 권한을 부여하십시오.

빌드 시 Killed만 출력되는 이유는 무엇인가요?

스택 트레이스 없이 한 단어만 출력되는 것은 커널의 OOM killer가 작동했기 때문입니다. sudo dmesg -T | grep -i -E 'out of memory|killed process'으로 이를 확인하십시오. Node 환경에서는 대신 JavaScript heap out of memory이 보일 수 있습니다. 다음 해결책을 순서대로 시도하십시오: 스왑 파일을 추가하고, 테스트 및 컴파일러 병렬 처리를 제한하며, NODE_OPTIONS=--max-old-space-size=...을 높인 뒤 VPS 사양을 올리십시오. OOM killer가 빌드 프로세스가 아닌 tmux 서버를 선택하여 전체 세션이 종료될 수 있음에 유의하십시오.

tmux와 systemd 서비스 중 무엇을 사용해야 하나요?

tmux는 사용자가 직접 접속하여 지켜보고 입력하는 대화형 세션에 적합하며, 에이전트 세션이 바로 여기에 해당합니다. 아무도 지켜보지 않는 상태에서 일정에 따라 실행되는 작업은 systemd 유닛과 타이머로 관리해야 합니다. 이 경우 로깅, 재시작 정책, 부팅 시 자동 실행 기능을 기본적으로 제공받을 수 있습니다. cron 형태의 작업을 실행하기 위해 tmux를 사용하려 한다면, 해당 작업은 서비스로 만드는 것이 좋습니다.