Jak zainstalować OpenCode na VPS

Czym jest OpenCode i co należy skonfigurować

OpenCode to agent AI do programowania typu open source, przeznaczony do obsługi w terminalu. Program uruchamia się wewnątrz katalogu projektu. Odczytuje kod, proponuje zmiany, edytuje pliki i wykonuje polecenia za pomocą interfejsu TUI. Produkt posiada licencję MIT i łączy się z ponad 75 dostawcami modeli. Według danych z połowy 2026 roku, posiadając około 165,000 gwiazdek w GitHub, jest to najbardziej oceniany agent open source do programowania. Aby uruchomić OpenCode na VPS, należy zainstalować go na dedykowanym użytkowniku o ograniczonych uprawnieniach, umieścić klucz API modelu w prywatnym pliku oraz uruchomić proces wewnątrz tmux, aby zapewnić trwałość sesji po rozłączeniu. Niniejszy poradnik opisuje dokładnie te kroki, w podanej kolejności.

Ważna uwaga dotycząca nazewnictwa. Oficjalne repozytorium to anomalyco/opencode, utrzymywane przez zespół Anomaly (wcześniej znanym jako SST), natomiast projekt znajdował się wcześniej pod adresem sst/opencode. Na GitHubie istnieje również starsze, niezwiązane z projektem repozytorium o nazwie opencode-ai/opencode, dlatego należy upewnić się, że dokumentacja dotyczy właściwego projektu. Oficjalna strona to opencode.ai.

Dlaczego należy uruchamiać OpenCode na VPS

Sesja agenta programistycznego jest długotrwała. OpenCode może spędzać wiele minut na refaktoryzacji lub uruchamianiu zestawu testów. Jeśli proces przebiega na laptopie, zamknięcie klapy lub utrata połączenia Wi-Fi przerywa zadanie w trakcie wykonywania. Na VPS wewnątrz sesji tmux agent kontynuuje pracę po rozłączeniu użytkownika. Można później ponownie nawiązać połączenie, aby sprawdzić wyniki. Jest to ten sam model, który stosuje się w przypadku uruchamiania Claude Code na VPS z tmux. Jest to najważniejsza korzyść wynikająca z przeniesienia agenta z laptopa.

Drugim powodem jest lokalizacja. VPS znajduje się blisko kodu przeznaczonego do wdrożenia: repozytorium, narzędzi budujących, baz danych testowych oraz środowisk stagingowych. Agent edytujący kod i uruchamiający testy pracuje najefektywniej na maszynie, na której faktycznie wykonywane są te testy. Ponieważ serwer jest pod pełną kontrolą, można celowo zapewnić agentowi odizolowane środowisko, co opisano w następnej sekcji.

Jeśli proces wyboru narzędzia trwa, artykuł uruchamianie agenta AI do programowania na VPS zawiera porównanie szerszego zestawu rozwiązań, w tym Aider oraz Goose.

Przypisanie OpenCode dedykowanego użytkownika

Punkt wyjścia: agent programistyczny edytuje pliki i wykonuje polecenia. Jest to jego zadanie, ale stanowi również ryzyko. OpenCode będzie uruchamiał procesy budowania, testy oraz wszelkie polecenia shell wymagane do wykonania zadania. Ocena modelu jest trafna, lecz nie jest nieomylna. Uprawnienia konta, z którego działa agent, wyznaczają maksymalny zakres szkód, jakie może wyrządzić błędne polecenie. Nie należy uruchamiać agenta jako root ani jako użytkownik administracyjny serwera.

W przeciwieństwie do agentów działających w tle, OpenCode jest interaktywny, dlatego jego użytkownik musi posiadać powłokę shell oraz katalog domowy:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Projekty przeznaczone do pracy należy przechowywać w /home/opencode i klonować przy użyciu tego użytkownika. Kontu nie należy nadawać uprawnień sudo. Jeśli agent wykona destrukcyjne polecenie, uszkodzi jedynie zasoby należące do tego konkretnego konta. Jest to ta sama zasada, która stosowana jest przy uruchamianiu usług jako użytkownik nieuprzywilejowany. Należy również pracować wewnątrz repozytorium git, ponieważ pozwala to zamienić błędną edycję w git revert zamiast trwałej utraty danych.

Install OpenCode

Projekt przewiduje dwie metody instalacji. Skrypt instalacyjny jest najszybszą metodą. Uruchomienie go jako użytkownik opencode sprawia, że wszystkie pliki pozostają w katalogu home tego użytkownika:

curl -fsSL https://opencode.ai/install | bash

Zasada curl | bash obowiązuje tutaj tak samo jak wszędzie: na serwerze, który jest istotny, najpierw pobierz skrypt, przeczytaj go, a dopiero potem uruchom. Po instalacji należy uruchomić nową powłokę, aby zmiany w zmiennej PATH wprowadzone przez instalator weszły w życie, a następnie zweryfikować działanie pliku binarnego:

opencode --version

Jeśli preferowana jest metoda za pomocą menedżera pakietów, a Node.js jest już zainstalowany w systemie, metoda npm zainstaluje to samo narzędzie systemowo. Powoduje to dodanie pliku binarnego opencode do zmiennej PATH dla każdego użytkownika:

sudo npm install -g opencode-ai

W obu przypadkach weryfikacja jest taka sama: opencode --version wypisuje numer wersji. Błąd command not found po instalacji za pomocą skryptu oznacza, że bieżąca powłoka nie odczytała jeszcze zaktualizowanej zmiennej PATH. Należy wtedy wylogować się i zalogować ponownie jako użytkownik opencode.

Umieść klucz API w prywatnym pliku

OpenCode wymaga klucza dla wybranego dostawcy modeli. Klucz ten generuje koszty, dlatego należy traktować go jak hasło. Należy utworzyć plik z uprawnieniami 600, do którego dostęp ma wyłącznie użytkownik opencode. Przechowywanie klucza w pliku zapobiega jego zapisaniu w historii powłoki (shell history) podczas wpisywania komend:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

W pliku należy umieścić zmienną dostawcy, na przykład ANTHROPIC_API_KEY=... lub odpowiednik dla danego dostawcy, ponieważ OpenCode korzysta ze standardowych zmiennych środowiskowych dostawców. Przed uruchomieniem agenta należy załadować plik do powłoki:

set -a; source ~/opencode.env; set +a

OpenCode oferuje również alternatywę interaktywną: polecenie /connect wewnątrz TUI prowadzi przez proces dodawania dostawcy i zapisuje dane uwierzytelniające w pliku ~/.local/share/opencode/auth.json w katalogu domowym użytkownika. W przypadku tej metody należy zweryfikować prywatność pliku za pomocą chmod 600 ~/.local/share/opencode/auth.json. Obie metody zapobiegają wyświetlaniu klucza w liniach komend; należy wybrać jedną i stosować ją konsekwentnie.

Uruchom OpenCode wewnątrz tmux

tmux jest kluczowym elementem konfiguracji VPS, ponieważ sesja tmux działa nadal po zakończeniu połączenia SSH. Należy uruchomić sesję, przejść do katalogu projektu i uruchomić agenta:

tmux new -s opencode
cd ~/my-project
opencode

Powinien otworzyć się interfejs TUI z poleceniem na dole oraz nazwą projektu w interfejsie. Po podaniu polecenia w języku naturalnym, agent rozpocznie odczytywanie plików i proponowanie zmian. Aby wyjść, należy odłączyć sesję za pomocą skrótu Ctrl-b, a następnie d; agent będzie kontynuował pracę po zamknięciu laptopa. Aby ponownie połączyć się z sesją, należy użyć:

tmux attach -t opencode

Sesja, konwersacja oraz wszystkie trwające zadania pozostają w tym samym stanie. Dane te są zachowane po rozłączeniu, ale nie po restarcie serwera. Po restarcie należy uruchomić nową sesję tmux w ten sam sposób.

Skonfiguruj model

OpenCode nie jest uzależniony od konkretnego dostawcy. Wykorzystuje AI SDK oraz katalog Models.dev, aby obsługiwać ponad 75 dostawców. To samo narzędzie działa z Anthropic, OpenAI, Google oraz dziesiątkami innych podmiotów, w tym z serwerami lokalnymi. Najszybszą metodą jest użycie komendy /connect wewnątrz TUI, która wyświetla listę dostawców i obsługuje poświadczenia. Aby uzyskać konfigurację umożliwiającą commit i powtarzalność, umieść plik opencode.json w głównym katalogu projektu i ustaw model jako provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

Lokalny model działa poprzez ten sam plik, ponieważ każdy serwer zgodny z OpenAI może zostać zadeklarowany jako dostawca. Jeśli uruchomisz model za pomocą Ollama na tym samym VPS, konfiguracja wskaże jego lokalne API, a nazwa modelu będzie zgodna z tym, co ollama list wyświetla w systemie:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

Warto od początku stosować jedną dobrą praktykę. OpenCode dostarcza dwóch agentów, przełączanych klawiszem Tab: Build (domyślny agent z pełnym dostępem) oraz Plan (wyłącza możliwość wprowadzania zmian). Rozpocznij nowe zadanie w trybie Plan, pozwól agentowi przeanalizować kod i zaproponować rozwiązanie, a do trybu Build przełącz się dopiero po zaakceptowaniu planu. Na serwerze pierwsza faza w trybie read-only stanowi skuteczne zabezpieczenie.

Zakres oddziaływania

Agent programistyczny nie jest pasywny, dlatego należy jasno określić zakres uprawnień tej konfiguracji. Zawiera ona ryzyko uszkodzenia plików: użytkownik opencode posiada własny katalog domowy i żadne inne zasoby, więc edycje i usunięcia kończą się na tej granicy. Zawiera ryzyko ekspozycji poświadczeń: klucz znajduje się w jednym pliku z trybem 600, przypisanym do jednego konta. Nie obejmuje ona jednak uprawnień, które konto posiada legalnie; jeśli katalog projektu zawiera poświadczenia do wdrożeń produkcyjnych, agent może ich użyć. Należy całkowicie wykluczyć takie dane z konta agenta.

W przeciwieństwie do agentów typu gateway, takich jak OpenClaw, OpenCode jest interaktywnym programem terminalowym, a nie demonem. Program nie otwiera żadnego portu nasłuchującego i nie posiada długotrwałych usług, więc nie wymaga tworzenia jednostki systemd ani konfiguracji reguł firewall dla samego agenta. Izolacja opiera się na koncie użytkownika oraz katalogu projektu, dlatego pierwsza sekcja tego przewodnika jest najważniejsza.

Serwer nadal wymaga standardowej ochrony, ponieważ VPS przeznaczony do kodowania pozostaje serwerem publicznym: należy stosować SSH wyłącznie z kluczem przy wyłączonym logowaniu root, zgodnie z zasadami opisanymi w utwardzaniu SSH na VPS, skonfigurować firewall w trybie default-deny oraz regularnie instalować aktualizacje. Należy również weryfikować kod generowany przez agenta. Przed wykonaniem operacji push należy sprawdzić diffy, tak jak w przypadku pull requestu od nowego kontrybutora, ponieważ to użytkownik dokonuje wdrożenia wyniku pracy.

Na koniec należy dbać o aktualność samego narzędzia. OpenCode wydaje częste aktualizacje, które zawierają poprawki istotne dla programu wykonującego polecenia na serwerze. Proces aktualizacji przebiega tak samo jak instalacja: należy ponownie uruchomić skrypt instalacyjny jako użytkownik opencode lub uruchomić sudo npm update -g opencode-ai, jeśli instalacja odbyła się przez npm, a następnie potwierdzić nową wersję poleceniem opencode --version. Krótka konserwacja jest bardziej opłacalna niż debugowanie błędów, które zostały już naprawione w nowszych wersjach.

FAQ

Czy OpenCode może używać lokalnego modelu zamiast płatnego API?

Tak. OpenCode traktuje każdy serwer zgodny z OpenAI jako dostawcę, więc model obsługiwany przez Ollama na tym samym VPS działa. Należy zadeklarować dostawcę w opencode.json przy użyciu lokalnego baseURL oraz nazwy modelu podanej przez Ollama. Ograniczeniem jest sprzęt, ponieważ model zdolny do profesjonalnego programowania wymaga dużej ilości pamięci RAM. Należy dobrać parametry serwera przed pobraniem modelu.

Jak utrzymać działanie OpenCode po zamknięciu laptopa?

Należy uruchomić proces wewnątrz tmux na VPS. Agent musi zostać uruchomiony w sesji o nazwie własnej za pomocą tmux new -s opencode. Po odłączeniu za pomocą Ctrl-b, a następnie d, sesja nadal działa na serwerze po zakończeniu połączenia SSH. Można wrócić do sesji w dowolnym momencie za pomocą tmux attach -t opencode, a rozmowa oraz trwające zadania pozostaną aktywne. Restart serwera kończy sesję, dlatego po restarcie należy uruchomić nową.

Czy bezpieczne jest uruchamianie komend przez OpenCode na VPS?

Jest to bezpieczne przy zachowaniu odpowiednich ograniczeń. Należy przypisać OpenCode dedykowanego użytkownika bez uprawnień sudo, przechowywać projekty w git w celu umożliwienia wycofania zmian, zapisać klucz API w pliku z uprawnieniami 600 oraz używać agenta Plan do wstępnej analizy w trybie read-only przed dopuszczeniem agenta Build do wprowadzania zmian. Dzięki temu agent może uszkodzić tylko zasoby należące do jego konta, a reszta serwera pozostaje niedostępna.

Jaka jest różnica między OpenCode a Claude Code?

OpenCode jest oprogramowaniem open source (licencja MIT) i jest niezależny od dostawcy. Łączy się z ponad 75 dostawcami modeli, w tym z modelami lokalnymi, poprzez jeden interfejs. Claude Code to terminalowy agent firmy Anthropic, zbudowany w oparciu o modele Anthropic. OpenCode jest odpowiedni, jeśli wymagane jest narzędzie obsługujące wielu dostawców lub w pełni samodzielny stos technologiczny z lokalnym modelem. Oba rozwiązania działają poprawnie na VPS wewnątrz tmux przy użyciu tej samej konfiguracji z użytkownikiem bez uprawnień administratora.