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 2026 yılı 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 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 işlemleri gerçekleştirmektedir.

İsimlendirme ile ilgili bir not kafa karışıklığını önleyecektir. Kanonik depo, Anomaly ekibi (daha önce SST olarak biliniyordu) tarafından sürdürülen anomalyco/opencode adresidir ve proje geçmişte sst/opencode adresinde barındırılıyordu. GitHub üzerinde opencode-ai/opencode adında, proje ile ilgisi olmayan daha eski bir depo daha bulunmaktadır; 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

İşin doğrusu şudur: bir kodlama ajanı dosyaları düzenler ve komutlar çalıştırır. İşi budur ve risk de buradan kaynaklanır. OpenCode derlemeler, testler 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ırıldığı hesap, hatalı bir komutun erişebileceği sınırları belirler; bu nedenle uygulamayı root olarak veya sunucuyu yöneten kullanıcı ile çalıştırmayın.

Arka plan ajanlarının aksine OpenCode etkileşimlidir, bu nedenle 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 verileri yok edebilir; bu mantık servisleri yetkisiz kullanıcı ile çalıştırma prensibiyle aynıdır. Ayrıca bir git deposu içinde çalışın, çünkü bir depo hatalı bir düzenlemeyi kayıp yerine bir git revert haline getirir.

OpenCode Kurulumu

Proje iki farklı kurulum yöntemi sunar. 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

Her yerde olduğu gibi burada da standart curl | bash alışkanlığı geçerlidir: önemsediğiniz bir sunucuda betiği önce indirin, içeriğini okuyun 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 halihazırda Node.js yüklüyse, npm yöntemi aynı aracı sistem genelinde kurar; bu da opencode ikili dosyasını tüm kullanıcılar için PATH dizinine ekler:

sudo npm install -g opencode-ai

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ğerini henüz okumadığı anlamına gelir; bu durumda oturumu kapatıp opencode kullanıcısı olarak tekrar giriş yapın.

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

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; böylece 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. Kaydedilebilir ve tekrarlanabilir 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-4-20250514"
}

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'sine 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 edinilmesi gereken yerleşik bir alışkanlık vardır. OpenCode, Tab tuşuyla geçiş yapabileceğiniz iki aracı (agent) beraberinde getirir: Tam erişime sahip varsayılan araç 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ını ve bir yaklaşım önerilmesini sağlayın; yalnızca plana onay verdiğinizde Build moduna geçin. Bir sunucuda, salt okunur bir ilk geçiş ucuz bir güvenlik önlemidir. Claude Code aynı kararı araçlar yerine izin modları olarak tanımlar ve otomatik moda varsayılan olarak geçişi, her iki aracı da kullanıyorsanız okumaya değerdir; çünkü bir oturumun hangi modda başladığı, denetlenmeyen bir aracın ne kadar değişiklik yapabileceğini belirler.

Etki alanı ve risk yönetimi

Bir kodlama ajanı pasif değildir; bu nedenle bu kurulumun neleri kapsayıp neleri kapsamadığını açıkça belirtmek gerekir. Kurulum dosya hasarı riskini barındırır: opencode kullanıcısı yalnızca kendi ev dizininin sahibidir, bu nedenle düzenleme ve silme işlemleri bu sınırda durur. Kurulum kimlik bilgisi ifşası riskini barındırır: anahtar, 600 moduna sahip tek bir dosyada ve tek bir hesapta tutulur. Kurulum, hesabın meşru olarak neler yapabileceğini sınırlamaz; 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 bir daemon değil, etkileşimli bir terminal programıdır. Herhangi bir port dinlemez 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. 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 güvenlik önlemleri standart bir özen gerektirir: VPS üzerinde SSH sıkılaştırma başlığında belirtildiği gibi root girişinin devre dışı bırakıldığı anahtar tabanlı SSH, varsayılan olarak reddeden bir güvenlik duvarı ve düzenli güncellemeler şarttır. Ayrıca ajanın ürettiği çıktıları gözden geçirin. Yeni bir katkıcının gönderdiği bir pull request'i nasıl inceliyorsanız, ajanın oluşturduğu diff çıktılarını da push etmeden önce aynı şekilde okuyun; çünkü sonucu dağıtıma çıkaran kişi sizsiniz.

Son olarak, aracın kendisini güncel tutun. OpenCode sık sık yeni sürümler 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. 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çinde 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 yüzden 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çinde ç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 sona erdikten sonra oturum sunucuda çalışmaya devam edecektir. tmux attach -t opencode ile istediğiniz zaman tekrar bağlanın; 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 üzerinde tutun böylece her değişiklik geri alınabilir olsun, API anahtarını 600 moduna sahip bir dosyada saklayın ve Build ajanının herhangi bir şeyi değiştirmesine izin vermeden önce salt okunur bir ilk geçiş için Plan ajanını kullanı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, Anthropic'in kendi modelleri etrafında oluşturulmuş, 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 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.