SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

HarnessRouter Self-Host Kurulumu ve API Yapılandırması

Codex, Claude Code ve Hermes agent modellerini tek bir API arkasında yönetin. Docker deploy adımları, loopback bind ayarları, varsayılan login değişikliği ve TLS erişimi.

HarnessRouter neyi ortadan kaldırır

HarnessRouter Community Edition'ı, sahibi olduğunuz bir sunucuda birden fazla agent harness'ın önüne tek bir API koymak için self-host edersiniz. Agent harness, bir modeli döngü içinde yöneten komut satırı programıdır: oturumu korur, dosyaları düzenler, komutları çalıştırır ve ilerleme durumunu işi isteyen tarafa aktarır. Codex, Claude Code ve Hermes bu işi yapar. Her biri kendi kurulumuyla, kendi kimlik bilgisi biçimiyle ve oturum kavramına ilişkin kendi yaklaşımıyla gelir. HarnessRouter bunların tamamını tek bir container içinde çalıştırır ve önlerine tek bir HTTP endpoint'i, tek bir oturum açma mekanizması ve tek bir secret store koyar.

Temel fikir budur. Ancak bunun maliyetini açıkça belirtmek gerekir. Birden fazla bileşeni tek bir yapı haline getirmek için sunucunuza bir container, bir oturum açma mekanizması, bir volume ve bir yükseltme süreci eklersiniz. Bugün yalnızca bir harness çalıştırıyorsanız bu yapı, harness'ı doğrudan kurmaktan daha kötü bir seçenektir. Bu tercih, buradaki son bölümde ele alınmaktadır. Dağıtıma geçmeden önce bu bölümü okuyun.

Aşağıdaki bilgilerin tamamı, 19 August 2026 tarihinde çekilen 0.5.5 image tag'iyle doğrulanmıştır. Proje çoğu gün yeni tag'ler yayımlar. Bu nedenle bir ay sonra bu sayfaya güvenmek yerine gerçekten çalıştırdığınız tag'i kontrol edin. Bu sayfa, 8 November 2026 tarihinde projenin güncel belgeleri ve kaynak kodu kullanılarak yeniden kontrol edilmiştir. Bu sırada latest, 0.38.5 değerini gösteriyordu. Güncel sürümlerin farklı davrandığı yerler belirtilmiştir. Komutlar, projenin github.com/HarnessRouter/harnessrouter repository'sinden alınmıştır. Bu komutlar 0.5.5 içinde README'de yer alıyordu. Kurulum ayrıntıları artık aynı repository içindeki docs/self-hosting-guide.md konumunda bulunmaktadır.

Unified Harness Protocol nedir

HarnessRouter, unifiedharnessprotocol.org adresinde yayımlanan Unified Harness Protocol (UHP) standardını uygular. UHP; bir ürünün harness üzerinde nasıl görev başlattığını, görev çalışırken nasıl takip edildiğini, oturum ve dosya yönetiminin nasıl yapıldığını ve hataların nasıl raporlandığını tanımlar. Spesifikasyon tarih bazlı sürümlenir. 19 Ağustos 2026 itibarıyla güncel olan sürüm 2026-08-11 tarihlidir. 8 Kasım 2026 itibarıyla site, güncel sürüm olarak 2026-10-19 tarihli olanı listelemekte ve bunu hâlâ "üzerine inşa edilebilecek kadar kararlı, güvenli bir şekilde değişebilmesi için sürümlenmiş" bir taslak standart olarak tanımlamaktadır.

Buradaki "açık standart" ifadesini dikkatli okuyun. Spesifikasyonu, referans uygulamasını ve kimin uyumlu olduğuna karar veren uygunluk paketini aynı şirket yazmaktadır. Projenin yönetişim kuralları, üçü birlikte değişmedikçe hiçbir değişikliğin kabul edilmeyeceğini belirtir. 9 Kasım 2026 itibarıyla protokol ana sayfası bu paketi 110 çalıştırılabilir kontrol olarak tanımlarken, uygunluk sayfası 101 kontrol olduğunu belirtmektedir. Kendi kendine barındırma kılavuzunun 4 Eylül 2026 tarihli kayıtlı referans çalışması ise 64 testi geçmiştir; yani yayımlanan sayılar birbiriyle uyuşmamaktadır. Projenin değişiklik günlüğü, altı ek dallanma kontrolünü 4 Kasım 2026 tarihine dayandırmaktadır. Bu kadar yeni bir protokol için bu durum normaldir ve Apache-2.0 lisansı, protokolün herhangi bir parçasını çatallayabileceğiniz (fork) anlamına gelir. Bu aynı zamanda UHP'nin henüz çok satıcılı bir standart olmadığı anlamına da gelir. Bunu gelişmekte olan bir protokol olarak değerlendirin: kullanışlı, hareketli ve kendi kodunuzun yeniden yazmaya gerek kalmadan kullanmayı bırakabileceği bir yapı olarak görün.

Başlamadan önce gerekenler

Docker ve yaklaşık 4 GB boş disk alanı gerekir. Ayrıca ücretli olarak kullandığınız bir model sağlayıcısından alınmış API anahtarı gerekir. Image indirme işlemi yaklaşık 700 MB veri kullanır. Disk alanının geri kalanı agent CLI'ları ve bunların yazdığı çalışma alanları için kullanılır. Image içinde bundled model veya deneme anahtarı bulunmaz. Bu nedenle bir sağlayıcı bağlanana kadar görevler başarısız olur. HarnessRouter'ın lisansı Apache-2.0'dır. Agent CLI'ları kendi lisanslarına ve kullanım koşullarına tabi olmaya devam eder. Repository lisansı bu lisansların ve koşulların yerine geçmez. Agent CLI'ları image içinde sunulmaz; ilk başlatma sırasında indirilir.

Tek bir docker run komutuyla HarnessRouter'ı self-host etme

docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

Ardından container'ın başlatılmasını izleyin. İlk başlatma yavaştır; loglar bunun nedenini gösterir.

docker logs -f harnessrouter

Çalışırken aşağıdaki satırlara benzer çıktılar görülür:

installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…

ready on :3000 için bekleyin. Mevcut kılavuz, sürenin bu satırdan değil, docker run komutunun komut istemini döndürmesinden itibaren yaklaşık yarım dakika olduğunu belirtir. Hazır satırından hemen sonra http://localhost:3000 yanıt vermiyorsa birkaç saniye bekleyip yeniden deneyin. Kurulan CLI'lar volume üzerinde önbelleğe alınır. Bu nedenle sonraki başlatmalar genellikle çok daha hızlıdır. Ancak sonradan eklenen veya daha önce kurulumu başarısız olan bir backend, kurulum işlemini yeniden tetikleyebilir.

Bu indirme iki sonucu ortaya çıkar ve ikisi de bir VPS için önemlidir. İlk olarak, ilk başlatma için dış ağa giden erişim gerekir. Image kendi başına yeterli değildir. Bu nedenle egress filtresinin arkasındaki veya dışarıya giden rotası olmayan bir sistem agent CLI'larını indiremez. Hem 0.5.5 hem de güncel sürümler, başarısız kurulumları kritik olmayan hata olarak değerlendirir ve bunları logda belirtir. Bu nedenle backends available: satırında hangi backend'lerin yer almadığını kontrol edin. İkinci olarak, üçüncü taraf yazılımları üçüncü taraf lisans koşulları kapsamında kurarsınız. Claude Code, Anthropic'in koşulları kapsamında; Hermes ise upstream projesinin belirlediği koşullar kapsamında sunulur. Bu nedenle ticari kullanım öncesinde her iki koşulu da inceleyin.

-v harnessrouter:/data adlı bir Docker volume oluşturur. Kalıcı verilerin tamamı /data içinde tutulur: SQLite veritabanları, depolanan dosyalar, secret store ve agent workspace'leri. Bu volume'ü silerseniz provider key'leri ve tüm transcript'ler dahil olmak üzere instance'ı silmiş olursunuz. Yedekleme işlemini container durdurulmuşken yapın. Yazılan bir SQLite veritabanını kopyalamak, açılamayabilecek bir dosya oluşturabilir. Aynı durdurma, ardından kopyalama ilkesi sistemdeki tüm durum bilgisi tutan container'lar için geçerlidir. Ayrıntılar servise göre değişir; örneğin PhotoPrism ve Immich kendi yedekleme komutlarını gerektirir.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
  tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouter

Compose varyantı ve değiştirmeniz gereken satır

Depo bir compose dosyası ile gelir. Artık "127.0.0.1:3000:3000" yayımlanmakta ve ana makine portunu loopback adresine bağlamaktadır. 0.5.5 dosyası "3000:3000" yayımlamıştır; halka açık bir sunucuda eski dosyayı kullanıyorsanız bu satırı değiştirin.

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:0.5.5
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

volumes:
  harnessrouter-data:

Mevcut upstream sürümünden farklı olan bir nokta, latest yerine sabitlenmiş (pinned) bir sürüm etiketinin kullanılmasıdır. Sürümleri sabitlemek önemlidir çünkü sürümler hızla değişir: Docker Hub, 8 Kasım 2026 tarihinde kontrol edildiğinde son bir gün içinde hem 0.38.4 hem de 0.38.5 etiketlerinin gönderildiğini göstermiştir. Sürekli değişen bir aracı çalışma zamanında (agent runtime) hata ayıklamak zordur. 0.5.5 değerini bu sayfadan kopyalamak yerine güncel sürümü sabitleyin; 9 Kasım 2026 itibarıyla bu değer 0.40.0 idi. Ardından ortam dosyasını kopyalayın, izinlerini kilitleyin ve başlatın.

cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f

.env, sağlayıcı anahtarınızı düz metin olarak tutar, bu nedenle 600 modu minimum gerekliliktir. docker compose alt komutu tanıdık gelmiyorsa, Docker Compose komut kopya kağıdı günlük kullanılan komutları kapsar.

Portun neden 0.0.0.0 yerine 127.0.0.1 üzerinde yayımlandığı

-p 3000:3000, varsayılan olarak portu ana makinenin sahip olduğu tüm arabirimlerde yayımlar. -p 127.0.0.1:3000:3000, ana makine portunu loopback arabiriminde yayımlar. 28.0.0 sürümünden eski Docker sürümleri, aynı L2 segmentindeki ana makinelerin localhost üzerinde yayımlanan portlara erişmesine izin verir. Açıkça etkinleştirilen doğrudan yönlendirme de loopback ana makine eşlemesi yapılmış olsa bile container portunu dışarı açabilir. Container, varsayılan olarak içeride 3000 portunu dinler. Bu değer PORT üzerinden yapılandırılabilir. Ana makine portu çakışmasını önlemek için soldaki port numarasını değiştirin. Sonucu kontrol edin:

docker port harnessrouter
sudo ss -ltnp | grep 3000

ss çıktısında 127.0.0.1:3000 görülmesi doğrudur. 0.0.0.0:3000, konsolun tüm IPv4 arabirimlerinde dinlediği anlamına gelir. Genel internet erişimi yine de yönlendirme ve filtreleme kurallarına bağlıdır. Bu durum, çoğu self-hosted uygulamaya kıyasla burada daha ciddi bir risktir. Çünkü konsol harness oluşturur, tüm transcript kayıtlarını okur, agent çalıştırır ve bu agent'lara çalışma alanlarında bir shell ile gerçek bir dosya sistemi sağlar. Ayrıca bağladığınız provider anahtarını da tutar. Korumasız bir konsola erişebilen herkes çalışmalarınızı okuyabilir, komut çalıştırabilir ve anahtarınızı kullanarak harcama yapabilir.

Bir ufw deny kuralı bu sorunu çözmez. Docker, yayımlanan container trafiğini ufw tarafından yönetilen zincirlerden önce kendi kuralları üzerinden yönlendirir. Bu nedenle sudo ufw status bir portu denied olarak göstermesi, yayımlanan portun engellendiğini kanıtlamaz. Testi VPS üzerinden değil, başka bir makineden gerçekleştirin. Aksi halde gerçekte hiçbir şeyi test etmiş olmazsınız. Bu, dsh'yi 3080 portunda headless çalıştırma ile aynı derstir: servisi loopback'e bağlayın, ardından ona nasıl erişeceğinize bilinçli biçimde karar verin.

İlk işlem olarak varsayılan oturum açma bilgilerini değiştirin

http://localhost:3000 adresinde harnessrouter kullanıcı adı ve instance tarafından oluşturulan başlangıç parolasıyla oturum açın. Parolayı şu komutla okuyun:

docker exec harnessrouter cat /data/selfhost-initial-password

Paylaşılan harnessrouter parolası 0.5.5 sürümünde çalışıyordu; güncel kurulumlar artık yayımlanmış bu varsayılanı kabul etmez.

Parolayı Profile sayfasından değiştirin veya betik tabanlı bir dağıtım için başlangıç sırasında ayarlayın. HR_AUTH_USER ve HR_AUTH_PASSWORD başlangıç kimlik bilgilerini sağlar; Profile sayfasından kaydedilen kimlik bilgileri önceliklidir.

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER='you' \
  -e HR_AUTH_PASSWORD='the-password-you-chose' \
  harnessrouter/harnessrouter

Yerel Console oturumu için parola sıfırlama e-postası gönderilmez. Parolayı kaybederseniz volume içindeki auth dosyasını silip servisi yeniden başlatın. Ardından yapılandırdığınız HR_AUTH_USER ve HR_AUTH_PASSWORD ile veya kendi parolanızı belirtmediyseniz oluşturulan başlangıç parolasıyla oturum açın.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouter

HR_AUTH_DISABLED=1 oturum açma denetimini tamamen kaldırır. Self-hosting kılavuzunda bunun "başka hiç kimsenin erişemeyeceği bir makinede yalnızca makul" olduğu belirtilir. Public IP address kullanan bir VPS bu tanıma uymaz. Bu nedenle kurulumu laptop üzerinde çalıştırmıyorsanız oturum açma denetimini etkin bırakın.

Sürümünüzü kontrol edin; eski sürümlerde erişim kontrolü yoktur

Bu bölüm ciddiye alınmalıdır. 0.1.x ve 0.2.0 sürümlerinde hiçbir kimlik doğrulama erişim kontrolü yoktu: 3000 numaralı porta erişebilen herkes konsola zaten girebiliyordu. 0.3.0, oturum açma özelliği bulunan ilk sürümdü. Bu sayfada, söz konusu eski etiketlerin yayımlanmış ve pull edilebilir olduğu en son 12 October 2026 tarihinde kaydedildi; mevcut erişilebilirlikleri 8 November 2026 tarihinde doğrulanmadı.

19 August 2026 itibarıyla yayımlanan en yeni etiket, 18 August 2026 tarihli 0.5.5 idi. 8 November 2026 tarihinde latest, 0.38.5 değerini gösteriyordu. Elinizdeki sürümü kontrol edin ve ardından Docker Hub üzerindeki etiket listesiyle karşılaştırın:

docker image ls harnessrouter/harnessrouter

0.3.0 sürümünden eski olan her şey hemen değiştirilmelidir; değişiklik daha sonraya planlanmamalıdır. Paylaşılan varsayılan parolayı kullanan eski sürümlerde parolanın yine değiştirilmesi gerekir. Güncel kurulumlar ilk parolayı oluşturur ve kendi parolanızı seçmenizi ister. Bu sayfadaki sürüm numaralarını güncel kabul etmeyin. Bunlar belirtilen tarihler için geçerliydi ve bu proje sürümleri hızlı yayımlar.

Bir sağlayıcı bağlayın

Bir model sağlayıcısı bağlanana kadar hiçbir şey çalışmaz. Hesap menüsündeki Bring your own key kısmından bir tane ekleyin veya ortam değişkenlerinde docker run değerine iletin. Değer JSON formatındadır, bu nedenle kabukta tırnak içine alın:

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'

.env.example, sağlayıcı ailesi başına bir bağlantı değişkenini adlandırır: claude-code arka ucu için HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC, codex arka ucu için HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI, gemini arka ucu için HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE ve bir toplayıcının veya kendi çıkarım sunucunuzun gittiği yer olan tüm OpenAI uyumlu uç noktalar için HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM. Eşleşen HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE, HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX ve HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES değişkenleri, her arka ucun varsayılan olarak hangi bağlantıyı kullandığını belirtir ve arka uç başına bir politika değişkeni bulunur. HR_SECRET_KEY ayrı bir konudur. Mevcut sürümler, saklanan kimlik bilgilerini bu değişken altında şifreler ve siz bir anahtar sağlamadığınızda /data/secret-key içinde bir anahtar oluşturur. Yeniden başlatmalar ve yükseltmeler boyunca aynı anahtarı koruyun; mevcut bir örnekteki verilerden ayrı tutmak için HR_SECRET_KEY değerini o dosyadaki değerle ayarlayın ve dosyayı silin.

HR_BACKENDS, HR_BACKENDS=claude,codex,hermes örneğinde olduğu gibi hangi arka uçların kurulacağını ve yükleneceğini seçer. Ayarlanmazsa, mevcut sürümler claude, codex ve hermes'ten opencode, gemini, goose ve diğerlerine kadar 30 arka uçtan oluşan çok daha uzun bir varsayılan liste kurar; bu nedenle listeyi kırpmak disk alanından ve ilk başlatma süresinden tasarruf sağlar. Mevcut kendi kendine barındırma kılavuzu, "kullanmayacaksanız HR_BACKENDS listesinden herhangi birini çıkarın" der ve kendi yalın örneği, Hermes'i tamamen dışarıda bırakan HR_BACKENDS=opencode değeridir. Kurulumu başarısız olan bir arka uç kritik bir hata değildir: diğerleri çalışmaya devam eder ve kurulmayan bir arka uç üzerindeki görev "kurulu değil" şeklinde reddedilirken, konteyner günlüğü başarısız olan kurulumu adlandırır. 0.5.5 README dosyası, hermes değerini çıkarmanın konteynerin hemen 1 durum koduyla ve hata mesajı vermeden kapanmasına neden olduğu bilinen bir sorunu içeriyordu, ancak bu etiketin giriş noktası (entrypoint) hatayı zaten düzeltmiştir; yorumları önceki uygulamayı tanımlar. İstediğiniz tek harness Hermes ise, Hermes aracısını kendi VPS'inde çalıştırmak daha küçük bir dağıtımdır.

Konsol olmadan API çağrısı yapma

Konsol isteğe bağlıdır. Aynı API her ikisine de hizmet verir ve Responses tarzı bir sözleşme kullanır. Önce oturum çerezini almak için oturum açın:

curl -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"your-password"}'

Ardından metadata.harness_id içinde harness adını ve bağlı sağlayıcınızın gerçekten sunduğu bir modeli belirterek bir görev gönderin:

curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
  -H 'content-type: application/json' \
  -d '{"input":"Reply with exactly this and nothing else: it works.",
       "metadata":{"harness_id":"codex"},
       "model":"gpt-5.4-mini",
       "stream":false}'

Çıktı bloğu ve token sayısı içeren bir JSON nesnesi, harness'ın çalıştığını gösterir. harness_id değerinin codex yerine claude-code olarak değiştirilmesi, aynı isteği farklı bir harness'a gönderir. Bu değiştirilebilirlik, bu yazılımın var olmasının temel nedenidir. Kimliğin claude-code olduğuna dikkat edin; backend adı HR_BACKENDS, ilke değişkeni ise claude olsa da durum böyledir. Yukarıdaki özel bağlantı, zaten barındırdığınız OpenAI uyumlu bir endpoint'i harness'a tanımlamanızı sağlar. VPS üzerinde self-host edilen bir DeepSeek harness'ı da bu şekilde bağlanır.

Oturum çerezi akışı yerel hata ayıklama için desteklenmeye devam eder. Ürün backend'i için güncel belgelerde API Keys bölümünde bir HarnessRouter API anahtarı oluşturulması ve bu anahtarın Console oturumu sürdürmek yerine Bearer token olarak gönderilmesi önerilir.

Dizüstü bilgisayarınızdan port yayımlamadan erişin

Bunun iki yolu vardır ve hiçbiri 0.0.0.0 üzerinde doğrudan port açmaz.

SSH tüneli, en düşük maliyetli seçenektir ve sunucuya herhangi bir yazılım kurulmasını gerektirmez. Makinenizdeki yerel bir portu VPS üzerindeki loopback arayüzüne yönlendirir.

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

Bu işlemi çalışır durumda bırakın ve tarayıcınızda http://localhost:3000 adresini açın. SSH bind: Address already in use mesajını yazdırırsa dizüstü bilgisayarınızda başka bir işlem 3000 portunu kullanıyordur. Bu durumda -L 3100:127.0.0.1:3000 ile farklı bir yerel port seçin ve 3100 portuna gidin.

Sonlandırma yapan bir reverse proxy, başka kişilerin erişmesi gerektiğinde uygun çözümdür. Proxy, TLS (transport layer security) sertifikasını tutar ve istekleri loopback arayüzüne yönlendirir. Self-hosting kılavuzunda bir Caddy yapılandırması verilir:

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1      # agent turns stream for minutes; never buffer them
    }
}

flush_interval -1, Caddy'nin yanıt arabelleğe almasını açıkça devre dışı bırakır; Caddy, bununla birlikte text/event-stream yanıtlarını zaten hemen gönderir. Agent, akış belirteçlerini dakikalar boyunca üretir. Yanıtları arabelleğe alan bir proxy bu belirteçleri işlem tamamlanana kadar tutar. Bu nedenle konsol donmuş gibi görünür ve ardından her şeyi tek seferde yazdırır. Nginx'teki karşılığı, location bloğu içindeki proxy_buffering off; ifadesidir. Hangisini seçerseniz seçin, DNS adını proxy'yi gösterecek şekilde ve container'ı loopback üzerinde tutun. Reverse proxy olarak Nginx, Caddy ve Traefik karşılaştırması, sisteminiz için hangisinin uygun olduğunu açıklar.

root yerine kendi kullanıcısı olarak çalıştırın

Docker daemon root olarak çalışır. docker grubuna üyelik de root yetkisine eşdeğerdir. Bunun nedeni, grup üyesinin host dosya sistemini mount eden bir container başlatabilmesidir. Bu nedenle "ekibi docker grubuna eklemek", provider anahtarını barındıran sistemde root yetkisi dağıtmak anlamına gelir.

Basit yaklaşım şudur: compose dosyasının ve .env dosyasının sahibi olan bir servis hesabı oluşturun. Bu dosyaları paylaşılan bir home dizininde tutmayın.

sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter

Bunu, docker run komutuna --user ekleyerek veya compose dosyasına user: ekleyerek sağlamaya çalışmayın. Güncel kılavuza göre container root olarak başlatılmalıdır. 0.8.2 sürümünden itibaren container başka bir şekilde başlatılmayı reddeder ve logda bunu belirten tek satırlık bir mesaj yer alır.

Daha güçlü yaklaşım rootless Docker kullanmaktır. Bu modelde daemon'ın kendisi, ayrıcalıksız kullanıcı olarak çalışır. newuidmap ve newgidmap için uidmap paketine, ayrıca kullanıcı için /etc/subuid ve /etc/subgid içinde en az 65536 subordinate UID değerine ihtiyaç vardır. uidmap Ubuntu arşivinde bulunur, ancak docker-ce-rootless-extras bulunmaz. docker-ce-rootless-extras, Docker engine kurulumunun eklediği download.docker.com adresindeki Docker'ın kendi apt deposundan sağlanır. Engine bu depodan kurulmadıysa grep -rl download.docker.com /etc/apt/sources.list.d/ herhangi bir çıktı üretmez ve aşağıdaki kurulum paketi bulamaz.

sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now docker

loginctl enable-linger, kullanıcının systemd örneğini oturum kapatıldıktan sonra da çalışır durumda tutar ve boot sırasında başlatır. Sonucu docker info ile doğrulayın. Bu komut, rootless değerini Security Options altında listeler. Rootless mode, ek yapılandırma olmadan 1024 altındaki portlara bağlanamaz. Burada bu durum önem taşımaz, çünkü 3000 portu bu sınırın üzerindedir. Hesabın kendisinin oluşturulması VPS üzerinde en az ayrıcalıklı kullanıcılar oluşturma bölümünde ele alınır.

Nelerin bozulduğu ve ne görüleceği

Container başlatıldıktan bir saniye sonra kapanıyor ve loglar boş. docker ps -a, Exited (1) bilgisini gösterir. Daha önceki bir entrypoint, HR_BACKENDS değerini hermes içermeden bıraktığında başarısız oluyordu; ancak README dosyasında sorun hâlâ listelenmesine rağmen 0.5.5 bu düzeltmeyi zaten içerir. Bu hatayı yalnızca çıkış durumuna bakarak teşhis etmeyin. Güncel bir tag üzerinde docker logs dosyasının son satırını okuyun: 0.8.2 ile başlayan ve --user kullanılarak başlatılan bir container, root olarak başlatılması gerektiğini belirten tek satırlık bir mesajla kapanır.

İlk başlatma hiç tamamlanmıyor. Log, bir installing satırından sonra durur ve ready on :3000 hiçbir zaman görünmez. Agent CLI araçlarını almak için makinenin ağa erişip erişemediğini kontrol edin; bu araçlar image içinde bulunmaz. Hem 0.5.5 hem de güncel sürümler, tamamlanan kurulum hatalarını tolere eder. Başarısız kurulumları logda belirtir ve bunları backends available: satırına dahil etmez. Giden rotayı veya proxy ayarlarını düzeltin, ardından yeniden başlatın.

Konsol yükleniyor, ancak her görev başarısız oluyor. Herhangi bir provider bağlı değildir. Image içinde yerleşik bir model veya ücretsiz katman bulunmaz. Bu nedenle yeni bir instance oturum açmanızı sağlayabilir, ancak hiçbir işlemi çalıştıramaz.

Proxy arkasında yanıtın ortasında konsol donuyor. Çıktı, işlem tamamlandığında tek blok halinde görünür. Bunun nedeni yanıtın buffer edilmesidir. Caddy üzerinde flush_interval -1, Nginx üzerinde proxy_buffering off; ayarını yapın.

Tünel çalışır durumda olmasına rağmen laptop üzerinden erişemiyorsunuz. Sunucuda docker port harnessrouter komutunu çalıştırın. Komut hiçbir çıktı vermezse container hiçbir port yayınlamıyordur. Port eşlemesini ve network mode ayarını kontrol edin.

Çalıştırmaya değer mi?

Gerçekten birden fazla harness kullanılıyor ve üç ayrı endpoint ile üç ayrı kimlik bilgisi deposu yerine tek bir endpoint ve tek bir kimlik bilgisi deposu isteniyorsa çalıştırmaya değerdir. Üzerinde bir ürün geliştiriliyor ve harness'in yeniden yazım gerektiren bir bileşen yerine bir yapılandırma değeri olması isteniyorsa da çalıştırmaya değerdir. UHP bunu sağlar; ancak protokolün ne kadar yeni olduğu konusunda yukarıda belirtilen çekince geçerlidir.

Tek bir harness kullanılıyorsa çalıştırmaya değmez. Bu CLI'ın sunucuya kurulması daha az hareketli parça anlamına gelir ve kullanıcı ile CLI arasına herhangi bir oturum açma katmanı girmez. Ayrıca istenen şey tek bir API üzerinden birden fazla harness'e erişmek yerine tek bir görev üzerinde iş birliği yapan birden fazla agent ise bu yapı uygun değildir. Bu farklı bir araç gerektirir: bu model için Omnigent gibi çok agent'lı bir harness konusuna bakılmalıdır. Her iki durumda da dağıtım kuralları değişmez. Loopback adresine bind edilmesi, parolanın değiştirilmesi, güncel bir sürümün sabitlenmesi ve ayrı bir kullanıcı kullanılması gerekir.

FAQ

HarnessRouter ürününü 3000 numaralı portta yayımlamak güvenli midir?

Hayır. Konsol harness oluşturur, tüm transcript kayıtlarını okur, shell ve dosya sistemi erişimine sahip agent'ları çalıştırır ve bağladığınız provider anahtarını saklar. Bu nedenle korumasız bir konsol bunların tamamını açığa çıkarır. -p 127.0.0.1:3000:3000 ile loopback üzerinde yayımlayın ve konsola bir SSH tüneli veya TLS sonlandıran reverse proxy üzerinden erişin. ufw deny kuralı tek başına yeterli değildir: Docker, yayımlanan container trafiğini ufw tarafından yönetilen zincirlere ulaşmadan önce yönlendirir. sudo ss -ltnp | grep 3000 ile doğrulama yapın; komutun 127.0.0.1:3000 çıktısını vermesi gerekir. Ardından başka bir makineden erişimi test edin. Eski aynı-L2 localhost açığını önlemek için Docker 28.0.0 veya sonraki bir sürümünü kullanın ve doğrudan yönlendirmenin etkinleştirilmediğini kontrol edin.

Giriş engeli hangi HarnessRouter sürümünde eklendi?

0.3.0. 0.1.x ve 0.2.0 sürümleri hiçbir kimlik doğrulama mekanizması olmadan yayımlandı. Bu sürümleri çalıştıran herkes, portu kimsenin bulmamasına güveniyor demektir. Bu sayfada bu etiketlerin yayımlanmış ve pull edilebilir olduğu en son 12 October 2026 tarihinde kaydedildi; mevcut erişilebilirlikleri 8 November 2026 tarihinde doğrulanmadı. 19 August 2026 itibarıyla en yeni etiket 0.5.5 idi ve tarihi 18 August 2026 idi; 8 November 2026 tarihinde latest, 0.38.5 değerini gösteriyordu. Kurulu sürümü görmek için docker image ls harnessrouter/harnessrouter komutunu çalıştırın. Bunu bu sayfayla değil, Docker Hub üzerindeki etiket listesiyle karşılaştırın ve kendi parolanızı belirleyin. Güncel kurulumlar eski ortak varsayılan parolayı kabul etmek yerine başlangıç parolası oluşturur.

HR_BACKENDS değerini ayarladıktan hemen sonra container neden kapanıyor?

Güncel bir sürümde kapanmaması gerekir. Self-hosting kılavuzu, kullanılmayacak backend'lerin yapılandırmadan çıkarılmasını belirtir. Kurulumu başarısız olan bir backend de kritik hata oluşturmaz. Önceki bir uygulamada hermes belirtilmediğinde süreç, hata mesajı vermeden 1 durum koduyla sonlanıyordu. Ancak 0.5.5 kaynak kodu bu hatayı zaten düzeltmiştir; README dosyasında hâlâ bu durum listelenmektedir. Güncel bir etikette docker logs dosyasını okuyun: 0.8.2 itibarıyla --user ile başlatılan bir container, root olarak başlatılması gerektiğini belirten tek satırlık bir mesajla kapanır.

HarnessRouter ilk başlatmada internet erişimine ihtiyaç duyar mı?

Evet. Agent CLI'ları image içinde gönderilmek yerine ilk başlatmada indirilir. Her CLI kendi lisansına ve kullanım koşullarına tabidir. Hem 0.5.5 hem de güncel sürümler, başarısız kurulumları log'a yazar ve diğer backend'lerin başlatılmasına izin verir. Kurulan CLI'lar volume üzerinde önbelleğe alınır. Bu nedenle sonraki başlatmalar genellikle daha hızlıdır. Ancak backend araçları ve çalıştırdığınız görevler yine de ağ erişimine ihtiyaç duyabilir. Yeni eklenen veya daha önce kurulumu başarısız olan bir backend yeniden kurulum başlatabilir.

Konsol parolasını kaybettim. Yeniden nasıl erişim sağlayabilirim?

Yerel Console girişi için parola sıfırlama e-postası yoktur. Container'ı durdurun, volume içindeki /data/selfhost-auth.json dosyasını silin ve container'ı yeniden başlatın. Ardından yapılandırdığınız HR_AUTH_USER ve HR_AUTH_PASSWORD ile giriş yapın. Kendi parolanızı belirtmediyseniz oluşturulan başlangıç parolasını kullanın. Daha sonra Profile sayfasından yeni bir parola belirleyin. Container ve volume adlarının her ikisi de harnessrouter ise sırasıyla docker stop harnessrouter, docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json ve docker start harnessrouter komutlarını çalıştırın. Oluşturulan parolayı docker exec harnessrouter cat /data/selfhost-initial-password ile okuyun.

Bu yazı işinize yaradı mı?