Claude Code'u Uzak VPS Sunucusunda tmux ile Çalıştırma

Sorun dizüstü bilgisayarın kapağı, CLI değil

Claude Code dizüstü bilgisayarınızda siz kapağı kapatana kadar sorunsuz çalışır: SSH oturumu sonlanır, kabuk (shell) bir SIGHUP sinyali alır ve test çalışmasının üçüncü dakikasındaki aracı (agent) onunla birlikte ölür. CLI'ı asla uyku moduna geçmeyen bir makinede, süreçleri SSH oturumunuzun alt süreçleri olmayan bir terminal çoğullayıcısı (terminal multiplexer) içinde çalıştırın. Tüm mesele budur; yükü taşıyan kısım kurulum değil, tmux'tır.

Bu sayfa, üzerinde araçlar çalışır durumda bırakacağınız bir sunucunun yönetimi hakkındadır. Eğer açık bırakabileceğiniz bir Linux sunucunuz yoksa, bu anlattıklarımızın hiçbiri geçerli değildir. Bu, tek dürüst ön koşuldur.

tmux gerçekte ne yapar

SSH ile bağlandığınızda, sshd bir kabuk (shell) oluşturur ve ona bir sözde uçbirim (pseudo-terminal) atar; bu kabuktan başlattığınız her şey onun alt sürecidir. Bağlantıyı kopardığınızda çekirdek pty'yi sonlandırır, kabuk SIGHUP sinyali alır ve sırayla kendi alt süreçlerini kapatır. Uzun süre çalışan ön plan süreçleri bu nedenle ölür.

tmux sahiplik yapısını tersine çevirir. Yazdığınız tmux komutu, uçbiriminizden bağımsız çalışan bir tmux sunucusu ile unix soketi üzerinden haberleşen ince bir istemcidir. Bir oturum içindeki kabuklar, sshd'ün değil, bu sunucunun alt süreçleridir. SSH bağlantısını kestiğinizde istemci kapanır ancak sunucu, oturum ve işlem ortasında kalan aracı çalışmaya devam eder. Yeniden bağlandığınızda, tmux attach komutuyla aynı kabuğa ve aynı kaydırma geçmişine geri dönersiniz. nohup de bağlantı kopmalarından sağ çıkar ancak size geri dönme imkanı tanımaz; arka plana atılmış bir TUI'ye yeniden bağlanamazsınız. Claude Code etkileşimlidir; tmux (veya screen) bu iş için doğru araçtır.

Sunucu boyutlandırma

CLI bir Node sürecidir; makineyi dolduran şey bu değildir. Makineyi dolduran, sizin adınıza çalıştırılan aracılardır: bir derleme, kapsamlı bir test paketi, tsc, bir dil sunucusu veya Docker üzerinde çalışan bir veritabanı. Boyutlandırmayı CLI için değil, araç zinciri için yapın. Asla kullanmayacak olsanız bile swap alanı ekleyin; bu, ani bir OOM kill durumunu yavaş bir derleme sürecine dönüştürür:

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

Diski de izleyin: depolar, node_modules ve Docker imajları hızla birikir. Eğer araç zinciri container'ların ötesine geçip tam sanal makineler, bir KVM konuğu veya yerel bir Kubernetes düğümü kullanıyorsa, taahhütte bulunmadan önce planın CPU sanallaştırma uzantılarını desteklediğinden emin olun. Çünkü VPS üzerinde iç içe sanallaştırma çalıştırma, içeriden açabileceğiniz bir özellik değil, sağlayıcının sizin için etkinleştirmesi gereken bir durumdur.

İlk adım olarak root olmayan bir kullanıcı oluşturma

Kendi ev dizinine sahip özel bir kullanıcı oluşturun ve genel anahtarınızı ilgili konuma yerleştirin:

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

İşleme devam etmeden önce ikinci bir terminalden giriş yapmayı deneyin; parola ile kimlik doğrulama hala yedek olarak mevcutken bu testi yapmanız önemlidir. Eğer Permission denied (publickey) hatası alırsanız, sorun genellikle anahtarın kendisinden ziyade .ssh dizininin sahiplik veya izin ayarlarından kaynaklanır.

agent kullanıcısı, bilinçli olarak sudo grubuna dahil edilmemiştir. Bir sistem paketi gerektiğinde kurulumu siz yaparsınız. Bu karar, hatalı bir kabuk komutunun ana makineye zarar vermesini önleyen en önemli güvenlik önlemidir.

Sürekli çalışan bir sunucu için SSH hijyeni

İnternete açık, üzerinde SSH agent ve kaynak kodlarınızı barındıran bir makinede parola ile kimlik doğrulaması yapmak, alınmaması gereken bir risktir. Bu özelliği kapatın. Ubuntu 24.04 ve Debian 13 üzerinde /etc/ssh/sshd_config, /etc/ssh/sshd_config.d/*.conf dizinini içerir; bu nedenle ana yapılandırma dosyasını düzenlemek yerine bu dizine bir dosya ekleyin:

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

Mevcut oturumunuzu açık tutarak ikinci bir terminalden test yapın ve ardından yapılandırmayı doğrulayıp yeniden yükleyin:

sudo sshd -t && sudo systemctl restart ssh

Ubuntu 24.04 üzerinde önemli bir ayrıntı: sshd soket tabanlı olarak etkinleştirilir. Kimlik doğrulama ayarları systemctl restart ssh üzerinde geçerli olur, ancak dinleme Port üzerindeki bir değişiklik, systemctl daemon-reload ve ssh.socket servisinin yeniden başlatılmasını da gerektirir.

Ardından güvenlik duvarı ayarlarını yapın. SSH erişimine, güvenlik duvarını etkinleştirmeden önce izin verin; aksi takdirde sunucuya erişiminizi kaybedersiniz:

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

fail2ban kurulumunu, sağladığı faydayı bilerek yapın: parola ile kimlik doğrulama kapalı olduğunda kaba kuvvet saldırıları zaten başarılı olamaz; bu araç yalnızca başarısız denemeleri günlük kayıtlarınızdan uzak tutar.

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

Son olarak, sudo apt install unattended-upgrades ve sudo dpkg-reconfigure -plow unattended-upgrades ile otomatik yama yönetimini yapılandırın. tmux ile olan etkileşime dikkat edin: Unattended-Upgrade::Automatic-Reboot seçeneği etkinleştirildiğinde, bir çekirdek güncellemesi sunucuyu yeniden başlatır ve tüm oturumları sonlandırır. Bu seçeneği kapalı tutun ve yeniden başlatma işlemini, hiçbir işlem çalışmadığı bir zamanda kendi planınıza göre gerçekleştirin. Aynı dikkat, sürüm yükseltme işlemleri için de geçerlidir: sunucuyu Ubuntu 24.04 sürümünden 26.04 sürümüne taşımak, sshd ve çekirdeği yeniden başlatır; bu nedenle bu işlem, tmux oturumlarınızda önemli bir çalışma bulunmadığı bir zaman diliminde yapılmalıdır.

Ubuntu üzerinde Node.js ve Claude Code kurulumu

Claude Code bir Node CLI aracıdır, bu nedenle güncel bir Node sürümüne ihtiyacınız vardır. Dağıtım paketleri genellikle geriden gelir; Ubuntu ve Debian üzerinde yaygın yöntem NodeSource kullanmaktır. Bu yöntem imzalı bir depo sağlar (apt-key artık kullanılmamaktadır):

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

Şimdi insanların hatalı yaptığı kısım: CLI aracını agent kullanıcınız olarak kurun, asla sudo npm -g ile kurmayın. root sahipliğinde bir global önek (prefix), daha sonra izin hatalarına yol açar ve npm önbelleğinde root sahipliğinde dosyalar bırakır. Öncelikle npm önekini kullanıcının ev dizinine yönlendirin:

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

Dışa aktarma (export) işlemi ~/.profile dosyasına değil, ~/.bashrc dosyasına eklenmelidir. Bu satır, dosyanın üst kısımlarında bulunan "Etkileşimli değilse hiçbir şey yapma" korumasının üzerine yerleştirilmelidir: tmux, ~/.bashrc dosyasını okuyan ve ~/.profile dosyasını atlayan etkileşimli olmayan oturumlar başlatabilir; ~/.profile ise yalnızca oturum açma kabukları için çalışır. nvm gibi bir sürüm yöneticisi aracılığıyla kullanıcı bazlı bir Node kurulumu da aynı sonucu verir; her iki durumda da amaç, npm install -g komutunun asla sudo yetkisine ihtiyaç duymamasını sağlamaktır. npm normal şekilde çalışmaya devam eder veya Anthropic'in şu anki belgelenmiş varsayılan yöntemi olan yerel kurulum betiğini kullanabilirsiniz. Yapıştırmadan önce Anthropic'in kurulum belgelerini kontrol edin, kurulum yöntemleri değişebilir.

Başlatmak için bir depo içerisinde claude komutunu çalıştırın. İlk çalıştırma sizi kimlik doğrulama adımlarına yönlendirir; başsız (headless) bir sunucuda tarayıcı bulunmadığından, süreç size kendi makinenizde açmanız için bir URL ve terminale geri girmeniz gereken bir kod verir. (Diğer yöntem ise ortam değişkenlerinde bir API anahtarı kullanmaktır.) Her iki durumda da bu kimlik bilgisi artık sunucuda barınır; bu da bizi insanların atladığı kısma getirir.

Etki alanı (blast radius) tartışması

Shell erişimine sahip bir aracı, bir shell'dir. Çalıştığı kullanıcının okuyabildiği her şeyi okuyabilir ve yazabildiği her yere veri gönderebilir. Bu, aracın bir eleştirisi değil, tanımıdır; bu nedenle aracın hangi kullanıcı altında çalıştığı, herhangi bir tekil ayardan daha önemlidir.

• Özel, yetkisiz kullanıcı. sudo grubu olmamalı, kendi hesabınızla paylaşılan bir ev dizini bulunmamalıdır.
• Sunucuda üretim (prod) kimlik bilgileri bulundurmayın. Üretim anahtarlarını tutan ~/.aws/credentials dosyaları, üretimden kopyalanmış .env verileri veya kritik öneme sahip herhangi bir yere yazma erişimi olan veritabanı parolaları olmamalıdır. Araca yalnızca staging veya salt okunur kimlik bilgileri verin.
• Kapsamı belirlenmiş token'lar. Tek bir depo ile sınırlandırılmış, ayrıntılandırılmış bir GitHub token'ı; salt okunur erişimin yeterli olduğu durumlarda ise deploy key kullanın.

Claude Code, izin istemlerini tamamen atlayan bir flag ile gelir. Bir dizüstü bilgisayarda veya geçici bir projede bu sizin kararınızdır. Token'lar barındıran bir sunucuda ise bu, yanlış anlaşılan bir komut ile git push --force arasında duran son engeli kaldırır. Atlayacağınız istemler hep ya da hiç mantığıyla çalışmaz; yeni varsayılan olarak gelen otomatik mod ile birlikte, başında olmadığınız bir sunucunun hangi izin moduna sabitlenmesi gerektiğini bilmek önemlidir. Söz konusu flag'in gerçekte neleri değiştirdiği ve bu flag ile çalışan bir aracın, yerleşik sandbox'tan tek kullanımlık bir VPS'e kadar nasıl sınırlandırılacağı Claude Code'u sunucuda güvenli çalıştırma bölümünde ele alınmıştır.

Deploy key ile SSH agent forwarding karşılaştırması

Git'in dizüstü bilgisayarınızdaki anahtarı kullanabilmesi için ssh -A kullanmak cazip gelebilir. Bunun ne anlama geldiğini anlayın: agent forwarding, yerel SSH agent soketinizi sunucudaki o kullanıcı olarak çalışan süreçlere açar. Aracı da dahil olmak üzere agent olarak çalışan her şey, siz bağlı kaldığınız sürece, ulaşabildiği herhangi bir ana bilgisayar için anahtarınızın imza atmasını isteyebilir. Bu, "git bu depoyu çeksin" demekten çok daha fazlasıdır.

Bunun yerine sunucu üzerinde bir anahtar oluşturun, bunu depo bazlı bir deploy key olarak kaydedin (yalnızca aracın yazma yapması gerekiyorsa yazma erişimi verin) ve sunucudan yapılan commit'lerin tanınabilmesi için bir git kimliği ayarlayın:

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 iş akışı

Kurulumu yapın (sudo apt install tmux), ardından minimal bir ~/.tmux.conf yapılandırması oluşturun:

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

Günlük kullanım için dört komut yeterlidir:

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 ezberlenmesi gereken komuttur; oturum mevcutsa ona bağlanır, yoksa yeni bir oturum oluşturur. Böylece hem güne başlarken hem de bağlantı koptuktan sonra geri dönerken tek bir komut kullanılır. Bu komutu bir alias olarak tanımlayın. Oturum içindeyken Ctrl-b c yeni bir pencere açar, Ctrl-b n ve Ctrl-b p pencereler arasında geçiş yapar, Ctrl-b [ ise geriye dönük kaydırma yapmak için kopyalama modunu başlatır (q bu moddan çıkar).

Hiç sonlandırmadığınız oturumlar hakkında bilinmesi gereken bir husus şudur: aracı, her etkileşimde tüm konuşma geçmişini yeniden gönderir. Bu nedenle, bir oturumu bir hafta boyunca açık bırakmadan önce uzun süreli bir Claude Code oturumunun token'larını neye harcadığına göz atın.

Hata modları

"Oturumum kayboldu." tmux ls komutu no server running on /tmp/tmux-1000/default çıktısını veriyor. Bu durum neredeyse her zaman sürecin hiçbir zaman tmux içinde çalışmadığı, SSH ile bağlanıp doğrudan claude komutunu çalıştırdığınız ve bağlantı kesildiğinde sürecin sonlandığı anlamına gelir. Kurtarılacak bir şey yoktur. Bunu önleme alışkanlığı: Her girişten sonraki ilk komut tmux new -A -s <project> olmalıdır.

Bölme (pane) küçücük bir kutuya dönüşüyor. tmux, bir oturumu en küçük bağlı istemciye göre boyutlandırır; bu nedenle başka bir makineden bağlı kalan eski bir istemci ekranı sıkıştırır. Bağlanırken diğerlerini zorla çıkarın: tmux attach -d -t claude.

Derleme işlemi Killed çıktısı veriyor. Tek kelime, yığın izi (stack trace) yok. sudo dmesg -T | grep -i -E 'out of memory|killed process' ile doğrulayın; çekirdek OOM killer en büyük süreci seçmiştir. Node tarafında bunun yerine FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory görebilirsiniz. Sırasıyla çözümler: swap alanı ekleyin (yukarıda), test ve derleyici paralelliğini sınırlayın, Node yığınını NODE_OPTIONS=--max-old-space-size=... ile yükseltin veya VPS boyutunu artırın. OOM killer, derleme süreci yerine tmux sunucusunu da seçebilir ve oturumunuzu onunla birlikte sonlandırabilir; eğer systemd-oomd çalışıyorsa, tüm kullanıcı dilimini (user slice) aynı etkiyle sonlandırabilir.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. root sahipliğindeki bir önek (prefix) içine global kurulum yapılmıştır. Yukarıdaki ~/.npm-global önekini kullanın. Eğer daha önce sudo npm komutunu çalıştırdıysanız Your cache folder contains root-owned files hatasını da görebilirsiniz; sudo chown -R $(id -u):$(id -g) ~/.npm ile onarın.

claude: command not found, ama sadece bazen. PATH dışa aktarma (export) işleminiz ~/.bashrc dosyasında "Etkileşimli çalışmıyorsa hiçbir şey yapma" korumasının altında kalmıştır, bu yüzden etkileşimli olmayan kabuklar bunu atlar. Dışa aktarma işlemini bu korumanın üzerine taşıyın ve ~/.profile yerine ~/.bashrc içinde tutun: tmux, ~/.bashrc dosyasını okuyan ancak ~/.profile dosyasına asla dokunmayan, giriş yapmayan (non-login) kabuklar başlatabilir.

Bağlandıktan sonra bozuk renkler. Bir TERM uyumsuzluğu söz konusudur; yukarıdaki default-terminal satırı bu sorunu çözer.

Yeniden başlatma sonrası oturumlar kayboluyor. Bu bir hata değildir: tmux sunucusu bir süreçtir ve yeniden başlatma onu sonlandırır. uptime dosyasını kontrol edin.

Büyüme sürecinde neler aksar

Daha fazla proje. Her depo için bir tmux oturumu oluşturun ve bunlara depo adını verin; tmux ls bu durumda kontrol paneliniz olur. İsimlendirme disiplinini atlarsanız 0, 1, 2 gibi oturumlarla karşılaşırsınız. Birkaç oturum aynı anda çalıştığında bunların yalıtılmış şekilde çalışması gerekmez; aynı sunucudaki bir oturum diğerine mesaj gönderebilir. Bu, uzun süren bir yeniden düzenleme işlemini yürüten aracın, testleri çalıştırması için ikinci bir araca ihtiyaç duyması durumunda kullanışlıdır. Portlar da benzer şekilde karmaşıklaşır; altı deponun tamamı :3000 portunu kullanmak istediğinde, portları manuel atamayı bırakıp Docker Compose üzerinde bir Traefik reverse proxy'nin ana bilgisayar adına göre yönlendirme yapmasını sağlamanız gerekir.

Daha fazla kullanıcı. tmux soketleri kullanıcı bazlıdır; bu nedenle aynı sunucudaki iki geliştirici kendi tmux sunucularına sahip olur ve birbirlerinin oturumlarını göremezler. Tek bir oturumu paylaşılan bir soket üzerinden paylaşmak, herkesin aynı Unix kullanıcısı olarak aynı kabuğa yazması anlamına gelir; bu da denetim ve izinler açısından riskler doğurur. Ayrı kullanıcılar kullanmak, sıkıcı ancak doğru olan çözümdür.

Gözetimsiz işler. tmux, bağlandığınız etkileşimli oturumlar içindir. Kimse izlemiyorken zamanlanmış şekilde çalışan işler, systemd birimi ve zamanlayıcısı (timer) içinde yer almalıdır; bu sayede günlük kaydı, yeniden başlatma politikası ve sistem açılışında otomatik çalışma gibi özelliklerden ücretsiz yararlanabilirsiniz. Cron benzeri bir işi çalıştırmak için tmux kullanmak, o işin bir servis haline gelmesi gerektiğinin işaretidir.

Son bir not: aracın başlattığı geliştirme sunucularını 0.0.0.0 yerine 127.0.0.1 adresine bağlayın ve ufw üzerinde port açmak yerine bunlara bir SSH tüneli (ssh -L 3000:127.0.0.1:3000 agent@your-server) üzerinden erişin. Yarım düzine portu yönlendirmeye başladığınızda veya bir telefon ile bir dizüstü bilgisayar aynı önizlemeye erişmek istediğinde, bunların önüne VPS üzerinde kendi kendine barındırılan bir WireGuard VPN kurun: geliştirme sunucuları özel bir arayüze bağlanır ve ufw genel arayüzden gelen her şeyi engellemeye devam eder. Güvenlik duvarı, yalnızca üzerinde delikler açmayı bıraktığınızda işe yarar.

Claude Code tek seçenek değildir: VPS üzerinde bir kodlama yapay zeka aracı çalıştırmak için Aider ve Goose seçeneklerini de değerlendirebilirsiniz.

FAQ

Claude Code, SSH bağlantım koptuktan sonra çalışmaya devam eder mi?

Yalnızca tmux içinde başlattıysanız devam eder. Doğrudan SSH kabuğu üzerinden başlatılan bir süreç, o kabuğun alt sürecidir ve bağlantı koptuğunda pty ile birlikte sonlanır. tmux içinde ise kabuk, bağlantısı kesilmiş (detached) tmux sunucusuna aittir; bu sayede aracı görevine devam eder ve tmux attach sizi aynı kaydırma geçmişine geri döndürür. Her girişten sonra tmux new -A -s <project> komutunu ilk komut yaparsanız bu sorun ortadan kalkar.

CLI'ı sudo npm install -g ile mi kurmalıyım?

Hayır. root sahipliğindeki global bir önek, sonraki kurulumlarda EACCES hatalarına ve npm önbelleğinde root sahipliğinde dosyalara yol açar. npm önekini ~/.npm-global olarak ayarlayın (veya nvm gibi bir sürüm yöneticisi kullanın), yetkisiz agent kullanıcısı olarak kurulum yapın ve ~/.npm-global/bin değişkenini etkileşimli koruma bloğunun üzerinde olacak şekilde ~/.bashrc dosyasından PATH içine aktarın. Eğer sudo npm komutunu bir kez çalıştırdıysanız, önbelleği sudo chown -R $(id -u):$(id -g) ~/.npm ile onarın.

Bir aracı çalıştıran sunucuda ssh -A aracı yönlendirmesi güvenli midir?

Bu, işin gerektirdiğinden çok daha fazla yetki verir. Yönlendirme, yerel SSH aracınızın soketini o kullanıcı olarak çalışan her sürece açar; böylece sunucudaki herhangi bir şey, siz bağlı kaldığınız sürece anahtarınızdan erişebildiği herhangi bir ana bilgisayar için imza isteyebilir. Sunucuda bir ed25519 anahtarı oluşturun ve bunu depo bazlı bir dağıtım anahtarı olarak kaydedin; yalnızca aracın gerçekten push yapması gerekiyorsa yazma erişimi verin.

Derleme işlemim neden sadece Killed yazdırıyor?

Yığın izi (stack trace) olmayan tek kelimelik bu hata, çekirdeğin OOM (Out of Memory) katilidir. Bunu sudo dmesg -T | grep -i -E 'out of memory|killed process' ile doğrulayın; Node tarafında bunun yerine JavaScript heap out of memory görebilirsiniz. Çözümleri sırasıyla uygulayın: bir swapfile ekleyin, test ve derleyici paralelliğini sınırlayın, NODE_OPTIONS=--max-old-space-size=... değerini yükseltin ve ardından VPS boyutunu artırın. OOM katilinin derleme süreci yerine tmux sunucusunu seçebileceğini ve tüm oturumunuzu sonlandırabileceğini unutmayın.

tmux mı yoksa systemd servisi mi?

tmux, bağlandığınız, izlediğiniz ve içine veri girdiğiniz etkileşimli oturumlar için uygundur; bir aracı oturumu tam olarak budur. Kimsenin izlemediği ve belirli bir zamanlamaya göre çalışan işler, günlük kaydı, yeniden başlatma politikası ve sistem açılışında otomatik çalışma gibi özelliklerin hazır geldiği bir systemd birimi ve zamanlayıcısı (timer) içinde yer almalıdır. Eğer cron benzeri bir işi çalıştırmak için tmux kullanıyorsanız, o iş bir servis olmalıdır.