OpenCode VPS Üzerinde Nasıl Kurulur ve Çalıştırılır?

OpenCode nedir ve neyi yapılandırıyorsunuz

OpenCode, terminal için geliştirilmiş açık kaynaklı bir yapay zeka kodlama aracıdır. Bir proje dizini içerisinde başlatıldığında kodunuzu okur, değişiklikler önerir, dosyaları düzenler ve komutları çalıştırır; tüm bunları bir terminal kullanıcı arayüzü (TUI) üzerinden gerçekleştirir. MIT lisansına sahiptir, 75'ten fazla model sağlayıcısına bağlanabilir ve Ekim 2026 itibarıyla 219,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 aracı yetkisiz bir kullanıcı altında kurmanız, model API anahtarınızı özel bir dosyaya yerleştirmeniz ve bağlantınız koptuğunda oturumun devam etmesi için tmux içerisinde başlatmanız gerekir. Bu kılavuz, tam olarak bu sırayla bu işlemleri gerçekleştirmektedir.

İsimlendirme ile ilgili bir not kafa karışıklığını önleyecektir. Kanonik depo anomalyco/opencode adresindedir ve Anomaly ekibi (daha önce SST olarak biliniyordu) tarafından sürdürülmektedir; proje geçmişte sst/opencode adresinde bulunuyordu. GitHub üzerinde artık arşivlenmiş olan ve proje ile ilgisi bulunmayan opencode-ai/opencode isimli eski bir depo daha mevcuttur, bu nedenle doğru projenin belgelerini okuduğunuzdan emin olun. Resmi site opencode.ai adresidir.

Neden bir VPS üzerinde OpenCode çalıştırılmalı

Bir kodlama ajanı oturumu uzun sürer. OpenCode, bir yeniden düzenleme (refactor) veya test paketi üzerinde çalışırken dakikalarca zaman harcayabilir; eğer bu işlem dizüstü bilgisayarınızda çalışıyorsa, kapağın kapanması veya Wi-Fi bağlantısının kopması oturumu görev ortasında sonlandırır. tmux içindeki bir VPS üzerinde ise, siz bağlantıyı kesseniz bile ajan çalışmaya devam eder ve daha sonra neler yaptığını görmek için oturuma tekrar bağlanabilirsiniz. Bu, tmux ile bir VPS üzerinde Claude Code çalıştırma ile aynı yöntemdir ve bir ajanı dizüstü bilgisayarınızdan taşımanın sağladığı en büyük yaşam kalitesi artışıdır.

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

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

OpenCode için özel bir kullanıcı oluşturun

Dürüst başlangıç noktası şudur: bir kodlama ajanı dosyaları düzenler ve komutlar çalıştırır. İşi budur ve risk de burada yatar. OpenCode derlemeleri, testleri ve görevin gerektirdiği her türlü kabuk komutunu çalıştıracaktır; modelin muhakemesi iyidir ancak kusursuz değildir. Ajanın çalıştığı hesap, hatalı bir komutun erişebileceği sınırları belirler; bu nedenle ajanı root olarak veya sunucuyu yöneten kullanıcı ile aynı kullanıcı altında çalıştırmayın.

Arka plan ajanlarının aksine OpenCode etkileşimlidir, bu yüzden kullanıcısının gerçek bir kabuğa ve bir ev dizinine ihtiyacı vardır:

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

Üzerinde çalışmasını istediğiniz projeleri /home/opencode altında tutun ve bu kullanıcı tarafından klonlanmasını sağlayın. Hesaba hiçbir sudo yetkisi vermeyin. Ajan yıkıcı bir komut çalıştırırsa, yalnızca bu hesabın sahip olduğu dosyaları yok edebilir; bu, servisleri yetkisiz kullanıcı olarak çalıştırma ile aynı mantıktır. Ayrıca bir git deposu içinde çalışın ve ajana bir görev vermeden önce commit yapın; çünkü commit edilmiş çalışmalara yapılan hatalı bir düzenleme, veri kaybı yerine bir git revert veya git restore uzaklığında olacaktır. Commit etmediğiniz değişiklikler korunmaz.

OpenCode Kurulumu

Proje belgelerinde çeşitli kurulum yöntemleri yer alır ve bunlardan ikisi sunucu kullanımı için uygundur. Kurulum betiği en hızlı yöntemdir ve bu betiği opencode kullanıcısı olarak çalıştırmak, tüm dosyaların ilgili kullanıcının ev dizininde kalmasını sağlar:

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

Sunucularda dikkat edilmesi gereken genel curl | bash alışkanlığı burada da geçerlidir: Önem verdiğiniz bir sunucuda betiği önce indirin, içeriğini inceleyin ve ardından çalıştırın. Kurulumdan sonra, yükleyicinin yaptığı PATH değişikliğinin geçerli olması için yeni bir kabuk (shell) başlatın ve ardından ikili dosyanın yanıt verip vermediğini kontrol edin:

opencode --version

Eğer bir paket yöneticisi tercih ediyorsanız ve sunucuda Node.js halihazırda yüklüyse, npm yöntemi aynı aracı npm'in genel önek dizinine kurar:

sudo npm install -g opencode-ai

Sistem genelinde bir Node.js kurulumunda bu önek genellikle /usr/local veya /usr dizinidir ve bunun bin dizini her kullanıcının PATH değişkeninde yer alır. Bir sürüm yöneticisi veya özel bir önek, ikili dosyayı başka bir konuma yerleştirebilir; bu nedenle opencode aracının opencode kullanıcısı tarafından bulunması gerekiyorsa önce npm prefix -g komutunu çalıştırın.

Hangi yöntem seçilirse seçilsin, kontrol aynıdır: opencode --version bir sürüm numarası çıktısı verir. Betik kurulumundan sonra alınan bir command not found hatası, mevcut kabuğun güncellenmiş PATH değişkenini henüz okumadığı anlamına gelir; bu durumda oturumu kapatıp opencode kullanıcısı olarak tekrar giriş yapın.

Her iki komut da OpenCode 1.x serisini kurar. Bu seri hala yeni sürümler yayınlamaktadır (16 Ekim 2026 itibarıyla 1.19.3) ve bu kılavuz bu seriyi temel almaktadır. OpenCode 2 artık https://opencode.ai/v2/install veya @opencode/cli npm paketi üzerinden ayrı bir kurulum olarak sunulmaktadır ve farklı bir çalışma mantığına sahiptir: Kullanıcı hesabı başına paylaşılan bir arka plan sunucusu oturumları, izinleri ve araç yürütme işlemlerini yönetir; terminal ise bu sunucuya bağlanır. Geçiş kılavuzu, her iki sürüm de opencode komutunu kullandığı için, 2. sürümü kurmadan önce paket yöneticisi ile kurulan 1.x sürümünün kaldırılmasını önerir.

API anahtarını özel bir dosyaya yerleştirin

OpenCode, kullandığınız model sağlayıcısı için bir anahtara ihtiyaç duyar. Bu anahtar harcama yapmanıza olanak tanıdığı için onu bir parola gibi koruyun. Yalnızca opencode kullanıcısının okuyabileceği, 600 moduna sahip bir dosya oluşturun ve anahtarı komut satırına yazıp shell geçmişinize düşmesine neden olmak yerine bu dosyada saklayın:

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

Sağlayıcınızın değişkenini bu dosyaya ekleyin; örneğin ANTHROPIC_API_KEY=... veya sağlayıcınız için eşdeğer olan değişkeni kullanın, çünkü OpenCode standart sağlayıcı ortam değişkenlerini otomatik olarak algılar. Ajanı başlatmadan önce dosyayı shell ortamınıza yükleyin:

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

OpenCode ayrıca etkileşimli bir alternatif de sunar: TUI içindeki /connect komutu, bir sağlayıcı ekleme sürecinde size rehberlik eder ve kimlik bilgilerini kullanıcının ev dizinindeki ~/.local/share/opencode/auth.json dosyasına kaydeder. Bu yöntemi kullanırsanız, dosyanın gizliliğini chmod 600 ~/.local/share/opencode/auth.json ile doğrulayın. Her iki yöntem de anahtarın komut satırlarınızda görünmesini engeller; birini seçin ve tutarlı bir şekilde kullanın.

OpenCode uygulamasını tmux içinde başlatma

tmux, VPS kurulumunu değerli kılan araçtır; çünkü bir SSH bağlantısı koptuğunda tmux oturumu çalışmaya devam eder. Bir oturum başlatın, proje dizininize geçin ve ajanı çalıştırın:

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

Alt kısımda bir komut satırı ve arayüzde proje adınızın yer aldığı TUI ekranının açıldığını görmelisiniz. Ajana yalın bir dille bir görev verin; ajan dosyaları okumaya ve değişiklikler önermeye başlayacaktır. Ayrılmak istediğinizde Ctrl-b ve ardından d tuşlarına basarak oturumu ayırın; siz bilgisayarınızı kapatsanız bile ajan çalışmaya devam edecektir. Daha sonra şu komutla tekrar bağlanın:

tmux attach -t opencode

Oturum, konuşma geçmişi ve devam eden tüm görevler tam olarak bıraktığınız şekilde kalır. Bu yapı bağlantı kopmalarına karşı dayanıklıdır ancak sunucu yeniden başlatıldığında oturum kapanır; bu nedenle yeniden başlatma sonrasında aynı yöntemle yeni bir tmux oturumu başlatmanız gerekir. İkinci bir tmux penceresi açıp ilkinin yanında başka bir ajan çalıştırmanızın önünde bir engel yoktur. OpenCode oturumları birbirinden bağımsız kalır; oysa aynı sunucudaki Claude Code oturumları birbirlerine mesaj gönderebilir, bu da bir işi ikiye bölmek için farklı bir yöntemdir.

Bir modele yönlendirme yapın

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 düzinelerce başka sağlayıcıyla çalışır. En hızlı yöntem, TUI içindeki /connect komutunu kullanmaktır; bu komut sağlayıcıları listeler ve kimlik bilgilerini yönetir. Commit edilebilir ve yeniden üretilebilir bir kurulum için proje kök dizinine bir opencode.json yerleştirin ve modeli provider/model-id olarak ayarlayın:

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

Sağlayıcınızın hala desteklediği bir model seçin: Anthropic, claude-sonnet-4-20250514 modelini 15 Haziran 2026 tarihinde kullanımdan kaldırmıştır, bu nedenle bu modeli içeren yapılandırmalar başarısız olur.

Yerel bir model de aynı dosya üzerinden çalışır, çünkü OpenAI uyumlu herhangi bir sunucu sağlayıcı olarak tanımlanabilir. Bir modeli aynı VPS üzerinde Ollama ile sunuyorsanız, yapılandırma yerel API'ye 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" } }
    }
  }
}

Yerleşik bir alışkanlığı ilk günden benimsemek faydalıdır. OpenCode, Tab tuşuyla geçiş yapabileceğiniz iki ajanla gelir: Tam erişime sahip varsayılan ajan olan Build ve analiz için kullanılan, kendi plan dizini dışındaki dosya düzenlemelerini onay almadan reddeden kısıtlı ajan olan Plan. Plan ajanı kesinlikle salt okunur değildir; çünkü hala shell komutları çalıştırabilir ve bir shell komutu dosyaları değiştirebilir. Yeni bir görevi Plan ile başlatın, kodları okumasını ve bir yaklaşım önermesini sağlayın; yalnızca plan üzerinde mutabık kaldığınızda Build moduna geçin. İlk aşamanın tamamen salt okunur olmasını istiyorsanız, opencode.json dosyasında Plan için düzenlemeleri ve shell komutlarını engelleyin; çünkü OpenCode deny değerini eylemi engelleme olarak kabul ederken, ask değeri yalnızca onayınızı ister:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

Bir sunucuda, hiçbir şeyi değiştiremeyen bir ilk geçiş ucuz bir sigortadır. Claude Code aynı kararı ajanlar yerine izin modları olarak tanımlar ve otomatik moda geçişin varsayılan olması, her iki aracı da kullanıyorsanız okunması gereken bir konudur; çünkü bir oturumun hangi modda başladığı, izlenmeyen bir ajanın ne kadar değişiklik yapabileceğini belirler.

Etki alanı ve riskler

Kodlama ajanı pasif bir araç değildir; bu nedenle kurulumun neleri içerip neleri içermediğini açıkça belirtmek gerekir. Kurulum dosya hasarı riski taşır: opencode kullanıcısı yalnızca kendi ev dizinine sahiptir, bu nedenle düzenleme ve silme işlemleri bu sınırda durur. Kimlik bilgisi ifşası riski taşır: anahtar, 600 moduna sahip tek bir dosyada ve tek bir hesapta tutulur. Kurulum, hesabın meşru olarak yapabileceklerini kısıtlamaz; bu nedenle proje dizini üretim ortamına ait dağıtım kimlik bilgilerini içeriyorsa, ajan bunları kullanabilir. Bu tür bilgileri ajanın hesabından tamamen uzak tutun.

OpenClaw gibi bir ağ geçidi ajanının aksine, OpenCode 1.x bir daemon değil, etkileşimli bir terminal programıdır. Varsayılan olarak hiçbir port dinlemez (yalnızca --port, --hostname veya --mdns bayrakları TUI'nin dinleme yapmasını sağlar) ve arka planda çalışan bir servisi yoktur; bu nedenle yazılacak bir systemd birimi veya ajan için güvenlik duvarında açılacak bir port bulunmaz. OpenCode 2, paylaşımlı arka plan sunucusu ile bu durumu değiştirir; bu nedenle sürüme geçiş yapmadan önce bu noktayı tekrar kontrol edin. Kapsama alanı kullanıcı hesabı ve proje dizini ile sınırlıdır; bu kılavuzun ilk bölümünün en önemli kısım olmasının nedeni budur.

Kodlama VPS'i hala halka açık bir sunucu olduğu için, çevresindeki koruma standart özen gerektirir: VPS üzerinde SSH sıkılaştırma başlığında belirtildiği gibi root girişi devre dışı bırakılmış, yalnızca anahtar ile erişilen SSH, varsayılan olarak reddeden bir güvenlik duvarı ve düzenli güncellemeler şarttır. Ayrıca ajanın ürettiği çıktıları inceleyin. Değişiklikleri (diff) push etmeden önce, yeni bir katılımcıdan gelen bir pull request'i okur gibi okuyun; çünkü sonucu dağıtıma alan kişi sizsiniz.

Son olarak, aracın kendisini güncel tutun. OpenCode sık sık sürüm yayınlar ve güncellemeler, sunucunuzda komut çalıştıran bir program için kritik öneme sahip düzeltmeler içerir. Güncelleme işlemi, kurulumu yaptığınız yöntemle aynıdı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 kullanın, ardından opencode --version ile yeni sürümü doğrulayın. Her iki yöntem de sizi 1.x hattında tutar; OpenCode 2'ye geçiş ayrı bir taşıma sürecidir. Zaman zaman yapılacak bir dakikalık bakım, aylar öncesine ait bir sürümde zaten düzeltilmiş olan hataları ayıklamaktan daha az maliyetlidir.

FAQ

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

Evet. OpenCode, OpenAI uyumlu her sunucuyu bir sağlayıcı olarak kabul eder; bu nedenle aynı VPS üzerinde Ollama tarafından sunulan bir model çalışabilir. Sağlayıcıyı opencode.json içerisinde yerel baseURL ve Ollama'nın bildirdiği model adıyla tanımlayın. Buradaki kısıtlayıcı faktör donanımdır; gerçek kodlama işleri için yeterli olan bir model ciddi miktarda bellek gerektirir, bu nedenle modeli indirmeden önce sunucuyu modelin ihtiyaçlarına göre boyutlandırın.

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

VPS üzerinde tmux içerisinde çalıştırın. Ajanı tmux new -s opencode ile adlandırılmış bir oturumda başlatın, Ctrl-b ve ardından d tuşlarına basarak oturumdan ayrılın; SSH bağlantınız kesilse bile oturum sunucuda çalışmaya devam eder. tmux attach -t opencode ile istediğiniz zaman tekrar bağlandığınızda konuşma ve devam eden tüm görevler orada olacaktır. Sunucunun yeniden başlatılması oturumu sonlandırır, bu nedenle yeniden başlatma sonrasında yeni bir oturum başlatın.

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

Sınırlandırıldığı takdirde yönetilebilir bir durumdur. OpenCode'a sudo yetkisi olmayan, özel ve düşük ayrıcalıklı bir kullanıcı tanımlayın. Projelerini git içerisinde tutun ve her görevden önce commit yapın; böylece hatalı bir düzenleme geri alınabilir. API anahtarını 600 moduna sahip bir dosyada saklayın. İlk aşama için Plan ajanını kullanın; Build ajanının herhangi bir değişiklik yapmasına izin vermeden önce bu aşamayı gerçekleştirin. Eğer bu aşamanın sadece salt okunur olmasını istiyorsanız, düzenlemeleri ve kabuk komutlarını deny olarak ayarlayın. Bu durumda ajan yalnızca kendi hesabının sahip olduğu dosyalara zarar verebilir ve sunucunun geri kalanı erişim alanı dışında 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ğlanır. Claude Code ise Anthropic'in kendi modelleri etrafında inşa edilmiş, Anthropic'e ait bir terminal ajanıdır. Birçok sağlayıcıda tek bir araç kullanmak veya yerel bir modelle tamamen kendi kendine barındırılan bir yığın oluşturmak istiyorsanız OpenCode uygun bir tercihtir; her ikisi de aynı düşük ayrıcalıklı kullanıcı kurulumuyla bir VPS üzerinde tmux içinde iyi çalışır.