OpenCode VPS kurulumu nasıl yapılır?

OpenCode nedir ve ne kuruluyor

OpenCode, terminal için geliştirilmiş açık kaynaklı bir yapay zeka kodlama aracıdır. Bir proje dizini içinde başlatılır; kodları okur, değişiklik önerir, dosyaları düzenler ve terminal kullanıcı arayüzü (TUI) üzerinden komutlar çalıştırır. MIT lisansına sahiptir ve 75'ten fazla model sağlayıcısına bağlanabilir. 2026 ortası itibarıyla yaklaşık 165.000 GitHub yıldızı ile mevcut en popüler açık kaynaklı kodlama aracıdır. OpenCode'u bir VPS üzerinde çalıştırmak için, yazılım yetkisiz bir kullanıcı altına kurulmalı, model API anahtarı özel bir dosyaya konulmalı ve bağlantı kesildiğinde oturumun devam etmesi için tmux içinde başlatılmalıdır. Bu kılavuz, bu işlemleri sırasıyla gerçekleştirmektedir.

İsimlendirme ile ilgili bir not karışıklığı önler. Resmi depo, Anomaly ekibi (eski adıyla SST) tarafından yönetilen anomalyco/opencode adresidir; proje daha önce sst/opencode adresinde bulunmaktaydı. GitHub üzerinde opencode-ai/opencode adında eski ve ilgisiz bir depo daha mevcuttur, bu nedenle doğru projenin dokümantasyonunu okuduğunuzdan emin olun. Resmi web sitesi opencode.ai adresidir.

OpenCode'un bir VPS üzerinde çalıştırılma nedenleri

Bir kodlama ajanı oturumu uzun sürebilir. OpenCode, bir refactoring veya test paketi üzerinde dakikalarca çalışabilir. Eğer yerel bilgisayarınızda çalışıyorsa, kapağın kapatılması veya Wi-Fi bağlantısının kopması oturumu görev ortasında sonlandırır. Bir VPS üzerinde tmux kullanarak çalıştırıldığında, bağlantı kesildikten sonra ajan çalışmaya devam eder; daha sonra ne yaptığını okumak için tekrar bağlanabilirsiniz. Bu durum, tmux ile bir VPS üzerinde Claude Code çalıştırma yöntemiyle aynıdır ve bir ajanı yerel bilgisayardan taşımak için sağlanan en büyük kolaylıktır.

İkinci neden konumlandırmadır. Bir VPS, dağıtım yaptığınız koda yakındır: depo (repository), derleme araçları, test veritabanı ve genellikle staging ortamı zaten orada veya yanında bulunur. Kod düzenleyen ve testleri çalıştıran bir ajan, bu testlerin fiilen çalıştığı makinede en iyi performansı gösterir. Ayrıca, kontrol ettiğiniz bir sunucu olduğu için ajana kasıtlı olarak izole bir ortam sağlayabilirsiniz; bir sonraki bölüm bunu açıklamaktadır.

Hâlâ bir araç seçme aşamasındaysanız, bir kodlama yapay zeka ajanını VPS üzerinde çalıştırma içeriği, Aider ve Goose dahil olmak üzere daha geniş bir alanı karşılaştırmaktadır.

OpenCode için ayrı bir kullanıcı oluşturun

Temel durum şudur: bir kodlama ajanı dosyaları düzenler ve komutları çalıştırır. Bu onun görevidir, ancak aynı zamanda bir risk teşkil eder. OpenCode; derlemeleri, testleri ve görevin gerektirdiği kabuk komutlarını çalıştıracaktır; modelin kararları iyi olsa da kusursuz değildir. Ajanın çalıştığı hesap, hatalı bir komutun erişebileceği üst sınırı belirler. Bu nedenle ajanı root olarak veya sunucuyu yöneten kullanıcıyla aynı kullanıcı olarak çalıştırmayın.

Arka plan ajanlarının aksine OpenCode etkileşimlidir; bu yüzden kullanıcının gerçek bir kabuğa (shell) ve bir ana dizine (home directory) ihtiyacı vardır:

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

Çalışmasını istediğiniz projeleri, ilgili kullanıcı tarafından klonlanmış şekilde /home/opencode altında tutun. Hesaba sudo yetkisi vermeyin. Ajan yıkıcı bir komut çalıştırırsa, yalnızca bu hesabın sahip olduğu verileri yok edebilir; bu, servislerin yetkisiz bir kullanıcı olarak çalıştırılması ile aynı mantığa dayanır. Ayrıca bir git deposu (repository) içinde çalışın; çünkü bir depo, hatalı bir düzenlemeyi veri kaybı yerine bir git revert haline getirir.

OpenCode Kurulumu

Proje iki kurulum yöntemi sunar. Kurulum betiği en hızlı yöntemdir; betiğin opencode kullanıcısı ile çalıştırılması tüm dosyaların bu kullanıcının home dizini içinde tutulmasını sağlar:

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

Her yerde geçerli olan standart curl | bash alışkanlığı burada da geçerlidir: Önemli bir sunucuda önce betiği indirin, içeriğini okuyun ve ardından çalıştırın. Kurulumdan sonra, yükleyicinin yaptığı PATH değişikliğinin etkili olması için yeni bir shell başlatın ve ardından binary yanıtlarını kontrol edin:

opencode --version

Eğer bir paket yöneticisi tercih ediliyorsa ve sistemde Node.js zaten yüklüyse, npm yöntemi aynı aracı sistem genelinde kurar. Bu işlem, opencode binary dosyasını tüm kullanıcılar için PATH dizinine ekler:

sudo npm install -g opencode-ai

Her iki yöntemde de kontrol aynıdır: opencode --version bir sürüm numarası yazdırır. Betik kurulumundan sonra command not found alınması, mevcut shell'in güncellenmiş PATH bilgisini henüz okumadığı anlamına gelir; bu durumda opencode kullanıcısı olarak oturumu kapatıp tekrar açın.

API anahtarını özel bir dosyaya kaydedin

OpenCode, kullanılan model sağlayıcısına bağlı olarak bir anahtara ihtiyaç duyar. Bu anahtar maliyet oluşturabileceği için bir parola gibi ele alınmalıdır. Anahtarı, shell geçmişine kaydedilmemesi için komut satırına yazmak yerine, sadece opencode kullanıcısının okuyabileceği 600 moduyla bir dosyada saklayın:

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

Dosya içerisine sağlayıcınızın değişkenini, örneğin ANTHROPIC_API_KEY=... veya sağlayıcınıza uygun olan eşdeğer değişkeni ekleyin; OpenCode standart sağlayıcı ortam değişkenlerini kullanır. Agent başlatılmadan önce dosyayı shell ortamına yükleyin:

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

OpenCode'un etkileşimli bir alternatifi de mevcuttur: TUI içindeki /connect komutu, bir sağlayıcı ekleme sürecini yönetir ve kimlik bilgilerini kullanıcının home dizinindeki ~/.local/share/opencode/auth.json konumuna kaydeder. Bu yöntemi kullanıyorsanız, dosyanın gizli olduğunu chmod 600 ~/.local/share/opencode/auth.json ile doğrulayın. Her iki yöntem de anahtarın komut satırlarında görünmesini engeller; bir yöntem seçin ve tutarlı kalın.

tmux içinde OpenCode başlatın

tmux, SSH bağlantısı kesildiğinde tmux oturumunun çalışmaya devam etmesi sayesinde VPS kurulumunu kullanışlı hale getirir. Bir oturum başlatın, proje dizinine geçin ve ajanı çalıştırın:

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

Arayüzde proje adını ve altta bir komut satırını içeren TUI açılmalıdır. Görevi doğal dilde girdiğinizde, ajan dosyaları okumaya ve değişiklikler önermeye başlar. Ayrılmak istediğinizde, Ctrl-b ardından d tuşlarına basarak oturumu ayırın; ajan siz bilgisayarınızı kapatsanız bile çalışmaya devam eder. Daha sonra şu komutla tekrar bağlanın:

tmux attach -t opencode

Oturum, konuşma ve çalışan tüm görevler bıraktığınız gibi kalır. Bu durum bağlantı kesintilerine karşı koruma sağlar ancak sunucu yeniden başlatıldığında geçerli değildir; bu nedenle yeniden başlatma işleminden sonra aynı yöntemle yeni bir tmux oturumu başlatılmalıdır.

Bir modele yönlendirin

OpenCode, sağlayıcıdan bağımsızdır. 75'ten fazla sağlayıcıyı desteklemek için AI SDK ve Models.dev kataloğunu kullanır; bu sayede aynı araç Anthropic, OpenAI, Google ve yerel sunucular dahil olmak üzere onlarca farklı sağlayıcı ile çalışır. En hızlı yöntem, TUI içindeki sağlayıcıları listeleyen ve kimlik bilgilerini yöneten /connect komutudur. Kaydedilebilir ve yeniden oluşturulabilir bir kurulum için proje kök dizinine bir opencode.json dosyası ekleyin ve modeli provider/model-id olarak ayarlayın:

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

OpenAI uyumlu herhangi bir sunucu sağlayıcı olarak tanımlanabildiğinden, yerel modeller de aynı dosya üzerinden çalışır. Eğer aynı VPS üzerinde Ollama ile bir model sunuyorsanız, yapılandırma yerel API'yi işaret eder ve model adı, ollama list komutunun sisteminizde gösterdiği isimdir:

{
  "$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" } }
    }
  }
}

İlk günden itibaren uygulanması gereken yerleşik bir alışkanlık mevcuttur. OpenCode, Tab tuşu ile aralarında geçiş yapabileceğiniz iki ajanla birlikte gelir: Tam erişime sahip varsayılan ajan olan Build ve değişiklik yapma yeteneğini devre dışı bırakan Plan. Yeni bir göreve Plan modunda başlayın, kodun okunmasına ve bir yaklaşım önerilmesine izin verin; yalnızca plana katıldığınızda Build moduna geçin. Sunucularda, ilk aşamada salt okunur modun kullanılması güvenli bir yöntemdir.

Etki alanı hakkında

Bir kodlama ajanı pasif değildir; bu nedenle bu kurulumun neleri içerip içermediği açıkça belirtilmelidir. Dosya hasarı riski mevcuttur: opencode kullanıcısı yalnızca kendi home dizinine sahiptir, bu nedenle düzenleme ve silme işlemleri bu sınırda durur. Kimlik bilgisi ifşası riski mevcuttur: anahtar, 600 moduyla tek bir dosyada ve tek bir hesapta tutulur. Hesabın meşru olarak yapabileceği işlemler risk kapsamı dışındadır; eğer proje dizini üretim ortamı dağıtım kimlik bilgilerini içeriyorsa, ajan bunları kullanabilir; bu bilgileri ajanın hesabından tamamen uzak tutun.

OpenClaw gibi bir gateway ajanı yerine OpenCode, bir daemon değil, etkileşimli bir terminal programıdır. Herhangi bir dinleme portu açmaz ve uzun süreli çalışan bir servisi yoktur; bu nedenle yazılması gereken bir systemd ünitesi veya ajan için firewall ile kapatılması gereken bir port yoktur. Sınırlama, kullanıcı hesabı ve proje dizini ile sağlanır; bu yüzden bu kılavuzun ilk bölümü en önemli kısımdır.

Sistemin genel güvenliği için standart önlemler alınmalıdır, çünkü bir kodlama VPS'i hala halka açık bir sunucudur: VPS üzerinde SSH sıkılaştırma kılavuzunda belirtildiği gibi root girişi devre dışı bırakılmış sadece anahtar tabanlı SSH, varsayılan olarak reddeden (default-deny) bir firewall ve rutin güncellemeler gereklidir. Ayrıca ajanın ürettiği çıktıları inceleyin. Sonuçları dağıtan kişi siz olduğunuz için, diff çıktılarını yeni bir katkıcıdan gelen bir pull request'i okur gibi okuyun.

Son olarak, aracın kendisini güncel tutun. OpenCode sık sık sürüm yayınlar ve güncellemeler, sunucunuzda komutlar çalıştıran bir program için kritik olan düzeltmeler içerir. Güncelleme işlemi, kurulum yaptığınız yöntemin aynısını kullanır: kurulum betiğini opencode kullanıcısı olarak tekrar çalıştırın veya npm üzerinden kurduysanız sudo npm update -g opencode-ai komutunu çalıştırın, ardından yeni sürümü opencode --version ile doğrulayın. Ara sıra yapılacak bir dakikalık bakım, aylar öncesinden düzeltilmiş bir sürümdeki hatayı ayıklamaktan daha kolaydır.

FAQ

OpenCode, ücretli bir API yerine yerel bir model kullanabilir mi?

Evet. OpenCode, OpenAI uyumlu tüm sunucuları sağlayıcı olarak kabul eder. Bu sayede aynı VPS üzerinde Ollama tarafından sunulan bir model kullanılabilir: Sağlayıcıyı opencode.json içerisinde yerel baseURL ve Ollama tarafından bildirilen model adı ile tanımlayın. Temel kısıtlamadır donanım; gerçek kodlama işleri için yeterli olan bir model yüksek bellek gerektirir. Modeli indirmeden önce sunucu kapasitesini modele göre belirleyin.

Dizüstü bilgisayarımı kapattıktan sonra OpenCode'un çalışmaya devam etmesini nasıl sağlarım?

Uygulamayı VPS üzerinde tmux içinde çalıştırın. Ajanı tmux new -s opencode ile isimlendirilmiş bir oturumda başlatın, Ctrl-b ardından d tuşlarına basarak oturumdan ayrılın. SSH bağlantısı kesildikten sonra oturum sunucuda çalışmaya devam eder. tmux attach -t opencode komutu ile istediğiniz zaman tekrar bağlanabilirsiniz; konuşma ve devam eden tüm görevler korunur. Sunucunun yeniden başlatılması oturumu sonlandırır, bu nedenle yeniden başlatma işleminden sonra yeni bir oturum başlatın.

OpenCode'un VPS üzerinde komut çalıştırmasına izin vermek güvenli mi?

Sınırlandırıldığı sürece yönetilebilir bir durumdur. OpenCode'a sudo yetkisi olmayan, özel bir yetkisiz kullanıcı (unprivileged user) tanımlayın. Her düzenlemenin geri alınabilmesi için projeleri git içinde tutun, API anahtarını 600 modunda bir dosyada saklayın ve Build ajanına değişiklik yaptırmadan önce ilk aşama için Plan ajanını salt okunur olarak kullanın. Bu durumda ajan sadece kendi hesabının sahip olduğu dosyalara zarar verebilir ve sunucunun geri kalanı erişilemez kalır.

OpenCode ile Claude Code arasındaki fark nedir?

OpenCode açık kaynaklıdır (MIT) ve sağlayıcıdan bağımsızdır; tek bir arayüz üzerinden yerel modeller dahil 75'ten fazla model sağlayıcısına bağlanabilir. Claude Code ise Anthropic modelleri üzerine inşa edilmiş, Anthropic'in kendi terminal ajanıdır. Birden fazla sağlayıcı için tek bir araç veya yerel bir model ile tamamen kendi sunucunuzda barındırılan bir yapı istiyorsanız OpenCode uygundur. Her iki araç da aynı yetkisiz kullanıcı kurulumuyla, bir VPS üzerinde tmux içinde sorunsuz çalışır.