OpenHands VPS Üzerine Nasıl Kurulur?

OpenHands Nedir ve Öncelikle Anlaşılması Gereken Tek Risk

Eski adıyla OpenDevin olan OpenHands, otonom bir yazılım mühendisliği ajanıdır. Ona düz dilde bir görev verirsiniz; o da işi planlar, kod yazar, komutları çalıştırır, çıktıyı okur ve görev tamamlanana kadar iterasyon yapar. Docker ile kendi sunucunuzda çalıştırabilir ve bir dil modeline yönlendirebilirsiniz. Bir VPS üzerinde, siz uzaktayken çalışan bir kodlama ajanı haline gelir.

Tüm kurulumunuzu şekillendirecek bir gerçek vardır. OpenHands sadece kod önermez, kodu çalıştırır; bunu yapabilmek için kontrolcü konteyneri, her görev için sandbox konteynerleri oluşturabilmek amacıyla host Docker socket'ini /var/run/docker.sock konumuna bağlar. Docker socket ile iletişim kurabilen her şey, tüm host dosya sistemini bağlayan yeni bir konteyner başlatabilir; bu da socket erişiminin makinede etkili olarak root yetkisine sahip olması demektir. Bu nedenle, OpenHands makinesini güvenilmeyen kod çalıştıran bir sunucu olarak değerlendirin, çünkü tam olarak bunu yapar. Aşağıdaki tüm sıkılaştırma seçimleri bu durumdan kaynaklanmaktadır.

İhtiyacınız olanlar

Güncel bir Docker Engine yüklü Ubuntu 24.04 çalışan bir VPS'e, en az 4 GB RAM'e ve bir dil modeli için API anahtarına (OpenAI, Anthropic veya Google) veya aynı VPS üzerinde Ollama ile sunulan yerel bir modele ihtiyacınız vardır. OpenHands onlarca model backend'ini destekler, bu nedenle seçim size aittir. Daha önce hiç konteyner kurulumu yapmadıysanız, bir VPS üzerinde Docker temelleri bu kılavuzun varsaydığı konuları kapsamaktadır.

Docker ile kurulum

OpenHands iki imaj olarak sunulur: çalıştırdığınız uygulama imajı ve her görevin sandbox'ını çalıştırmak için çektiği agent-server imajı. Projenin dokümanlarındaki güncel tag'leri 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 sizi bir saatlik kafa karışıklığından kurtarır. Uygulama imajı ve agent-server imajı bilerek farklı versiyon numaralarına sahiptir, bu yüzden bunları eşitlemeye çalışmayın: dokümanların uygulamanızın versiyonuyla eşleştirdiği agent-server tag'ini kullanın. Ayrıca -p 3000:3000 yerine -p 127.0.0.1:3000:3000 kullanıldığını fark edin. Bu tek değişiklik, sadece sizin erişebileceğiniz bir Web UI ile tüm internetin erişebileceği bir Web UI arasındaki farktır; bir sonraki bölüm bunun hakkındadır.

Web UI'ı genel internetten uzak tutun

OpenHands arayüzünü 3000 portundan sunar. Bu arayüz kod çalıştıran bir ajanı yönetir, bu nedenle arayüzü internete açmak, onu bulan herhangi birine komut yürüten bir sürece uzaktan erişim yolu sağlar. Yukarıdaki çalıştırma komutunda yapıldığı gibi loopback'e bağlayın ve bir SSH tüneli üzerinden dizüstü bilgisayarınızdan erişin:

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

Ardından kendi makinenizde http://127.0.0.1:3000 portunu açın. Trafik mevcut SSH oturumınız üzerinden iletilir ve genel internette yeni bir dinleyici bulunmaz. Daha kalıcı bir kurulum için bunun yerine bir VPN arkasına koyun. Her iki durumda da, hiçbir şeyin kazara dışarı açılmaması için makinenin önüne varsayılan olarak reddeden (default-deny) bir firewall koyun ve yalnızca IPv4'ü kapsayan bir firewall'un aynı portu IPv6 üzerinde açık bırakacağını unutmayın; bu, birçok kişiyi yakalayan IPv6 firewall boşluğu durumudur.

Model anahtarını ve tüm repo kimlik bilgilerini izole edin

OpenHands, modeli için bir API anahtarına ve genellikle depolarınıza clone/push yapmak için bir token'a ihtiyaç duyar. Her ikisi de para harcayabilir ve sizin adınıza işlem yapabilir, bu nedenle bunlara şifre gibi davranın. Bunları yalnızca doğru hesabın okuyabileceği bir ortam dosyasında (environment file) tutun; asla shell geçmişinize ve işlem listesine düşecek olan çalıştırma komutuna veya bir git deposu içindeki bir dosyaya yazmayın.

Atılabilir bir makinede çalıştırın

Kontrolcü Docker socket'ini tutmak zorunda olduğundan, OpenHands'ı host makineden tamamen izole edemezsiniz. Gerçek çözüm yerleşim yoluyla izolasyondur: OpenHands'ı veritabanınızın veya web sitenizin de çalıştığı sunucuda değil, içinde sizin için önemli olan başka hiçbir şey bulunmayan özel bir VPS üzerinde çalıştırın. Başlamadan önce bir snapshot alın ve bir hafta boyunca ajan tarafından yazılmış kod çalıştıran bir makineye güvenmek yerine o snapshot'tan yeniden kurulum yapın. Ucuz, tek kullanımlık ve tek amaçlı bir VPS, onun için doğru yerdir.

Makineyi etrafından sıkılaştırın

Geri kalanı standart sunucu hijyenidir ve iş yükü normalden daha riskli olduğu için burada normalden daha önemlidir. servisleri yetkisiz bir kullanıcı olarak çalıştırma konusunu takip ederek, root olarak çalışmak yerine yetkisiz bir admin kullanıcısı oluşturun. SSH'ı yalnızca anahtar tabanlı kimlik doğrulamaya geçirin. Ardından aşağıdaki kontrol listesini uygulayın ve bunu tekrar göreceğiniz bir yerde saklayın.

Parçaları sadece çalıştırmak yerine mantığını anlamak için bir VPS üzerinde kendi AI ajanınızı oluşturun konusuna bakın; daha az kod gerektiren bir platform için Dify self-hosting daha yumuşak bir başlangıçtır.

FAQ

OpenHands bir sunucuda güvenli bir şekilde çalıştırılabilir mi?

Dikkatli olunursa olabilir, ancak kod yazdığı ve çalıştırdığı, ayrıca kontrolcüsü makinede etkili olarak root yetkisine sahip olan host Docker socket'ini tuttuğu için normal bir web uygulamasından daha risklidir. Onu değerli hiçbir şey barındırmayan özel, tek kullanımlık bir VPS üzerinde çalıştırın, Web UI'ını bir SSH tüneli veya VPN arkasında loopback üzerinde tutun, anahtarlarını izole edin ve makineyi sıkılaştırın. Onu önemli servislerinizin yanında çalıştırmayın.

OpenHands neden Docker socket'ine ihtiyaç duyar?

OpenHands her görevi yeni bir sandbox konteyneri içinde çalıştırır ve host Docker daemon'ından, /var/run/docker.sock bileşenini kontrolcüsüne bağlayarak bu konteynerleri oluşturmasını ister. Bu, kontrolcü konteynerine host üzerindeki Docker üzerinde kontrol sağlar; bu güçlü ve riskli bir durumdur, bu nedenle host'un kendisi güvenilmeyen kod çalıştıran bir makine 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 maliyet olmadan ve verileriniz sunucunuzdan ayrılmadan tamamen kendi kendine barındırılan (self-hosted) bir şekilde çalıştırabilirsiniz. Yetenekli bir kodlama modeli için yeterli belleğe sahip bir makineye ihtiyacınız vardır, bu da Ollama kılavuzunda ele alınan boyutlandırma sorusuyla aynıdır.

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

Hayır. Ajan tarafından yazılmış kod çalıştırdığı ve Docker socket'ini tuttuğu için, onu yeniden kurmaya hazır olduğunuz ayrı, tek amaçlı bir VPS üzerinde tutun. Onu bir veritabanı, bir web sitesi veya diğer servislerinizle aynı yere koymak, ajanın bir hata yapması veya içindeki bir bug nedeniyle, dokunmaması gereken şeylere erişebileceği anlamına gelir.