OneCLI self-host kurulumu ve VPS yapılandırması

OneCLI self-host kurulumu ile elde edecekleriniz

OneCLI uygulamasını kendi sunucunuzda barındırdığınızda, ekibinizdeki her kişi kendi sandbox ortamında çalışan özel bir asistana sahip olur. API anahtarları, asistanların asla okuyamadığı bir ağ geçidinde (gateway) tutulur. Kurulum, arka planda PostgreSQL kullanan ve http://localhost:10254 adresinden erişilebilen bir Docker Compose yığınıdır. Gerçek bir sunucu planlaması yapın. Belgelenen varsayılan değer, asistan sandbox'ı başına 2 GiB bellek gerektirir; dolayısıyla bu, 1 GB RAM'e sahip bir VPS üzerinde çalışacak bir iş yükü değildir.

Bu yığın içerisinde yedi bileşen bulunur; bunların ne işe yaradığını bilmek, kılavuzun geri kalanını anlamanızı kolaylaştıracaktır.

• Web paneli (Next.js), 10254 portu. Asistan oluşturma, sohbet, bellek ve yetenek düzenleme, bağlantılar ve gizli anahtarlar.
• API sunucusu, 10256 portu. Kontrol düzlemi: veritabanı, sohbet yönetimi ve iş kuyrukları.
• Rust ağ geçidi, 10255 portu. Asistanlardan gelen giden istekleri yakalar ve kimlik bilgilerini enjekte eder.
• Runner. README dosyasında "asistan sandbox'larını başlatan, durduran ve sonlandıran bileşen" olarak tanımlanır. Yalnızca dışa dönüktür ve veritabanına asla erişmez.
• Sandbox Supervisor. README dosyasında "her sandbox içinde çalışan ve asistan çalışma zamanının değiştirilebilir olması için satıcıdan bağımsız bir arayüz kullanan bileşen" olarak tanımlanır.
• Kanal bağdaştırıcısı (Channel adapter). Bir Slack uygulamasını bağlayan daemon; böylece bir asistan, kanallarda ve doğrudan mesajlarda kendi adıyla yanıt verebilir.
• PostgreSQL. Sunulan compose dosyası, pgdata birimini (volume) kullanarak postgres:18-alpine sürümünü çalıştırır.

İsim CLI olsa da ürün bir sunucudur

OneCLI bir sunucu platformudur. İsim, dizüstü bilgisayarınıza kurduğunuz bir komut satırı aracına işaret etse de, bu rehberdeki ürün için bu tanım yanlıştır. onecli/onecli-cli deposunda ayrı bir komut satırı istemcisi mevcuttur ve bu istemci, yerel bir kodlama aracısının trafiğini bir ağ geçidi üzerinden yönlendirir. Burada dağıtımını yapacağınız şey çok kullanıcılı bir web uygulamasıdır: ilk hesabın örneğin sahibi olduğu bir hesap sistemi, konuşmalar ve gizli verilerden oluşan bir veritabanı ve container'ları başlatan bir çalıştırıcı.

Kişi başına düşen model, tasarımın temelini oluşturur. README dosyasında belirtildiği üzere: "Her kişi için bir aracı oluşturursunuz, her aracıya ihtiyaç duyduğu erişimi verirsiniz ve bu aracı, kimlik bilgilerini ekleyen ve politikanızı uygulayan bir ağ geçidi üzerinden yönlendirilerek korumalı bir alanda (sandbox) çalışır." Her aracının kendi dosya sistemi, kabuğu, konuşma sayfası, platformun sakladığı belleği ve bir kez yazdığınız yetenekleri vardır. Kimlik bilgileri, alışılagelmiş kurulumun aksine ters yönde çalışır. Bir API anahtarını her kişinin ortamına kopyalamak yerine, anahtarı bir kez depolarsınız ve onu kullanma izni olan aracılara tanımlarsınız.

Başlamadan önce gerekenler

• Docker ve 2.19 veya daha yeni sürüme sahip Compose eklentisi. Compose dosyası, API'nin beklediği tek seferlik bir geçiş servisi kullanır; bu bağımlılık biçimi 2.19 sürümünü gerektirir.
• Bellek, asıl kısıtlayıcı faktördür. Bir plan seçmeden önce aşağıdaki boyutlandırma bölümünü okuyun.
• Boş loopback portları: 10254, 10255, 10256 ve 5432.

PostgreSQL'i kendiniz kurmanız gerekmez: compose dosyası bunu bir servis olarak çalıştırır. Node.js veya Rust kurulumuna da ihtiyacınız yoktur. Bunlar yalnızca mise aracının araç zincirini sabitlediği, kaynaktan derleme yöntemi için gereklidir.

VPS üzerinde kaç adet agent sandbox çalıştırılabilir?

Runner'ın kendi dokümantasyonu, tahminler yerine gerçek rakamlar sunar. Her sandbox 2048 MB bellek (RUNNER_SANDBOX_MEMORY_MB), bir CPU (RUNNER_SANDBOX_CPUS) ve 512 işlem (RUNNER_SANDBOX_PIDS) kapasitesine sahiptir. Eşzamanlılık sınırı 4 (RUNNER_MAX_SANDBOXES) olarak belirlenmiştir ve dokümantasyon, bu sınırı karşılamak için temel yığının üzerinde yaklaşık 10 GiB boş bellek önermektedir.

[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Bu yuva sayıları bir kıyaslama (benchmark) değil, aritmetik bir hesaptır: toplam bellekten PostgreSQL ve dört adet uzun süreli çalışan servis için gereken yaklaşık 2 GB çıkarılır ve sonuç 2 GiB'lık sandbox sınırına bölünür. Bu temelde, 2 GB box planı 0 adet sandbox barındırabilir; dolayısıyla en ucuz plan, barındırılan bir agent'ı çalıştırmak için yeterli değildir. Bir 16 GB box planı, 7 adet sandbox için yer açar; bu da varsayılan dört adetlik sınırın ve runner dokümantasyonunun talep ettiği yaklaşık 10 GiB boş belleğin üzerindedir. 32 GB box planı ise sizi 15 kapasitesine ulaştırır.

İki durum bu aritmetiği değiştirir. Arka plan süreci çalışan bir sandbox asla park etmez, bu nedenle yuvasını kalıcı olarak işgal eder; bu da RUNNER_MAX_SANDBOXES değerini en yoğun an için değil, sürdürülebilir yük için belirlemeniz gerektiği anlamına gelir. Ayrıca bellek, CPU'dan önce tükenir. Her sandbox bir CPU ile sınırlandırılmıştır, bu nedenle dört meşgul agent dört çekirdek ister; ancak boşta duran ancak aktif olan dört agent hala 8 GiB bellek tutar.

Docker Compose ile OneCLI Kurulumu

Resmi self-hosting dokümantasyonu tam olarak bu sıralamayı önerir. Compose dosyasının yanındaki docker/.env dizinine üç adet gizli anahtar yazar ve ardından yığını başlatır.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
docker compose up -d --wait

Bu bloğu çalıştırmadan önce okuyun. Heredoc işaretçisi tırnak içinde değildir; bu nedenle kabuğunuz her bir head -c 32 /dev/urandom | base64 ifadesini çalıştırır ve metnin kendisi yerine sonucunu yazar. SECRET_ENCRYPTION_KEY, veritabanındaki her gizli veri için AES-256-GCM anahtarıdır. GATEWAY_INTERNAL_SECRET, ağ geçidinin API ile kimlik doğrulamasını sağlar. BETTER_AUTH_SECRET, oturum çerezlerini imzalar. COMPOSE_PROFILES=runner en kritik satırdır; çünkü runner servisi bir Compose profili arkasında çalışır. Bu satırı atlarsanız yığın sağlıklı bir şekilde ayağa kalkar ancak hiçbir agent sandbox başlatılmaz.

--wait, her servis sağlıklı olduğunu bildirene kadar kabuğu meşgul eder; bu nedenle sıfır olmayan bir çıkış kodu, bir şeylerin yanlış gittiğinin ilk işaretidir. Ardından nelerin gerçekten çalıştığını kontrol edin.

docker compose ps
docker compose logs migrations

Sürümü sabitleyin. ONECLI_VERSION, tüm servislerin etiketini aynı anda ayarlar; RUNNER_AGENT_IMAGE başka bir yeri işaret etmediği sürece agent sandbox imajı da bu etiketi takip eder. 19 Ağustos 2026 itibarıyla güncel sürüm, 18 Ağustos 2026 tarihinde yayınlanan v2.0.1 sürümüdür. Bunu aynı dosyaya ekleyin ve yığını tekrar ayağa kaldırın.

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

Ayrıca yapılandırmasını ~/.onecli/.env dosyasına yazan ve aynı işlemleri gerçekleştiren curl -fsSL https://onecli.sh/install | sh adında bir yükleyici de mevcuttur. Compose yolu, herhangi bir işlem başlamadan önce tüm dosyaları inceleyebileceğiniz yöntemdir ve halihazırda başka Compose yığınları barındıran sunucularda bu yöntem kullanılmalıdır. Kaynaktan derleme ise üçüncü bir yoldur; klonlanmış depoda önce pnpm install, ardından pnpm run setup olarak belgelenmiştir. Bu yol her halükarda mise, ağ geçidi için Rust ve Docker gerektirir; kod üzerinde değişiklik yapmayı planlayan kullanıcılar için tasarlanmıştır.

Dashboard'a dizüstü bilgisayarınızdan erişim

Dağıtılan compose dosyasındaki her yayınlanmış port ${ONECLI_BIND_HOST:-127.0.0.1} adresine bağlanır. Bir VPS üzerinde bu, dashboard'un çalıştığı ancak dışarıdan kimsenin ona erişemeyeceği anlamına gelir. Bu varsayılan ayar doğrudur. Bunu koruyun ve tünelleme yapın:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Şimdi dizüstü bilgisayarınızda http://localhost:10254 adresini açın. Trafik SSH bağlantısı üzerinden iletilir; bu sayede genel internet üzerinde şifrelenmemiş bir dashboard olmaz ve güvenlik duvarına ek bir port açmanız gerekmez.

ONECLI_BIND_HOST=0.0.0.0 ayarı, dashboard'u düz HTTP üzerinden yayınlar ve yanında PostgreSQL'i de dışarıya açar. Eğer birden fazla kişinin dashboard'a erişmesi gerekiyorsa, 10254 numaralı portun önüne TLS (transport layer security) destekli bir reverse proxy yerleştirin ve bind host ayarını değiştirmeyin. Bunu, instance'ın bir sahibi olmadan önce yapın. Upstream dokümantasyonu bunun nedenini açıkça belirtir: "Siz yapana kadar instance'ın bir sahibi yoktur ve erişilebilir bir sunucuda oraya ilk ulaşan kişi sahibi olur." Eğer bu proxy halihazırda diğer self-hosted uygulamalarınızın önünde duruyorsa, kendi kendine barındırılan bir tek oturum açma katmanı üzerinden kimlik doğrulamasını yönlendirmek, dashboard'u ekibinizin zaten kullandığı giriş sisteminin arkasına alır; böylece birinin erişimini tek bir yerden kaldırmak bu kapıyı da kapatır.

İlk hesabı oluşturun ve ardından bir model anahtarı atayın

Paneli açın ve hesabı hemen oluşturun. Bu hesap örneğin sahibidir ve hesap oluşturulduktan sonra sisteme katılım davetiye gerektirir.

Bir aracı (agent) oluşturmadan önce bir model anahtarı kaydedin. Barındırılan bir aracının atanmış bir model anahtarına ihtiyacı vardır ve işlem sırası önemlidir: anahtarı panelde kaydedin, aracıya atayın ve ancak o zaman bir görüşme başlatın. Atama adımını atlarsanız sandbox asla başlatılmaz; bu durum, hiçbir işlem yapmadan bekleyen bir aracı olarak görünür.

Atamaları sınırlı tutun. Her aracıya yalnızca kendisine atadığınız yetkiler verilir ve ağ geçidi (gateway) bunu her istekte zorunlu kılar; bu sayede tek bir depoyu okuyan bir aracının, ödeme sağlayıcınızın anahtarına erişim yolu bulunmaz. Aynı atama listesi, harcamalarınızı kontrol etmenizi sağlayan mekanizmadır. Sahip olduğunuz her modeli kullanabilen kişisel bir aracı, kişi başına fatura anlamına gelir; bu nedenle on tanesini dağıtmadan önce bir aracının model çağrıları için harcayabileceği tutarı sınırlama konusunu okumanız faydalı olacaktır.

Ağ geçidinin anahtarları aracıların dışında tutma yöntemi

Ağ geçidi, 10255 numaralı portu dinleyen, Rust ile yazılmış bir HTTPS proxy'sidir. Bir aracının HTTP istemcisi bu ağ geçidine yönlendirilir ve aracı, gerçek bir kimlik bilgisi yerine bir yer tutucu kimlik bilgisi taşır. Ağ geçidi, giden isteği ilgili aracının yetkileriyle eşleştirir, gerçek gizli anahtarın şifresini çözer, bunu isteğin içine yerleştirir ve isteği iletir. Gizli anahtarlar PostgreSQL içinde AES-256-GCM (gelişmiş şifreleme standardı, 256-bit, Galois/sayaç modu) ile şifrelenmiş halde tutulur ve yalnızca istek anında şifreleri çözülür. Her çağrı, aracının kimliği ve hedefi ile birlikte kaydedilir; bu, anahtarlar on kişinin shell profillerinde durduğunda elde edemeyeceğiniz bir denetim izidir.

İki mekanizma, sistemi nasıl dağıtacağınızı belirler.

• HTTPS müdahalesi bir ortadaki adam (man-in-the-middle) saldırısıdır. Ağ geçidi yerel bir sertifika yetkilisi oluşturur, aracı buna güvenir ve ağ geçidi aracının TLS bağlantısını sonlandırıp yukarı akış servisine yeni bir bağlantı açar. HTTP istemcisi ağ geçidi sertifika yetkilisine güvenmeyen bir aracının, kimlik doğrulama hatası yerine sertifika doğrulama hatası vermesinin nedeni budur.
• Aracı, kendini bir Proxy-Authorization başlığı ile tanıtır. Aracıların ve ağ geçidinin dahili bir Docker ağını paylaştığı tek bir sunucuda, bu başlık sizin kontrolünüzde olmayan bir ağdan asla geçmez. Sunucu dışındaki bir aracıya ağ geçidini işaret ederseniz, proxy portunun kendi TLS'ine ihtiyacı olur; çünkü bu başlık bir taşıyıcı (bearer) belirteçtir.

Dürüst takas şudur: Ağ geçidi, tasarım gereği aracınızın yaptığı her isteği düz metin olarak okur. Bu, makinedeki en hassas süreçtir. Barındığı sunucuya buna göre davranın ve sisteme giriş yapabilen kişi sayısını en düşük yetkili Linux kullanıcıları ile sınırlı tutun.

Runner neden gelen port bağlantısına ihtiyaç duymaz

Runner yalnızca dışa dönük çalışır. Dokümantasyonunda belirtildiği üzere: "dış dünyanın erişebileceği hiçbir portu açık tutmaz; bu sayede bir dizüstü bilgisayar, ev laboratuvarı veya NAT arkasındaki bir VPC, herhangi bir giriş trafiği, tünel veya TLS termination gereksinimi olmadan çalışabilir." NAT, yani ağ adresi çevirisi, ev yönlendiricilerinin yaptığı işlemdir. Runner, kontrol düzlemine dışarıdan bağlanır ve işleri oradan çeker; bu nedenle yönlendirilecek veya açılacak hiçbir port yoktur.

Bu tasarım, sandbox ağında avantaj sağlar. Compose dosyası, Docker terminolojisinde ana makine dışına hiçbir rotanın bulunmadığı anlamına gelen internal: true işaretli ikinci bir ağ tanımlar. Sandbox'lar bu ağa katılır. Ağ geçidi her iki ağda da çift yönlü (dual-homed) yapılandırılmıştır, bu yüzden dışarıya çıkışın tek yolu budur. Runner dokümantasyonu bu noktayı açıkça belirtir: "ağ geçidinin çift yönlü olarak bağlı olduğu bir internal ağı, ağ geçidi üzerinden çıkışı bir öneri olmaktan çıkarıp kesin bir sınır haline getirir." Kaynak kodunuzu kendi seçtiği bir adrese göndermeye karar veren bir aracı, bunu yapacak bir rotaya sahip değildir.

Yukarıdaki paragrafa güvenmek yerine kendi makinenizde doğrulayın.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

"Internal": true çıktısını görmelisiniz. Eğer false yazıyorsa, çıkış kontrolü kapalıdır ve ağ geçidi tekrar sadece bir öneri haline gelmiştir. onecli-sandboxes yalnızca varsayılan değer olduğundan, docker network ls komutunun yazdırdığı sandbox ağ adını kullanın.

OneCLI sandbox'ı ne kadar güçlüdür?

Bu bölümü dikkatle okuyun; çünkü "sandbox" ifadesi projenin kendi açıklamasında büyük bir ağırlığa sahipken, mekanizması yalnızca tek bir yerde belgelenmiştir.

README dosyası, her ajanın "kendi dosya sistemine ve kabuğuna sahip, izole bir sandbox" aldığını belirtir ve "her sandbox içinde çalışan, satıcıdan bağımsız bir harness arayüzü ile konuşan ve böylece ajan çalışma zamanının değiştirilebilir olmasını sağlayan" bileşen olarak Sandbox Supervisor'ı isimlendirir. Bu cümlelerin hiçbiri izolasyonun neyden oluştuğunu belirtmez. Çalıştırıcı (runner) belgeleri bunu açıklar: varsayılan arka uç Docker'dır (RUNNER_BACKEND=docker) ve bir sandbox; bellek sınırı, CPU sınırı ve süreç sınırı olan, dahili ağa bağlı bir Docker container'ıdır. Kod, diğer arka uçlar için bir yapı içerir ve belgeler, birinin yazması gereken modüller olarak Kubernetes ve microVM gibi isimlerden bahseder. Bugün, sunucunuzda bir sandbox bir container'dır.

Belgelerin söylemedikleri de en az söyledikleri kadar önemlidir. Bir tehdit modeli yoktur. Docker daemon'ın rootless çalıştırılması, kullanıcı ad alanı eşlemesi (user namespace remapping), Docker'ın varsayılanlarının ötesinde seccomp veya AppArmor profilleri hakkında bir ifade ve gVisor veya microVM gibi bir çekirdek sınırı iddiası yoktur. Bu yüzden dar bir okuma yapın. Sınırlar, kaynak sınırlarıdır. Dahili ağ, gerçek bir çıkış (egress) kontrolüdür. Bir ajan ile ana makineniz arasındaki izolasyon, standart bir Docker container'ının size sunduğu kadardır ve bir container, ana makine çekirdeğini paylaşır.

Dikkate alınması gereken ikinci bir gerçek vardır. Çalıştırıcı servisi /var/run/docker.sock dizinini bağlar (mount), çünkü sandbox'ları bu şekilde oluşturur. Docker soketine erişim, ana makinede root yetkisine eşdeğerdir; çünkü bu API'yi çağırabilen herkes, ana makine dosya sistemini içine bağlayarak bir container başlatabilir. Docker destekli her çalıştırıcı bu şekilde çalışır. Bunun sonucu olarak, çalıştırıcı süreci gateway kadar hassastır.

Yukarı akış (upstream) tarafından yazılı hale getirilene kadar sınırı kanıtlanmamış kabul edin. Uygulamada bu, üç alışkanlık anlamına gelir.

1. OneCLI'ı başka hiçbir iş yapmayan bir makinede çalıştırın. İlişkisiz bir üretim servisi, paylaşılan bir veritabanı veya başka bir ekibin verisi olmasın.
2. Sandbox'ı içinde keyfi kod çalıştırma yetkisi alan bir ajanın ana makineye ulaşabileceğini varsayın ve bu sonucu, makine dışında tutulan yedeklerle yönetilebilir kılın.
3. Bir meslektaşınıza ajanın izole edildiğini söylemeden önce apps/runner/src dosyasını okuyun veya yukarı akışa (upstream) sorun.

Belgelenmiş bir sınırın nasıl göründüğüne dair bir resim ve yukarı akışa (upstream) sorulmaya değer sorular için, bunu gerçek bir ajan sandbox sınırının nasıl göründüğü ile karşılaştırın. Fark, birinin mekanizmayı ve neyi durdurmadığını yazılı hale getirip getirmediğidir.

Lisans ayrımı ve kurulum öncesi kontrol gerekliliği

OneCLI'ın çekirdeği Apache-2.0 lisansına sahiptir ve üretim ortamında self-host edilmesi serbesttir. ee/ olarak adlandırılan dizinler, ayrı bir OneCLI Enterprise License kapsamına girer; geliştirme, test ve değerlendirme süreçleri için ücretsizdir, ancak üretim ortamında kullanım için abonelik gerektirir. 18 Ağustos 2026 tarihli v2.0.1 sürüm notlarında, GitHub tarafından algılanabilir bir Apache-2.0 lisans dosyasının geri getirildiği belirtilmiştir; bu nedenle depo sayfasındaki rozet yakın zamanda değişmiştir. Başka bir tarihte yazılmış özetlere güvenmek yerine, dağıtımını yaptığınız etiketi (tag) kontrol edin.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Bu yolların altındaki her şey ticari kısımdır. Bağımlı olmayı planladığınız bir özellik bu dizinlerde yer alıyorsa, üzerine bir süreç inşa etmeden önce maliyetini hesaplayın.

Yükseltmeler, geçişler ve kaybedilmemesi gereken tek dosya

Yükseltmeler, bir sürüm artışı ve yeniden başlatma işleminden ibarettir. Her up üzerinde API'den önce tek seferlik bir geçiş servisi çalışır; eğer bir geçiş başarısız olursa, yığın yarıda kalmış bir şema ile hizmet vermek yerine başlatılmayı reddeder. Bu, istenen davranıştır çünkü başarısız bir yükseltme, sessiz bir veri bozulması yerine bir kesinti gibi görünür ve docker compose logs migrations bunun nedenini açıklar.

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

Eğer kurulumu yükleme betiği ile yaptıysanız, elle çekmek yerine o betiği tekrar çalıştırın; böylece compose dosyası referans verdiği imajlarla uyumlu kalır.

İki şeyi yedekleyin. PostgreSQL; aracıları, konuşmaları, belleği ve şifrelenmiş gizli verileri tutar. docker/.env dosyası ise SECRET_ENCRYPTION_KEY verisini barındırır; bu anahtar olmadan şifrelenmiş veriler okunamaz, dolayısıyla sadece bir veritabanı dökümü kullanılabilecek hiçbir şeyi geri yüklemez.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Her iki kopyayı da sunucunun dışında tutun. İzlenecek rutin, durum bilgisi tutan (stateful) her Compose yığını için aynıdır; bu nedenle eğer halihazırda bir Docker Compose yığınını yedekleyip yükseltme işlemini bir takvime bağladıysanız, bu iki yolu da o plana ekleyin ve bu konuyu düşünmeyi bırakın.

Çalışmadığı durumlar

• Yığın hiçbir zaman sağlıklı duruma geçmiyor ve docker compose up -d --wait sıfır olmayan bir çıkış kodu döndürüyor. Önce docker compose logs migrations dosyasını okuyun, çünkü API kasıtlı olarak bu servisi bekler.
• Bir agent boşta bekliyor ve hiçbir sandbox görünmüyor. COMPOSE_PROFILES=runner değerinin docker/.env içinde olduğundan ve docker compose ps listesinde bir runner bulunduğundan emin olun. Ardından, sandbox'lar bir model anahtarı olmadan başlatılamayacağı için agent'ın geçerli bir model anahtarına sahip olup olmadığını kontrol edin.
• Kullanılabilir yuva (slot) kalmadı. RUNNER_MAX_SANDBOXES varsayılan olarak 4 değerindedir ve arka plan süreci çalışan bir sandbox, yuvasını kalıcı olarak işgal eder. docker ps komutu, gerçekte nelerin aktif olduğunu gösterir.
• Container'lar kayboluyor veya ana makine yanıt vermekte zorlanıyor. Belleğiniz tükenmiş olabilir. dmesg -T | grep -i oom, çekirdek seviyesindeki bellek yetersizliği (OOM) kaynaklı sonlandırmaları kaydeder; tek bir sandbox kendi başına 2048 MB bellek talep edebilir.
• Bir agent'ın HTTPS çağrıları, kimlik doğrulama hataları yerine sertifika doğrulama hatalarıyla başarısız oluyor. Agent'ın HTTP istemcisi, ağ geçidinin sertifika yetkilisine güvenmiyor.
• Bir agent'ı sildikten sonra eski container'lar veya volume'lar kalmaya devam ediyor. Runner her 60 saniyede bir durumu yeniden kontrol eder ve RUNNER_ORPHAN_GRACE_SECONDS değerinden (varsayılan olarak 3600 saniye) daha eski olan yetim süreçleri temizler; bu nedenle bir sızıntı olduğunu düşünmeden önce bir saat bekleyin.

Bunu çalıştırmanız sizin için doğru bir adım mı?

Uygunluk testi kısadır. Birden fazla kişinin her birinin bir ajana ihtiyaç duyduğu ve kimlik bilgilerini tek bir yerde toplamak istediğiniz durumlarda OneCLI bir çözüm sunar: döndürülecek tek bir depo, okunacak tek bir denetim günlüğü ve bir kişinin erişimini iptal ettiğinizde bunun gerçekten gerçekleştiği tek bir panel. Bu gerçek bir operasyonel sorundur ve bir API anahtarını altı farklı dizüstü bilgisayara kopyalamak bu soruna yönelik daha kötü bir yanıttır.

Tek bir kişi için bu, hiçbir kazanç sağlamayan büyük bir mekanizmadır. Kendinize tek bir ajan sağlamak için PostgreSQL, bir kontrol düzlemi, bir ağ geçidi ve bir çalıştırıcı (runner) çalıştırmış olursunuz; oysa anahtarın tek sahibi siz olduğunuzda ağ geçidinin çözdüğü kimlik bilgisi sorunu neredeyse hiç mevcut değildir. Bunun yerine daha küçük bir sunucuda tek bir harness çalıştırın: VPS üzerinde tek bir ajan harness'ı bu işi çok daha az bellek kullanarak yapar. Henüz bir karar vermediyseniz, self-hosted yapay zeka ajanlarının karşılaştırması başlıklı inceleme daha düşük maliyetli bir ilk adımdır.

FAQ

OneCLI'yi kendi sunucumda barındırmak için gereken minimum sistem gereksinimleri nelerdir?

Docker Compose eklentisi ile birlikte 2.19 veya daha yeni bir sürüm ve yeterli bellek gereklidir. PostgreSQL, compose dosyası ile birlikte geldiği için ayrıca kurulum yapmanız gerekmez. Sunucu planını belirleyen temel unsur bellektir: runner varsayılan olarak her agent sandbox'ı için 2048 MB bellek ayırır. Dokümantasyon, varsayılan dört sandbox sınırını karşılamak için temel yığının üzerine yaklaşık 10 GiB boş alan, PostgreSQL ve dört adet uzun süreli çalışan servis için ise yaklaşık 2 GB bellek önermektedir. 4 GB belleğe sahip bir sunucu aynı anda tek bir agent çalıştırabilir. 16 GB belleğe sahip bir sunucu ise varsayılan sınırı rahatlıkla karşılar. 1 GB veya 2 GB belleğe sahip bir VPS üzerinde barındırılan bir agent başlatılamaz.

OneCLI için PostgreSQL gerekli mi, yoksa SQLite kullanılabilir mi?

PostgreSQL gereklidir. DATABASE_URL bir PostgreSQL bağlantı dizgisi olarak belgelenmiştir, sunulan compose dosyası postgres:18-alpine servisini pgdata birimi ile çalıştırır ve API başlamadan önce şema güncellemelerini uygulamak için ayrı bir migration servisi devreye girer. SQLite seçeneği ile ilgili herhangi bir dokümantasyon bulunmamaktadır. Eğer halihazırda başka bir yerde PostgreSQL çalıştırıyorsanız, DATABASE_URL değerini bu sunucuya yönlendirin ve migration servisini tutmaya devam edin; çünkü başarısız bir migration işlemi, yarım uygulanmış bir şema ile servis vermektense yığının durmasını sağlar.

OneCLI agent sandbox'ı gerçek bir güvenlik sınırı mıdır?

Belgelenen mekanizma; bellek, CPU ve süreç sınırlarına sahip, internal: true olarak işaretlenmiş bir ağa bağlı ve ağ geçidi dışında dışarıya çıkış yolu olmayan bir Docker container'ıdır. Çıkış trafiği kontrolü gerçektir ve bunu docker network inspect ile doğrulayabilirsiniz. Sunucu izolasyonu container seviyesindedir; geliştirici ekip herhangi bir tehdit modeli, rootless veya kullanıcı isim alanı (user-namespace) iddiası ya da gVisor veya microVM gibi bir çekirdek sınırı yayınlamamıştır. Runner ayrıca /var/run/docker.sock dizinini bağlar; bu, sunucu üzerinde root yetkisine eşdeğerdir. Geliştirici ekip tarafından aksi belirtilene kadar agent ile sunucu arasındaki sınırı kanıtlanmamış kabul edin, OneCLI'yi özel bir sunucuda çalıştırın ve yedeklerinizi bu sunucunun dışında tutun.

OneCLI için herhangi bir gelen port açmam gerekiyor mu?

Hayır. Runner yalnızca dışarıya doğru trafik üretir ve dış dünyanın erişebileceği herhangi bir portu dinlemez; bu nedenle NAT arkasında, tünel gerektirmeden çalışır. Compose dosyası varsayılan olarak dashboard, gateway, API ve PostgreSQL servislerini 127.0.0.1 adresine bağlar. Dashboard'a bir SSH tüneli üzerinden erişebilir veya birden fazla kişinin erişmesi gerekiyorsa 10254 numaralı portun önüne TLS destekli bir reverse proxy koyabilirsiniz. 10255 numaralı porttaki gateway agent'lar içindir ve tek bir sunucuda bu agent'lar gateway'e dahili Docker ağı üzerinden ulaşır.

OneCLI şirket içinde ücretsiz olarak kullanılabilir mi?

Çekirdek yazılım Apache-2.0 lisanslıdır ve kendi sunucunuzda ticari lisans gerektirmeden üretim ortamında kullanılmasına izin verilir. ee/ olarak adlandırılan dizinler OneCLI Enterprise Lisansı kapsamındadır; bu lisans geliştirme, test ve değerlendirme süreçleri için ücretsizdir ancak üretim ortamında abonelik gerektirir. Bu ayrım sürümler arasında değişiklik gösterebilir; 18 Ağustos 2026 tarihli v2.0.1 notlarında GitHub üzerinde tespit edilebilir bir Apache-2.0 lisans dosyasının geri getirildiği belirtilmiştir. Bu nedenle, herhangi bir özellik üzerine iş akışı oluşturmadan önce kullandığınız sürümdeki LICENSE dosyasını ve ee/ dizinlerini mutlaka kontrol edin.