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

> OpenHands Agent Canvas'ı Ubuntu veya Debian'da Docker ile çalıştırın: API anahtarıyla giriş, Caddy ile HTTPS, bulut ya da Ollama modelleri, sandbox ve yedek.

Zorluk: İleri\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

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ı):

| Çerçeve | Nedir | Dil |
|---|---|---|
| LangGraph | Durum tutan ajanlar için düşük seviyeli orkestrasyon | Python (ayrı bir JavaScript sürümü var) |
| CrewAI | Rol tabanlı ajan ekipleri için çerçeve | Python |
| Microsoft Agent Framework | Ajanlar ve çok ajanlı iş akışları; bakım moduna geçen AutoGen için önerilen geçiş yolu | Python ve .NET |
| PydanticAI | Pydantic ekibinden tip güvenli ajan çerçevesi | Python |
| Mastra | Yapay zeka uygulamaları ve ajanlar için çerçeve | TypeScript |

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.

> **Tehlike**
>
> OpenHands ajanları gerçek komutlar çalıştırır. Belgeler ajan sunucusunun konteyner içinde rastgele kabuk komutları çalıştırabildiğini belirtir ve makineyi kimlik bilgileri barındıran güvenilir bir altyapı olarak görmenizi ister. Üretim servislerinizi de çalıştıran bir sunucu yerine OpenHands'e ayrılmış bir sunucu kullanın.

## Ön koşullar

- Docker Engine ve Compose eklentisi kurulu, **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13** çalıştıran bir sunucu; bkz. [Ubuntu'ya Docker kurulumu](/guides/install-docker-ubuntu) veya [Debian'a Docker kurulumu](/guides/install-docker-debian). OpenHands VM rehberi varsayılan olarak Ubuntu 24.04 LTS kullanır.
- `sudo` yetkisi ve SSH anahtarıyla girişi olan, root olmayan bir kullanıcı; bkz. [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys).
- Sunucuyu gösteren bir A (isteğe bağlı olarak AAAA) kaydına sahip `agents.example.com` gibi bir alan adı ve [Caddy reverse proxy](/guides/caddy-reverse-proxy) rehberindeki Caddy kurulumu.
- Yetenekli bir model için API anahtarı (OpenHands Anthropic, OpenAI, Mistral AI ve kendi sağlayıcısını doğrulanmış olarak listeler) veya uygun bir GPU'su olan sunucuda [Ollama kurulumu](/guides/install-ollama) ile kurulmuş Ollama.

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Tek kullanıcı için 2 vCPU | Ajanlar kod derleyip test ediyorsa 4 vCPU |
| RAM | Tek kullanıcı için 4 GB | Derleme, test ve birden çok konuşma için 8 GB |
| Disk | Yayınlanmamış | İmajlar, depolar ve bağımlılıklar için 40 GB |

Resmi değerler OpenHands VM rehberinden gelir. Önerilen sütun ihtiyatlı bir başlangıç noktasıdır, ölçüm sonucu değildir; yerel modellerin kendi GPU belleği ihtiyacı buna eklenir.

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

```bash
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](https://github.com/OpenHands/OpenHands/releases) 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:

```yaml
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:

```bash
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

```bash
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:

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

```bash
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](/guides/nginx-reverse-proxy-certbot) rehberinden alın.

> **Uyarı**
>
> OpenHands belgeleri bilinen bir sorunu listeler: paketle gelen kod düzenleyici Canvas ile aynı tarayıcı kökenini (origin) paylaşır; bu nedenle o kökende çalışan bir betik Canvas'ın yerel depolamada tuttuğu oturum API anahtarlarını okuyabilir. IP izin listesini koruyun veya Caddy'yi hiç kullanmadan bir SSH tüneli (`ssh -L 8000:127.0.0.1:8000 youruser@203.0.113.10`, ardından `http://localhost:8000/canvas`) ya da [WireGuard](/guides/wireguard-vpn-server) gibi bir VPN kullanı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:

```bash
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](/gpu-servers) 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:

```bash
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:

```bash
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ı](https://github.com/OpenHands/OpenHands/releases) okuyun, yedek alın, ardından etiketi değiştirip konteyneri yeniden oluşturun:

```bash
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](/guides/install-ollama) ile çalıştırın.
- Canvas'a yalnızca özel bir ağ üzerinden [WireGuard](/guides/wireguard-vpn-server) ile erişin.
- Otomasyonlar, birden çok arka uç ve Software Agent SDK için [OpenHands belgelerini](https://docs.openhands.dev/) okuyun.
- Ajan iş yükleri için sunucuları [AI agents hosting](/ai-agents-hosting) sayfasında karşılaştırın.

## Sık sorulan sorular

### OpenHands ile LangGraph veya CrewAI gibi çerçeveler arasındaki fark nedir?

LangGraph, CrewAI ve benzeri projeler kendi kodunuza eklediğiniz kütüphanelerdir. OpenHands da bir Python SDK sunar, ancak Agent Canvas bir ajan sunucusuyla birlikte gelen hazır, kendi sunucunuzda barındırılan bir web uygulamasıdır; böylece önce bir uygulama yazmadan depolarınız üzerinde ajan çalıştırabilirsiniz.

### Ajanın sunucumda komut çalıştırmasına izin vermek güvenli mi?

Ajan konteyner içinde rastgele kabuk komutları çalıştırır ve kayıtlı ayarlar dahil konteynere bağlanan her şeyi okuyabilir. Onu yalnızca bu iş için ayrılmış bir sunucuda çalıştırın, yalnızca gereken projeleri bağlayın, dar kapsamlı belirteçler kullanın ve konteynere asla privileged mod veya Docker soketi vermeyin.

### OpenHands Ollama üzerinden yerel bir model kullanabilir mi?

Evet, Ollama'nın OpenAI uyumlu uç noktası üzerinden: model olarak openai/ ve ardından Ollama model adı, temel adres olarak http://host.docker.internal:11434/v1 ve herhangi bir yer tutucu API anahtarı. Belgeler en az 22000 belirteçlik bağlam uzunluğu ister; yetenekli yerel modeller bol bellekli bir GPU gerektirir.

### Eski rehberler Docker soketiyle docker.openhands.dev/openhands/openhands kullanıyor. Hangisi doğru?

O imaj, OpenHands belgelerinin artık kullanımdan kaldırılmış (deprecated) olarak tanımladığı eski Local GUI'dir. ghcr.io/openhands/agent-canvas olarak yayınlanan Agent Canvas güncel self-hosted uygulamadır ve Docker soketine ihtiyaç duymaz.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/install-openhands>\
Son güncelleme: 2026-10-09