Claude Code na zdalnym VPS: konfiguracja z tmux

Problem stanowi pokrywa laptopa, a nie CLI

Claude Code działa poprawnie na laptopie do momentu jego zamknięcia: sesja SSH zostaje przerwana, powłoka otrzymuje sygnał SIGHUP, a agent działający od trzech minut w trakcie testu kończy pracę wraz z nią. Uruchom CLI na maszynie, która nigdy nie przechodzi w stan uśpienia, wewnątrz multipleksera terminala, którego procesy nie są procesami potomnymi sesji SSH. Na tym polega cały trik, a to tmux, a nie sama instalacja, stanowi kluczowy element utrzymujący działanie.

Niniejsza strona dotyczy obsługi maszyny, na której pozostawiasz uruchomionych agentów. Jeśli nie posiadasz serwera Linux, który może pozostać włączony, powyższe informacje nie mają zastosowania. Jest to jedyny uczciwy warunek wstępny.

Jak w rzeczywistości działa tmux

Podczas logowania przez SSH, sshd tworzy proces potomny powłoki i przydziela mu pseudo-terminal; wszystko, co uruchamiasz z poziomu tej powłoki, jest jej procesem potomnym. Zerwanie połączenia powoduje, że jądro systemu zamyka pty, powłoka otrzymuje sygnał SIGHUP i kończy działanie swoich procesów potomnych. Długotrwałe procesy działające na pierwszym planie zostają przerwane.

tmux odwraca tę zależność. Polecenie tmux, które wpisujesz, jest lekkim klientem komunikującym się przez gniazdo unixowe z serwerem tmux, który działa w oderwaniu od Twojego terminala. Powłoki wewnątrz sesji są procesami potomnymi tego serwera, a nie sshd. Przerwanie połączenia SSH powoduje zamknięcie klienta, podczas gdy serwer, sesja i trwające zadanie działają dalej. Po ponownym połączeniu, tmux attach, wracasz do tej samej powłoki z zachowaną historią przewijania. nohup również przetrwa rozłączenie, ale nie oferuje możliwości powrotu; nie można ponownie podłączyć się do procesu TUI działającego w tle. Claude Code jest interaktywny; tmux (lub screen) jest właściwym narzędziem.

Dobieranie rozmiaru maszyny

Sam interfejs CLI jest pojedynczym natywnym plikiem binarnym; to nie on zajmuje zasoby maszyny. Zasoby zajmuje to, co agent uruchamia w Twoim imieniu: proces budowania, pełny zestaw testów, tsc, serwer języka czy baza danych w Docker. Dobierz rozmiar pod kątem łańcucha narzędzi, a nie samego CLI. Dodaj swap, nawet jeśli nie planujesz z niego korzystać; zamienia on nagłe przerwanie procesu przez OOM killer na powolne budowanie:

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

Monitoruj również dysk: repozytoria, node_modules oraz obrazy Docker szybko zajmują miejsce. Jeśli łańcuch narzędzi wykracza poza kontenery i obejmuje pełne maszyny wirtualne, gościa KVM lub lokalny węzeł Kubernetes, sprawdź przed podjęciem decyzji, czy plan udostępnia rozszerzenia wirtualizacji procesora. Uruchamianie zagnieżdżonej wirtualizacji na VPS jest funkcją włączaną przez dostawcę, a nie opcją, którą można aktywować z poziomu systemu gościa.

Użytkownik bez uprawnień root

Utwórz dedykowanego użytkownika z własnym katalogiem domowym i umieść w nim swój klucz publiczny:

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

Przetestuj logowanie z poziomu drugiego terminala przed wykonaniem kolejnych kroków, dopóki uwierzytelnianie hasłem pozostaje dostępne jako rozwiązanie awaryjne. Jeśli pojawi się błąd Permission denied (publickey), przyczyną jest zazwyczaj niewłaściwy właściciel lub uprawnienia katalogu .ssh, a nie sam klucz.

Celowo użytkownik agent nie jest dodawany do grupy sudo. W razie potrzeby instalacji pakietu systemowego, wykonuje się to ręcznie. Ta decyzja eliminuje większość scenariuszy, w których przypadkowe polecenie powłoki mogłoby uszkodzić system hosta.

Higiena SSH dla serwera działającego w trybie ciągłym

Uwierzytelnianie hasłem na maszynie wystawionej na publiczny dostęp do Internetu, która przechowuje agenta oraz kod źródłowy, stanowi nieakceptowalne ryzyko. Należy je wyłączyć. W systemach Ubuntu 24.04 oraz Debian 13, /etc/ssh/sshd_config zawiera /etc/ssh/sshd_config.d/*.conf, dlatego zaleca się utworzenie osobnego pliku konfiguracyjnego zamiast edycji głównego pliku:

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

Nie umieszczaj wymiany kluczy w tym pliku bez konkretnego powodu: wiersz KexAlgorithms skopiowany ze starszego przewodnika dotyczącego wzmacniania zabezpieczeń często ogranicza konfigurację wyłącznie do algorytmów klasycznych. W efekcie nowszy klient ssh wyświetla ostrzeżenie, że połączenie nie korzysta z postkwantowej wymiany kluczy.

Zweryfikuj poprawność konfiguracji i przeładuj usługę, zachowując aktywną bieżącą sesję podczas testowania nowego połączenia z drugiego terminala:

sudo sshd -t && sudo systemctl restart ssh

Ważny szczegół w Ubuntu 24.04: sshd jest aktywowany przez gniazdo (socket-activated). Ustawienia uwierzytelniania są stosowane w systemctl restart ssh, jednak zmiana portu nasłuchiwania Port wymaga również edycji systemctl daemon-reload oraz restartu ssh.socket.

Następnie skonfiguruj zaporę sieciową. Zezwól na ruch SSH przed włączeniem firewalla, aby uniknąć zablokowania dostępu do serwera:

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

Zainstaluj fail2ban, mając świadomość jego przeznaczenia: po wyłączeniu uwierzytelniania hasłem ataki typu brute force i tak nie zakończą się powodzeniem, a narzędzie to jedynie odciąży dziennik systemowy z nieudanych prób logowania.

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

Na koniec skonfiguruj automatyczne aktualizacje za pomocą sudo apt install unattended-upgrades oraz sudo dpkg-reconfigure -plow unattended-upgrades. Zwróć uwagę na interakcję z tmux: włączenie Unattended-Upgrade::Automatic-Reboot spowoduje restart serwera po aktualizacji jądra, co zamknie wszystkie sesje. Zaleca się pozostawienie tej opcji wyłączonej i wykonywanie restartów w zaplanowanym terminie, gdy żadne procesy nie są w toku. Ta sama ostrożność obowiązuje przy aktualizacji dystrybucji: przejście z Ubuntu 24.04 na 26.04 powoduje restart sshd oraz jądra, dlatego należy to wykonać w oknie serwisowym, gdy żadna sesja tmux nie przechowuje istotnych danych.

Instalacja Node.js i Claude Code na Ubuntu

Ścieżka npm wymaga Node.js w wersji 22 lub nowszej. (Pakiet pobiera obecnie natywny plik binarny, który nie uruchamia się na Node, ale npm nadal sprawdza wersję silnika, a własny łańcuch narzędzi agenta zazwyczaj i tak wymaga aktualnego środowiska Node). Pakiety dystrybucyjne często są przestarzałe; NodeSource to standardowa metoda na Ubuntu i Debianie, która dostarcza podpisane repozytorium (bez apt-key, który jest przestarzały w Ubuntu 24.04 i usunięty w Debianie 13):

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

Teraz część, w której często popełniane są błędy: zainstaluj CLI jako użytkownik agent, nigdy z sudo npm -g. Globalny prefiks należący do root powoduje późniejsze błędy uprawnień i pozostawia pliki należące do root w pamięci podręcznej npm. Najpierw skieruj prefiks npm na katalog domowy użytkownika:

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

Eksport umieszcza się w ~/.bashrc i musi on znaleźć się powyżej warunku "If not running interactively, don't do anything" znajdującego się na początku pliku. Domyślny panel tmux uruchamia powłokę logowania: tmux pozostawia default-command puste, co nakazuje mu uruchomić default-shell jako powłokę logowania, a powłoka bash logowania odczytuje ~/.profile, które w Ubuntu wczytuje ~/.bashrc. Powłoki niebędące powłokami logowania, na przykład jeśli ustawisz default-command samodzielnie, odczytują bezpośrednio ~/.bashrc. Zatem ~/.bashrc obejmuje oba przypadki, podczas gdy samo ~/.profile pominęłoby drugi z nich. Jeden haczyk: bash pomija ~/.profile, jeśli istnieje ~/.bash_profile lub ~/.bash_login, więc jeśli któryś z nich został utworzony, należy dodać w nim wczytywanie ~/.bashrc. Node dla użytkownika za pośrednictwem menedżera wersji, takiego jak nvm, osiąga ten sam cel; w obu przypadkach chodzi o to, aby npm install -g nigdy nie wymagało sudo. npm nadal działa poprawnie, ale dokumentacja Anthropic wskazuje natywny skrypt instalacyjny jako zalecaną metodę, a podpisane repozytoria apt, dnf i apk stanowią alternatywę. Przed wklejeniem poleceń sprawdź dokumentację instalacji Anthropic, ponieważ metody instalacji ulegają zmianie.

Uruchom claude wewnątrz repozytorium, aby je zainicjować. Pierwsze uruchomienie przeprowadzi użytkownika przez proces uwierzytelniania; serwer bez interfejsu graficznego nie posiada przeglądarki, więc proces udostępnia adres URL do otwarcia na własnym komputerze oraz kod do wprowadzenia w terminalu. (Klucz API w zmiennych środowiskowych to druga metoda). W obu przypadkach poświadczenie to znajduje się teraz na serwerze, co prowadzi nas do części, którą użytkownicy często pomijają.

Rozmowa o promieniu rażenia

Agent z dostępem do powłoki jest powłoką. Może odczytać wszystko, co może odczytać użytkownik, na którego koncie działa, i może zapisać dane wszędzie tam, gdzie ten użytkownik ma uprawnienia do zapisu. Nie jest to krytyka narzędzia, lecz jego definicja. Dlatego konto, na którym działa agent, ma większe znaczenie niż jakiekolwiek pojedyncze ustawienie.

• Dedykowany, nieuprzywilejowany użytkownik. Brak grupy sudo, brak katalogu domowego współdzielonego z własnym kontem.
• Brak danych uwierzytelniających środowiska produkcyjnego na serwerze. Brak pliku ~/.aws/credentials przechowującego klucze produkcyjne, brak plików .env skopiowanych ze środowiska produkcyjnego, brak hasła do bazy danych z uprawnieniami do zapisu w istotnych zasobach. Należy nadać agentowi uprawnienia środowiska testowego lub dostęp tylko do odczytu.
• Tokeny o ograniczonym zakresie. Precyzyjnie określony token GitHub ograniczony do jednego repozytorium; klucz typu deploy key, gdy wystarczy dostęp do odczytu.

Claude Code udostępnia flagę --dangerously-skip-permissions, która pomija niemal wszystkie monity o uprawnienia. Na laptopie, w przypadku projektu tymczasowego, jest to decyzja użytkownika. Na serwerze przechowującym tokeny, flaga ta usuwa ostatnią barierę między błędnie zinterpretowaną instrukcją a poleceniem git push --force. Monity, które są pomijane, nie działają na zasadzie „wszystko albo nic”, a przy trybie automatycznym jako domyślnym trybie startowym (od wersji Claude Code v2.1.283) warto wiedzieć, w jakim trybie uprawnień powinien pracować serwer, który nie jest stale monitorowany. Informacje o tym, co faktycznie zmienia ta flaga oraz jak ograniczyć agenta, który z niej korzysta – od wbudowanego środowiska sandbox po jednorazowy serwer VPS – znajdują się w sekcji bezpieczne uruchamianie Claude Code na serwerze.

Deploy key a przekazywanie SSH agenta

Kuszące jest użycie ssh -A, aby git mógł korzystać z klucza znajdującego się na laptopie. Należy zrozumieć, co to oznacza: przekazywanie agenta udostępnia gniazdo lokalnego agenta SSH procesom działającym na serwerze jako dany użytkownik. Wszystko, co działa jako agent, w tym agent, może poprosić o podpisanie kluczem żądania dla dowolnego hosta, do którego ma dostęp, tak długo, jak trwa połączenie. Jest to znacznie więcej niż tylko „pozwól gitowi pobrać to jedno repozytorium”.

Zamiast tego należy wygenerować klucz na serwerze, zarejestrować go jako klucz typu deploy key dla konkretnego repozytorium (dostęp do zapisu tylko wtedy, gdy agent musi wypychać zmiany) oraz ustawić tożsamość git, aby commity z serwera były rozpoznawalne:

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"

Przepływ pracy w tmux

Zainstaluj narzędzie (sudo apt install tmux), a następnie utwórz minimalny plik ~/.tmux.conf:

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

Cztery polecenia wystarczają do codziennej pracy:

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

Polecenie tmux new -A -s claude jest najważniejsze do zapamiętania; dołącza do istniejącej sesji lub tworzy nową, jeśli nie istnieje, więc jedno polecenie obsługuje zarówno rozpoczęcie pracy, jak i powrót po rozłączeniu. Warto utworzyć dla niego alias. Wewnątrz sesji Ctrl-b c otwiera nowe okno, Ctrl-b n oraz Ctrl-b p przełączają się między nimi, a Ctrl-b [ uruchamia tryb kopiowania umożliwiający przewijanie (q zamyka ten tryb).

Warto pamiętać o sesjach, których nigdy nie kończysz: agent przesyła całą historię konwersacji przy każdym zapytaniu, dlatego przeczytaj na co zużywa tokeny długotrwała sesja Claude Code przed pozostawieniem jej uruchomionej przez tydzień.

Tryby awaryjne

"Moja sesja zniknęła." tmux ls wyświetla no server running on /tmp/tmux-1000/default. Oznacza to niemal zawsze, że proces nigdy nie działał wewnątrz tmux, użytkownik zalogował się przez SSH, uruchomił claude bezpośrednio, a rozłączenie zakończyło proces. Nie ma czego odzyskiwać. Nawyk, który temu zapobiega: tmux new -A -s <project> to pierwsze polecenie po każdym zalogowaniu.

Panel zmniejsza się do małego okna. Opcja window-size decyduje, który podłączony klient ustala rozmiar. Od wersji tmux 3.1 (Ubuntu 24.04 dostarcza 3.4) wartością domyślną jest latest, czyli klient z najnowszą aktywnością, ale konfiguracja zawierająca window-size smallest wymusza rozmiar najmniejszego podłączonego klienta, więc nieaktywny klient podłączony z innej maszyny ściska wyświetlany obraz. Należy wymusić rozłączenie innych klientów podczas łączenia: tmux attach -d -t claude.

Proces budowania wyświetla Killed. Jedno słowo, brak śladu stosu. Należy potwierdzić za pomocą sudo dmesg -T | grep -i -E 'out of memory|killed process', że mechanizm OOM killer jądra wybrał największy proces. W przypadku Node można zamiast tego zobaczyć FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory. Rozwiązania w kolejności: dodanie swap (powyżej), ograniczenie równoległości testów i kompilacji, zwiększenie sterty Node za pomocą NODE_OPTIONS=--max-old-space-size=... lub zwiększenie zasobów VPS. OOM killer może również wybrać serwer tmux zamiast procesu budowania, co zakończy sesję; jeśli działa systemd-oomd, może on zabić cały wycinek użytkownika z tym samym skutkiem.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Globalna instalacja w katalogu należącym do root. Należy użyć prefiksu ~/.npm-global opisanego powyżej. Jeśli w pewnym momencie uruchomiono sudo npm, można również zobaczyć Your cache folder contains root-owned files, należy naprawić za pomocą sudo chown -R $(id -u):$(id -g) ~/.npm.

claude: command not found, ale tylko czasami. Eksport PATH znajduje się w ~/.bashrc poniżej warunku "Jeśli nie działa interaktywnie, nie rób nic", więc powłoki nieinteraktywne go pomijają. Należy przenieść eksport powyżej tego warunku i zachować go w ~/.bashrc: domyślny panel tmux to powłoka logowania, która dociera do ~/.bashrc poprzez ~/.profile w systemie Ubuntu, a każda powłoka niebędąca powłoką logowania odczytuje ~/.bashrc bezpośrednio, więc ten jeden plik obsługuje oba przypadki.

Zniekształcone kolory po podłączeniu. Niedopasowanie TERM, linia default-terminal powyżej stanowi rozwiązanie.

Sesje znikają po restarcie. To nie błąd: serwer tmux jest procesem, a restart go kończy. Należy sprawdzić uptime.

Co przestaje działać wraz ze wzrostem skali

Więcej projektów. Jedna sesja tmux na repozytorium, nazwana zgodnie z jego nazwą; tmux ls pełni wtedy rolę pulpitu nawigacyjnego. Pominięcie dyscypliny nazewnictwa prowadzi do powstania sesji 0, 1, 2. Gdy uruchomionych jest kilka sesji jednocześnie, nie muszą one pracować w izolacji, ponieważ jedna sesja może przekazać wiadomość do drugiej na tym samym serwerze, co jest przydatne, gdy agent wykonujący długotrwały refaktoring potrzebuje drugiego agenta do uruchomienia testów. Porty rozrastają się w ten sam sposób; sześć repozytoriów wymagających :3000 to moment, w którym należy przestać przypisywać je ręcznie i pozwolić, aby reverse proxy Traefik w Docker Compose zajęło się kierowaniem ruchu na podstawie nazwy hosta.

Więcej osób. Gniazda (sockets) tmux są przypisane do użytkownika, więc dwóch programistów na tym samym serwerze otrzymuje własne serwery tmux i nie widzi sesji innych osób. Współdzielenie jednej sesji przez wspólne gniazdo oznacza, że wszyscy wpisują polecenia w tę samą powłokę jako ten sam użytkownik Unix, co niesie ze sobą konsekwencje w zakresie audytu i uprawnień. Oddzielni użytkownicy to nudne, ale poprawne rozwiązanie.

Praca w tle. tmux służy do sesji interaktywnych, do których użytkownik się podłącza. Zadania uruchamiane według harmonogramu bez nadzoru powinny znajdować się w jednostce (unit) i timerze systemd, gdzie automatycznie otrzymują logowanie, politykę restartu i odporność na restart systemu. Sięganie po tmux w celu uruchomienia zadania typu cron jest sygnałem, że zadanie powinno stać się usługą.

Ostatnia uwaga: serwery deweloperskie uruchamiane przez agenta należy wiązać z 127.0.0.1, a nie 0.0.0.0, i uzyskiwać do nich dostęp przez tunel SSH (ssh -L 3000:127.0.0.1:3000 agent@your-server), zamiast otwierać porty w ufw. Gdy przekierowujesz już pół tuzina portów lub gdy telefon i laptop wymagają dostępu do tego samego podglądu, umieść przed nimi samodzielnie hostowany VPN WireGuard na VPS: serwery deweloperskie wiążą się z prywatnym interfejsem, a ufw odrzuca wszystko z interfejsu publicznego. Firewall pomaga tylko wtedy, gdy przestaniesz robić w nim dziury.

Claude Code nie jest jedynym wyborem: uruchomienie agenta AI do kodowania na VPS pozwala również rozważyć Aider oraz Goose.

FAQ

Czy Claude Code działa nadal po zerwaniu połączenia SSH?

Tylko jeśli uruchomiono go wewnątrz tmux. Proces uruchomiony bezpośrednio z powłoki SSH jest procesem potomnym tej powłoki i kończy się wraz z pty w momencie zerwania połączenia. Wewnątrz tmux powłoka należy do odłączonego serwera tmux, więc agent kontynuuje pracę w trakcie zadania, a tmux attach przywraca użytkownika do tego samego bufora przewijania. Ustawienie tmux new -A -s <project> jako pierwszego polecenia po każdym logowaniu rozwiązuje ten problem.

Czy należy instalować CLI za pomocą sudo npm install -g?

Nie. Globalny prefiks należący do root powoduje błędy EACCES przy późniejszych instalacjach oraz pliki należące do root w pamięci podręcznej npm. Należy ustawić prefiks npm na ~/.npm-global (lub użyć menedżera wersji, takiego jak nvm), instalować jako użytkownik bez uprawnień agent oraz wyeksportować ~/.npm-global/bin do PATH z pliku ~/.bashrc, powyżej warunku sprawdzającego interaktywność. Jeśli polecenie sudo npm zostało już raz uruchomione, należy naprawić pamięć podręczną za pomocą sudo chown -R $(id -u):$(id -g) ~/.npm.

Czy przekazywanie agenta ssh -A jest bezpieczne na serwerze z uruchomionym agentem?

Przyznaje ono znacznie więcej uprawnień, niż wymaga tego zadanie. Przekazywanie udostępnia gniazdo lokalnego agenta SSH każdemu procesowi działającemu jako dany użytkownik, więc każdy element na serwerze może zażądać od klucza podpisu dla dowolnego hosta, do którego ma dostęp, tak długo, jak trwa połączenie. Należy wygenerować klucz ed25519 na serwerze i zarejestrować go jako klucz wdrożeniowy (deploy key) dla konkretnego repozytorium, z dostępem do zapisu tylko wtedy, gdy agent faktycznie musi wykonać operację push.

Dlaczego kompilacja wyświetla tylko Killed?

Jedno słowo bez śladu stosu (stack trace) oznacza działanie mechanizmu OOM killer jądra systemu. Należy to potwierdzić za pomocą sudo dmesg -T | grep -i -E 'out of memory|killed process'; w przypadku Node można zobaczyć JavaScript heap out of memory. Należy zastosować poprawki w następującej kolejności: dodać plik wymiany (swapfile), ograniczyć równoległość testów i kompilatora, zwiększyć NODE_OPTIONS=--max-old-space-size=..., a następnie zwiększyć zasoby VPS. Należy pamiętać, że OOM killer może wybrać serwer tmux zamiast procesu kompilacji, co spowoduje zamknięcie całej sesji.

tmux czy usługa systemd?

tmux jest odpowiedni dla sesji interaktywnych, do których użytkownik się podłącza, obserwuje je i wpisuje polecenia – dokładnie tak działa sesja agenta. Zadania uruchamiane według harmonogramu bez nadzoru powinny być obsługiwane przez jednostkę (unit) i timer systemd, gdzie logowanie, polityka restartu i przetrwanie po restarcie systemu są dostępne w standardzie. Jeśli użytkownik sięga po tmux w celu uruchomienia zadania typu cron, zadanie to powinno być usługą.