OpenHands yapay zeka ajan platformu Docker ile nasıl barındırılır

Bir yapay zeka ajan çerçevesi (agent framework), dil modelinin yalnızca metin üretmek yerine çok adımlı görevleri planlamasını ve bunları kabuk komutu çalıştırma, dosya düzenleme veya API çağırma gibi araçlarla uygulamasını sağlar. Çoğu çerçeve kendi uygulamanıza eklediğiniz kütüphanelerdir. OpenHands bunu Python için Software Agent SDK olarak sunar, ancak ek olarak Agent Canvas ile gelir: kodlama ajanlarının depolarınız üzerinde çalıştığı, REST API'li bir ajan sunucusu ve zamanlanmış otomasyonlarla desteklenen, kendi sunucunuzda barındırılan bir web uygulaması. Bu da onu bir sunucu için doğal bir seçenek yapar: tek konteyner, kalıcı durum ve bir tarayıcı arayüzü.

Bunun yerine kendi ajan uygulamanızı geliştirmek istiyorsanız, bakımı aktif olarak süren şu açık kaynaklı çerçeveler yaygın başlangıç noktalarıdır (hepsinin bu rehber kontrol edilmeden önceki haftalarda yeni sürümü vardı):

Bu rehber resmi ghcr.io/openhands/agent-canvas imajını Docker Compose ile çalıştırır. Sürümü sabitler, kendi API anahtarınızı ve gizli anahtarınızı belirler, portu localhost'ta tutar, Canvas'ı bir IP izin listesiyle Caddy üzerinden yayınlar, barındırılan bir model sağlayıcısını veya yerel bir Ollama sunucusunu bağlar ve ajanın erişebileceklerini sınırlarsınız. Ardından yedekleme, güncelleme ve sorun giderme gelir.

Adım 1 — Klasörleri ve gizli değerleri oluşturun

sudo mkdir -p /opt/openhands/state /opt/openhands/projects
sudo chown -R $USER:$USER /opt/openhands
cd /opt/openhands
cat > .env <<EOF
OPENHANDS_VERSION=1.26.0
LOCAL_BACKEND_API_KEY=$(openssl rand -hex 32)
OH_SECRET_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

• state, konteynerde /home/openhands/.openhands olur: ayarlar, saklanan gizli değerler, konuşma geçmişi, çalışma alanları ve otomasyon veritabanı.
• projects, konteynerde /projects olur; ajanın üzerinde çalışmasını istediğiniz depolar için tek yerdir.
• LOCAL_BACKEND_API_KEY sunucunun API anahtarıdır. Her API çağrısı bu anahtarı taşımalıdır ve Canvas'ı açtığınızda tarayıcıya bu anahtarı girersiniz. Belgeler, sunucu localhost dışından erişilebilir olduğunda güçlü bir değer ister.
• OH_SECRET_KEY saklanan ayarları ve gizli değerleri korur. Anahtarlardan birini atlarsanız imaj bir tane üretir ve 600 izniyle state/agent-canvas/ içine kaydeder; ancak ikisini kendiniz belirlemek onları bilinen tek bir yerde tutar.
• OPENHANDS_VERSION imajı sabitler. Sürümler sık çıkar; güncel numarayı OpenHands sürümler sayfasından alın.

Adım 2 — Compose dosyasını yazın ve sahipliği düzeltin

/opt/openhands/compose.yaml dosyasını oluşturun. Dosya, resmi imaj için belgelenen docker run komutunun yeniden başlatma politikası, yalnızca localhost'a açık bir port ve anahtarlarınızla Compose servisi olarak yazılmış halidir:

services:
  openhands:
    image: ghcr.io/openhands/agent-canvas:${OPENHANDS_VERSION}
    container_name: openhands
    restart: unless-stopped
    ports:
      - "127.0.0.1:8000:8000"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - LOCAL_BACKEND_API_KEY=${LOCAL_BACKEND_API_KEY}
      - OH_SECRET_KEY=${OH_SECRET_KEY}
      - AGENT_CANVAS_DISABLE_TELEMETRY=true
    volumes:
      - ./state:/home/openhands/.openhands
      - ./projects:/projects

Bilerek privileged: true ve /var/run/docker.sock bağlaması yoktur. İmaj root olmayan openhands kullanıcısıyla çalışır; bu yüzden iki klasörün o kullanıcının UID ve GID değerlerine ait olması gerekir. Bu değerleri imajdan öğrenin ve sahipliği ayarlayın:

docker compose pull
OH_UID=$(docker compose run --rm -T --entrypoint id openhands -u)
OH_GID=$(docker compose run --rm -T --entrypoint id openhands -g)
echo "$OH_UID:$OH_GID"
sudo chown -R "$OH_UID:$OH_GID" state projects

echo sayıları yazar, örneğin 1000:1000. Daha sonra projects içine depoları kendiniz koymak için sudo kullanın veya ajanın onları klonlamasına izin verin.

Adım 3 — OpenHands'i başlatın ve kontrol edin

docker compose up -d
docker compose ps
docker compose logs --tail 50 openhands
curl -I http://127.0.0.1:8000/canvas

docker compose ps konteyneri 127.0.0.1:8000->8000/tcp ile çalışır göstermeli, curl ise HTTP/1.1 200 OK veya bir yönlendirme döndürmelidir. Konteynerin içinde 8000 numaralı porttaki bir giriş katmanı web arayüzünü, /api yolunu ve WebSocket uç noktasını yalnızca iç portlarda dinleyen ajan sunucusuna ve otomasyon arka ucuna yönlendirir.

Adım 4 — Canvas'ı IP izin listesiyle HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. 198.51.100.24 değerini değiştirerek erişimi çalıştığınız adreslerle sınırlayın; API anahtarı tek kilit değil, ikinci kilittir:

agents.example.com {
    @outside not remote_ip 198.51.100.24
    respond @outside 403
    reverse_proxy 127.0.0.1:8000
}

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://agents.example.com/canvas

OpenHands'in Nginx örneği canlı ajan olayları için WebSocket başlıkları ve bir saatlik zaman aşımları ayarlar. Caddy WebSocket'leri kendiliğinden aktarır ve varsayılan olarak okuma zaman aşımı uygulamaz; bu yüzden ek ayar gerekmez. Bunun yerine Nginx kullanırsanız bu ayarları OpenHands VM rehberinden veya Nginx ve Certbot rehberinden alın.

Adım 5 — Giriş yapın ve bir model sağlayıcısı bağlayın

https://agents.example.com/canvas adresini açın. Docker imajı anahtarını sayfaya eklemediği için Canvas önce anahtarı ister; sunucuda grep LOCAL_BACKEND_API_KEY /opt/openhands/.env ile yazdırın ve yapıştırın.

Ardından LLM ayarlarını açın. Bir LLM Provider ve LLM Model seçin, sağlayıcının API Key değerini girin ve Save Changes düğmesine tıklayın; yeni konuşmalar bu ayarı kullanır, mevcut konuşmaların yeniden başlatılması gerekir. Advanced altında LiteLLM'in desteklediği herhangi bir modeli sağlayıcı öneki ile ve özel bir temel adresle girebilirsiniz. Kaydedilen yapılandırmalar, konuşma başına değiştirebileceğiniz LLM profillerine (en fazla 10) dönüşür.

Belgelere göre OpenHands'in düzgün çalışması için güçlü bir model gerekir. Sağlayıcınızda OpenHands için harcama sınırı olan ayrı bir API anahtarı oluşturun; böylece kontrolden çıkan bir görev sınırsız kullanım biriktiremez.

Adım 6 — Ollama üzerinden yerel bir model kullanın (isteğe bağlı)

Ajan iş yükleri uzun bağlamlara ihtiyaç duyar. OpenHands belgeleri en az 22000 belirteçlik bir Ollama bağlam uzunluğu ister ve varsayılan 4096 değerinin çok küçük olduğu konusunda uyarır. Bunu dinleme adresiyle birlikte bir systemd drop-in dosyasında ayarlayın:

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_CONTEXT_LENGTH=32768"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama
docker network inspect openhands_default | grep Subnet
sudo ufw allow from 172.18.0.0/16 to any port 11434 proto tcp
docker compose exec openhands curl -s http://host.docker.internal:11434/v1/models

172.18.0.0/16 yerine inspect komutunun yazdığı alt ağı kullanın. Bu kural Ollama'yı yalnızca ufw varsayılan reddetme politikasıyla etkinken korur; sudo ufw status verbose çıktısında Status: active ve deny (incoming) göründüğünü ve başka bir makineden nc -vz sunucu-ip-adresiniz 11434 komutunun başarısız olduğunu doğrulayın. Ollama'nın kimlik doğrulaması yoktur; 11434 numaralı portu asla herkese açmayın. Son komut modellerinizi listelemelidir. LLM ayarlarında Advanced görünümüne geçin ve şunları girin:

• Custom Model: openai/ ve ardından ollama list çıktısındaki model adı, örneğin OpenHands rehberinin kullandığı openai/qwen3.6:35b-a3b.
• Base URL: http://host.docker.internal:11434/v1
• API Key: local-llm gibi herhangi bir yer tutucu.

Belgelerdeki örnek model, kuantize sürümler için en az 24 GB belleği olan bir GPU ister ve yerel modellerin işlevlerinin sınırlı olabileceğini belirtir. Yalnızca CPU'lu sunucularda barındırılan bir sağlayıcı kullanın; yerel çıkarım için GPU sunucularına bakın.

Adım 7 — Ajanın sandbox'ını dar tutun

Bu kurulumda sandbox konteynerin kendisidir: ajan komutları içeride openhands kullanıcısı olarak çalıştırır ve yalnızca bağladığınız şeylere ve ağın izin verdiklerine ulaşır. Bu şekilde kalmasını sağlayın:

• İçeride Docker yok. Belgeler, ajanın Docker çalıştırabilmesinin ana makine çekirdeğine geniş erişim veren --privileged gerektirdiğini ve daha güvenli bir ara yol olmadığını açıklar. Bunu eklemeyin ve Docker soketini asla bağlamayın.
• Az şey bağlayın. /opt/openhands/projects içine yalnızca ajanın dokunması gereken depoları koyun. Ajan, kayıtlı sağlayıcı anahtarları dahil state klasörünü de okuyabilir; orada ilgisiz gizli değerler tutmayın.
• Kimlik bilgilerinin kapsamını daraltın. Ajana en az yetkili, depo kapsamlı ve son kullanma tarihli ayrıntılı erişim belirteçleri verin; buna Adım 5'teki harcama sınırlı ayrı model anahtarını da ekleyin.
• Kimlerin erişebileceğini sınırlayın. Caddy izin listesini veya bir VPN'i koruyun ve LOCAL_BACKEND_API_KEY gereğinden geniş paylaşıldıysa yenileyin (.env dosyasını düzenleyin, ardından docker compose up -d).
• Birleştirmeden önce inceleyin. Ajanın commit'lerini bir katkıcının pull request'i gibi değerlendirin.

Yedekleme ve geri yükleme

Her şey /opt/openhands içindedir: state (ayarlar, gizli değerler, konuşmalar, otomasyon veritabanı), projects, .env ve compose.yaml. Tutarlı bir kopya için konteyneri durdurun:

sudo mkdir -p /opt/backups
cd /opt/openhands
docker compose stop
sudo tar czf /opt/backups/openhands-$(date +%F).tar.gz -C /opt openhands
docker compose start

Geri yüklemek için arşivi Docker kurulu bir sunucuda /opt altına açın ve başlatın; tar sayısal sahiplikleri korur:

sudo tar xzf /opt/backups/openhands-2026-10-09.tar.gz -C /opt
cd /opt/openhands
docker compose up -d

Arşiv API anahtarlarınızı ve sağlayıcı kimlik bilgilerinizi içerir; sunucudan çıkmadan önce şifreleyin ve kopyalarını sunucunun dışında tutun. Ajanın projects içindeki çalışmasını Git barındırma hizmetinize de gönderin; kod için en iyi yedek bir uzak depodur.

OpenHands güncelleme

OpenHands sık sürüm yayınlar. Mevcut sürümünüzle hedef sürüm arasındaki sürüm notlarını okuyun, yedek alın, ardından etiketi değiştirip konteyneri yeniden oluşturun:

cd /opt/openhands
nano .env
docker compose pull
docker compose up -d
docker compose logs --tail 50 openhands

nano içinde OPENHANDS_VERSION değerini yeni sürüm numarasına ayarlayın. Konteyneri yeniden oluşturmak çalışan konuşmaları kestiği için güncellemeden önce onları bitirin veya durdurun.

Sorun giderme

Canvas sürekli API anahtarını soruyor veya API 401 döndürüyor

Girdiğiniz anahtar LOCAL_BACKEND_API_KEY ile eşleşmiyor. Anahtarı grep LOCAL_BACKEND_API_KEY /opt/openhands/.env ile yazdırın; değiştirdiyseniz konteynerin yeni değeri alması için docker compose up -d çalıştırın.

/home/openhands/.openhands altında Permission denied

state veya projects klasörü yanlış kullanıcıya ait. Adım 2'deki sahiplik komutlarını tekrarlayın ve docker compose up -d ile yeniden başlatın.

Ollama modeliyle ajan talimatları yok sayıyor veya erken duruyor

Bağlam çok kısa. OLLAMA_CONTEXT_LENGTH değerini systemctl show ollama --property=Environment ile doğrulayın, Ollama'yı yeniden başlatın ve yeni bir konuşma açın. Küçük modeller ajan işleri için yeterince yetenekli olmayabilir.

host.docker.internal:11434 için Connection refused

Ollama hâlâ 127.0.0.1 üzerinde dinliyor ya da ufw Docker alt ağını engelliyor. ss -tln | grep 11434 ve sudo ufw status çıktılarını kontrol edin, ardından Adım 6'daki test komutunu tekrarlayın.

Caddy 403 Forbidden döndürüyor

Genel IP adresiniz remote_ip satırında yok. Adresi güncelleyin ve sudo systemctl reload caddy çalıştırın.

Sonraki adımlar

• Kendi modellerinizi Ollama kurulumu ile çalıştırın.
• Canvas'a yalnızca özel bir ağ üzerinden WireGuard ile erişin.
• Otomasyonlar, birden çok arka uç ve Software Agent SDK için OpenHands belgelerini okuyun.
• Ajan iş yükleri için sunucuları AI agents hosting sayfasında karşılaştırın.