VPS Uzerinde OpenHands Kurulumu ve Guvenlik Rehberi

OpenHands nedir ve öncelikle bilinmesi gereken risk

OpenHands, eski adıyla OpenDevin, otonom bir yazılım geliştirme aracıdır. Kendisine yalın bir dille görev verdiğinizde; işi planlar, kod yazar, komutları çalıştırır, çıktıları okur ve görev tamamlanana kadar süreci yineler. Yazılımı kendi sunucunuzda Docker ile çalıştırır ve bir dil modeline yönlendirirsiniz. Bir VPS üzerinde, siz yokken de çalışan bir kodlama aracına dönüşür.

Kurulumunuzu şekillendirmesi gereken temel bir gerçek vardır. OpenHands yalnızca kod önermekle kalmaz, aynı zamanda bu kodu çalıştırır. Bunu yapabilmek için kontrolcü container'ı, her görev için sandbox container'ları oluşturabilmek amacıyla ana makinenin Docker socket'ini /var/run/docker.sock konumuna bağlar. Docker socket ile iletişim kurabilen her şey, ana makinenin tüm dosya sistemini bağlayan yeni bir container başlatabilir; bu da socket erişiminin makine üzerinde fiilen root yetkisine sahip olmak anlamına geldiği sonucunu doğurur. Dolayısıyla OpenHands sunucusunu, güvenilmeyen kodları çalıştıran bir sistem olarak değerlendirin; çünkü yaptığı iş tam olarak budur. Aşağıdaki tüm güvenlik sıkılaştırma tercihleri bu gerçeğe dayanmaktadır.

Gereksinimler

Ubuntu 24.04 çalıştıran, güncel bir Docker Engine sürümüne sahip, en az 4 GB RAM içeren bir VPS'e ihtiyacınız vardır. Ayrıca bir dil modeli (OpenAI, Anthropic veya Google) için API anahtarına ya da aynı VPS üzerinde Ollama ile sunulan yerel bir modele sahip olmanız gerekir. OpenHands onlarca model arka ucunu desteklediği için seçim size aittir. Daha önce hiç container kurulumu yapmadıysanız, VPS üzerinde Docker temelleri başlıklı rehber, bu kılavuzun varsaydığı temel bilgileri kapsamaktadır.

Docker ile kurulum

OpenHands iki imaj olarak sunulur: çalıştırdığınız uygulama imajı ve her görevin sandbox ortamını çalıştırmak için çektiği agent-server imajı. Proje belgelerindeki güncel etiketleri kullanarak şu şekilde çalıştırın:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

İki detay, bir saatlik kafa karışıklığından tasarruf etmenizi sağlar. Uygulama imajı ve agent-server imajı kasıtlı olarak farklı sürüm numaralarına sahiptir, bu yüzden bunları eşleştirmeye çalışmayın: belgelerde uygulama sürümünüzle eşleştirilen agent-server etiketini kullanın. Ayrıca -p 3000:3000 yerine -p 127.0.0.1:3000:3000 kullanımına dikkat edin. Bu tek değişiklik, yalnızca sizin erişebileceğiniz bir Web arayüzü ile tüm internetin erişebileceği bir arayüz arasındaki farktır; bir sonraki bölüm bununla ilgilidir.

Web arayüzünü genel internete kapalı tutun

OpenHands, arayüzünü 3000 numaralı port üzerinden sunar. Bu arayüz, kod çalıştıran bir ajanı yönettiği için, arayüzü internete açmak, onu bulan herkese komut yürüten bir sürece uzaktan erişim yolu sağlar. Yukarıdaki çalıştırma komutunda olduğu gibi arayüzü loopback adresine bağlayın ve kendi dizüstü bilgisayarınızdan bir SSH tüneli aracılığıyla erişin:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Ardından kendi makinenizde http://127.0.0.1:3000 adresini açın. Trafik mevcut SSH oturumunuz üzerinden iletilir ve genel internet üzerinde dinleme yapan yeni bir servis oluşmaz. Her ajanın bir porta ihtiyacı yoktur: Aynı VPS üzerindeki Claude Code oturumları terminal üzerinden birbirleriyle haberleşir, bu nedenle dışarıya açtığınız tek şey SSH'ın kendisidir. Aynı loopback ve tünel alışkanlığını barındırdığınız tüm ajan panelleri için sürdürmelisiniz; open-kritt tarama arayüzüne tünel üzerinden erişmek aynı şekilde çalışır, sadece 5173 numaralı port kullanılır. Daha kalıcı bir kurulum için arayüzü bir VPN arkasına alın. Her iki durumda da, yanlışlıkla hiçbir şeyin açığa çıkmaması için sunucunun önüne varsayılan olarak reddeden (default-deny) bir güvenlik duvarı yerleştirin. Sadece IPv4'ü kapsayan bir güvenlik duvarının, aynı portu IPv6 üzerinde açık bıraktığını unutmayın; bu, birçok kişinin karşılaştığı IPv6 güvenlik duvarı açığıdır.

Model anahtarını ve depo kimlik bilgilerini izole edin

OpenHands, model için bir API anahtarına ve genellikle depolarınızı klonlamak veya deponuza veri göndermek için bir erişim belirtecine (token) ihtiyaç duyar. Her ikisi de maliyet oluşturabilir ve sizin adınıza işlem yapabilir; bu nedenle bunları parola gibi değerlendirin. Bu bilgileri yalnızca ilgili hesabın okuyabileceği bir ortam dosyasında saklayın. Bilgileri asla shell geçmişinize ve süreç listesine yansıyacak olan çalıştırma komutlarının içine yazmayın; ayrıca git deposu içindeki hiçbir dosyada bulundurmayın. Orijinal bilgileri kendi barındırdığınız (self-hosted) bir parola yöneticisinde tutuyorsanız, o sunucuyu da sıkılaştırın. Çünkü bir kasanın zayıf noktaları, şifrelenmiş öğelerin kendisinden ziyade yönetici belirteci ve yedekleme dosyasıdır; Vaultwarden sıkılaştırma adımları bu süreç üzerinde çalışır.

Gözden çıkarılabilir bir sunucuda çalıştırın

Controller, Docker socket'ine erişim gerektirdiği için OpenHands'i ana makinesinden tamamen izole etmeniz mümkün değildir. Bu durumun dürüst çözüm yolu, yerleşim bazlı izolasyondur: OpenHands'i veritabanınızın veya web sitenizin çalıştığı sunucuda değil, içinde sizin için önemli başka hiçbir şeyin bulunmadığı özel bir VPS üzerinde çalıştırın. Başlamadan önce bir snapshot alın ve bir hafta boyunca ajan tarafından yazılmış kodları çalıştıran bir sunucuya güvenmek yerine, sistemi bu snapshot üzerinden yeniden oluşturun. Ucuz, tek kullanımlık ve tek amaçlı bir VPS, bu uygulama için en doğru ortamdır. Yerleşim, OpenHands'in size sunduğu tek güvenlik kontrolüdür; bu nedenle ajanın durup onay istemeden önce ne kadar işlem yapabileceğini de kontrol etmek isterseniz, Claude Code'un izin modları kimsenin izlemediği bir sunucuda bu ikinci kontrol mekanizmasının nasıl göründüğünü açıklamaktadır.

Sunucuyu çevreleyen katmanı güçlendirme

Geri kalan işlemler standart sunucu hijyenidir ve iş yükü normalden daha riskli olduğu için burada her zamankinden daha fazla önem taşır. root kullanıcısı olarak çalışmak yerine, ayrıcalıksız kullanıcı olarak servisleri çalıştırma rehberini izleyerek yetkisiz bir yönetici kullanıcısı oluşturun. SSH bağlantısını yalnızca anahtar tabanlı kimlik doğrulamaya geçirin. Ardından aşağıdaki kontrol listesini uygulayın ve tekrar görebileceğiniz bir yerde saklayın.

Bileşenlerin nasıl çalıştığını anlamak için kendi yapay zeka temsilcinizi bir VPS üzerinde oluşturma rehberine göz atın; daha az kod gerektiren bir platform için Dify self-hosting daha kolay bir başlangıç noktasıdır.

FAQ

OpenHands sunucuda çalıştırmak için güvenli midir?

Dikkatli olunduğunda güvenli olabilir, ancak kod yazıp çalıştırdığı ve kontrolcüsü ana makinenin Docker soketini tuttuğu için sıradan bir web uygulamasından daha risklidir; bu durum makinede root yetkisine sahip olmakla eşdeğerdir. Uygulamayı, içinde başka değerli veri barındırmayan, tek kullanımlık ve özel bir VPS üzerinde çalıştırın; Web arayüzünü bir SSH tüneli veya VPN arkasında, loopback üzerinde tutun; anahtarlarını izole edin ve sunucuyu sıkılaştırın. Önemli servislerinizin yanında çalıştırmayın.

OpenHands neden Docker soketine ihtiyaç duyar?

OpenHands her görevi yeni bir sandbox container içinde çalıştırır ve bu container'ları oluşturmak için ana makinedeki Docker daemon'dan, /var/run/docker.sock dosyasını kendi kontrolcüsüne mount ederek yardım ister. Bu durum, kontrolcü container'ına ana makinedeki Docker üzerinde tam yetki verir; bu oldukça güçlü ve riskli bir durumdur, bu nedenle ana makinenin kendisi güvenilmeyen kod çalıştıran bir sistem olarak ele alınmalıdır.

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

Evet. OpenHands, Ollama veya vLLM tarafından sunulan yerel modelleri destekler; böylece token başına ücret ödemeden ve hiçbir veri sunucunuzdan çıkmadan tamamen kendi kendine barındırılan (self-hosted) bir yapıda çalıştırabilirsiniz. Kodlama yeteneği yüksek bir model için yeterli belleğe sahip bir makineye ihtiyacınız vardır; bu, Ollama rehberinde ele alınan boyutlandırma gereksinimleriyle aynıdır.

OpenHands uygulamasını ana sunucumda çalıştırmalı mıyım?

Hayır. Ajan tarafından yazılan kodları çalıştırdığı ve Docker soketini tuttuğu için, onu yeniden kurmaya hazır olduğunuz, ayrı ve tek amaçlı bir VPS üzerinde tutun. Onu bir veritabanı, web sitesi veya diğer servislerinizle aynı sunucuda barındırmak, ajan tarafından yapılan bir hatanın veya ajandaki bir bug'ın, asla erişmemesi gereken yerlere ulaşabileceği anlamına gelir.