SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

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

OneCLI uygulamasını kendi sunucunuzda Docker Compose ile nasıl kuracağınızı öğrenin. Asistan başına 2 GiB RAM gereksinimi ve PostgreSQL veritabanı yapılandırması dahildir.

Self-host OneCLI kullanıldığında elde edilenler

OneCLI self-host edildiğinde ekibinizdeki her kişi kendi agent'ına sahip olur. Her agent kendi sandbox'ında çalışır. API anahtarları, agent'ların hiçbir zaman okuyamadığı bir gateway içinde tutulur. Kurulum, arkasında PostgreSQL bulunan bir Docker Compose stack'idir ve http://localhost:10254 adresinden erişilebilir. Gerçek bir sunucu planlanmalıdır. Belgelenen varsayılan değer, agent sandbox'ı başına 2 GiB bellek sınırıdır. Bu nedenle temel stack için gereken belleği agent'ların gerçek çalışma belleğinden ayrı hesaplayın.

Bu stack içinde sekiz bileşen bulunur. Her bileşenin görevini bilmek, kılavuzun geri kalanını anlamayı kolaylaştırır.

  • Web dashboard (Next.js), 10254 portu. Agent oluşturma, sohbet, bellek ve skill düzenleme, bağlantılar ve secret'lar.
  • API server, 10256 portu. Kontrol düzlemi: veritabanı, konuşma yönetimi ve iş kuyrukları.
  • Rust gateway, 10255 portu. Agent'lardan çıkan istekleri yakalar ve kimlik bilgilerini ekler.
  • Runner. README bu bileşeni, "agent sandbox'larını başlatan, beklemeye alan ve sonlandıran bileşen. Yalnızca dışarı doğru bağlantı kurar ve veritabanına hiçbir zaman erişmez." şeklinde tanımlar.
  • Sandbox Supervisor. README bu bileşenin "her sandbox'ın içinde çalıştığını ve agent runtime'ının değiştirilebilmesi için vendor-neutral bir harness arayüzü üzerinden iletişim kurduğunu" belirtir.
  • SSH terminator, 10257 portu. README bunu "SSH ön kapısı" olarak adlandırır. API tarafından verilen kısa ömürlü sertifikalarla SSH bağlantısını sonlandırır ve her oturumu bir agent'ın sandbox'ına aktarır. Runner ile aynı runner profili altında çalışır.
  • Channel adapter. Bir Slack uygulamasına bağlanan daemon'dur. Böylece bir agent, kanallarda ve DM'lerde kendi adıyla yanıt verebilir.
  • PostgreSQL. Birlikte sunulan compose dosyası postgres:18-alpine değerini pgdata volume'u ile ç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: organizasyonlar ve davetiyeler içeren bir hesap sistemi, konuşmalar ve gizli verilerden oluşan bir veritabanı ve container 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 bir sandbox içinde çalışır." Her aracının kendi dosya sistemi, kabuğu, kendine ait 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 saklar ve onu kullanma izni olan aracılara tanımlarsınız.

Başlamadan önce sistemin gereksinimleri

  • Docker ve 2.24.0 veya daha yeni sürüme sahip Compose eklentisi. Sağlanan compose dosyası, Docker'ın 2.24.0 sürümünden itibaren desteklediği required: false ile isteğe bağlı env_file eşlemelerini kullanır. Geçiş açıklamalarında belirtilen 2.19 alt sınırı, up --wait altındaki tek seferlik bağımlılıkları desteklemek içindir; ancak bu sınır, dosyanın isteğe bağlı environment dosyalarını kapsamaz.
  • Bellek; asıl kısıt budur. Bir plan seçmeden önce aşağıdaki boyutlandırma bölümünü okuyun.
  • 10254, 10255, 10256, 10257 ve 5432 loopback portlarının boş olması. 10257, bu kılavuzun etkinleştirdiği runner profiliyle başlatılan SSH giriş noktasıdır.

PostgreSQL'i kendiniz kurmanız gerekmez; compose dosyası PostgreSQL'i bir servis olarak çalıştırır. Aşağıdaki kurulum sihirbazı için host üzerinde Node.js ve pnpm gerekir. Kod üzerinde çalışırken, Rust dahil toolchain'i sabitlemek için mise de kullanılır.

VPS'nizde kaç agent sandbox'ı çalışabilir?

Runner'ın kendi belgelerinde tahmini değerler yerine gerçek sayılar verilir. Her sandbox için bellek üst sınırı 2048 MB (RUNNER_SANDBOX_MEMORY_MB), CPU üst sınırı bir çekirdek (RUNNER_SANDBOX_CPUS) ve süreç üst sınırı 512'dir (RUNNER_SANDBOX_PIDS). Eşzamanlılık üst sınırı 4'tür (RUNNER_MAX_SANDBOXES). Belgelerde bu üst sınırı karşılamak için temel stack'e ek olarak yaklaşık 10 GiB boş bellek önerilir.

GrafikAgent memory budgets per box, using the documented 2 GiB cap
Bu grafiğin arkasındaki veriler
[
  {
    "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 slot sayıları benchmark sonucunu değil, aritmetik hesabı gösterir: toplam bellekten PostgreSQL ve uzun süre çalışan diğer servisler için varsayılan yaklaşık 2 GB çıkarılır ve kalan miktar 2 GiB sandbox üst sınırına bölünür. Bu hesaba göre 2 GB box, tam bellek üst sınırında 0 sandbox için yeterli bütçe sağlar. Sıfır, bu varsayımlar altında tam üst sınır için bütçe bulunmadığı anlamına gelir; Docker'ın agent başlatmayı reddettiği anlamına gelmez. 16 GB box, 7 sandbox için alan bırakır. Bu değer, varsayılan dört sandbox üst sınırının ve runner belgelerinde istenen yaklaşık 10 GiB boş belleğin rahatça üzerindedir. 32 GB box, değeri 15 seviyesine çıkarır. Aynı anda dörtten fazla sandbox çalıştırmak için RUNNER_MAX_SANDBOXES değerinin de artırılması gerekir.

Bu aritmetiği iki durum değiştirir. Arka plan süreci çalışan bir sandbox askıya alınmaz. Bu nedenle slotunu kalıcı olarak tutar. Dolayısıyla RUNNER_MAX_SANDBOXES, en yoğun dakikaya göre değil, sürekli yükü karşılayacak şekilde boyutlandırılmalıdır. Platform bu durum için de bir üst sınır uygular: varsayılan olarak her runner, en fazla RUNNER_MAX_SANDBOXES eksi bir uyanık tutulan sandbox bulundurur; bu sayı hiçbir zaman birden az olmaz ve API üzerinde MAX_HELD_AWAKE_SANDBOXES ile değiştirilebilir. Bu sınır aşıldığında en uzun süredir boşta olan sandbox sonlandırılır ve izlenen sürecin kaybolduğu bildirilir. Bellek ve CPU kullanımı yapılan işe bağlıdır. Her sandbox bir CPU ile sınırlandırılmıştır. Bu nedenle yoğun çalışan dört agent dört çekirdek kullanabilir. Ancak 2 GiB bellek ayarı bir üst sınırdır, ayrılmış kaynak miktarı değildir. Uyanık durumdaki dört boşta agent otomatik olarak 8 GiB tüketmez.

Değiştirmek isteyebileceğiniz Runner ayarları
  • RUNNER_MAX_SANDBOXES (varsayılan 4): aynı anda çalıştırılan sandbox sayısı.
  • RUNNER_SANDBOX_MEMORY_MB (varsayılan 2048): sandbox başına bellek üst sınırı.
  • RUNNER_SANDBOX_CPUS (varsayılan 1): sandbox başına CPU üst sınırı.
  • RUNNER_SANDBOX_PIDS (varsayılan 512): sandbox başına süreç üst sınırı.
  • RUNNER_NETWORK_INTERNAL (varsayılan true): sandbox ağının dışarıya rota içermemesini sağlar. Bu ayar açık bırakılmalıdır.
  • RUNNER_SANDBOX_NETWORK (varsayılan onecli-sandboxes): sandbox'ların katıldığı ağ.
  • RUNNER_RECONCILE_SECONDS (varsayılan 60): runner'ın durumu uzlaştırma sıklığı.
  • RUNNER_ORPHAN_GRACE_SECONDS (varsayılan 3600): sahipsiz container ve volume'ların silindiği yaş sınırı.
  • RUNNER_AGENT_IMAGE: sandbox image'ını geçersiz kılar; aksi halde image ONECLI_VERSION değerini izler.

OneCLI, Docker Compose ile kurulur

Upstream self-hosting dokümanındaki ham sıra, compose dosyasının yanındaki docker/.env dosyasına üç secret yazar. Bu sırada, etkinleştirdiği servislerin ihtiyaç duyduğu runner token, Docker socket grubu ve SSH kimlik bilgileri yer almaz. Bu nedenle stack'i başlatmadan önce kurulum sihirbazı çalıştırılmalıdı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
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Çalıştırmadan önce bu bloğu okuyun. Heredoc işareti tırnak içine alınmadığı için shell, her head -c 32 /dev/urandom | base64 ifadesini çalıştırır ve sonucu değişmez metin yerine dosyaya yazar. SECRET_ENCRYPTION_KEY, veritabanındaki tüm secret'lar için kullanılan AES-256-GCM anahtarıdır. GATEWAY_INTERNAL_SECRET, gateway'in API'ye kimlik doğrulaması yapmasını sağlar. BETTER_AUTH_SECRET, oturum çerezlerini imzalar. En önemli satır COMPOSE_PROFILES=runner satırıdır; runner servisi bir Compose profile arkasında çalışır. Bu satır eklenmezse stack sağlıklı durumda başlar, ancak hiçbir agent sandbox'ı başlatılmaz.

--wait, servislerin çalışır veya sağlıklı durumda olmasını ve migrations bağımlılığının başarıyla tamamlanmasını bekler. Bu nedenle sıfır olmayan bir çıkış kodu, bir şeylerin yanlış olduğuna dair ilk göstergedir. Ardından gerçekte hangi servislerin başladığı incelenmelidir.

docker compose ps
docker compose logs migrations

Sürümü sabitleyin. ONECLI_VERSION, tüm servislerin tag değerini tek seferde belirler. Agent sandbox image'ı da RUNNER_AGENT_IMAGE başka bir konumu göstermediği sürece bu değeri kullanır. Yalnızca sürüm numarasını kullanın; yayımlanan image tag'lerinde v öneki bulunmaz. 1 November 2026 itibarıyla güncel sürüm v2.17.0 sürümüdür ve 31 October 2026 tarihinde yayımlanmıştır. Bu değeri aynı dosyaya ekleyin. Ardından çalışan sandbox'ların da bu image'a taşınması için belgelenen upgrade yolunu kullanın.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

curl -fsSL https://onecli.sh/install | sh adlı bir installer da bulunur. Bu installer yapılandırmasını ~/.onecli/.env dosyasına yazar ve aynı işlemleri gerçekleştirir. Kendi çalışması için ONECLI_VERSION=latest değerini ayarlar. Bu değer, yalnızca .env dosyasında tutulan sürüm sabitlemesini geçersiz kılar. Compose yolu, çalıştırmadan önce her dosyanın okunabilmesini sağlar. Başka Compose stack'lerini zaten barındıran bir sunucuda kullanılacak yol da budur. Yukarıdaki checkout kurulumu, pnpm run setup --upgrade ile upgrade yapar. Bu yol, host üzerinde Node.js ve pnpm bulunmasını gerektirir. Kodun kendisi üzerinde çalışmak ise gateway için mise ve Rust eklenmesini gerektirir. Bu nedenle OneCLI üzerinde değişiklik yapmayı planlayanlar için uygundur. Kubernetes için 8 October 2026 tarihli v2.11.0 sürümünde bir Helm chart eklendi. Güncel chart, agent sandbox'larını Docker daemon olmadan, persistent volume kullanan Job nesneleri olarak çalıştırır. Gerekli secret'ları, veritabanı yapılandırmasını ve routing ayarlarını da belgeler.

Dizgi paneline dizüstü bilgisayardan erişme

Yayınlanan compose dosyasındaki her port ${ONECLI_BIND_HOST:-127.0.0.1} adresine bind edilir. VPS üzerinde bu, dizgi panelinin çalıştığı ancak kutu dışından hiçbir istemcinin ona erişemediği anlamına gelir. Bu varsayılan ayar doğrudur. Bu ayarı koruyun ve tünel oluşturun:

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 taşınır. Böylece genel internette şifrelenmemiş bir dizgi paneli bulunmaz ve güvenlik duvarında ek bir port açmanız gerekmez.

ONECLI_BIND_HOST=0.0.0.0 ayarlanırsa dizgi paneli düz HTTP üzerinden yayınlanır. Ayrıca, POSTGRES_PASSWORD ayarlanmadığı sürece PostgreSQL, compose dosyasındaki onecli varsayılan parolasıyla birlikte yayınlanır. Docker socket'ini mount eden SSH ön kapısı da 10257 numaralı port üzerinden yayınlanır. Birden fazla kişinin dizgi paneline erişmesi gerekiyorsa önüne TLS (transport layer security) kullanan bir reverse proxy yerleştirin ve bind host ayarını değiştirmeyin. ONECLI_EXTERNAL_URL değerini HTTPS URL'si olarak ayarlayın ve upstream'in reverse proxy yapılandırmasını kullanın. Bu yapılandırma, dizgi paneli, API ve gateway yollarını ilgili servislere yönlendirir. Tek başına bir proxy, yetkisiz kişilerin erişimini engellemez. Self-hosting belgesinde, kayıt işleminin tasarım gereği açık olduğu ve bunu kapatacak bir ayarın bulunmadığı belirtilir. Dizgi paneline erişebilen herkes bir hesap oluşturabilir. Bu hesap kendi organization'ına sahip olur; yalnızca sizin organization'ınıza katılım davet gerektirir. Belgenin önerisi, dizgi panelinin ağ sınırınızın arkasında tutulmasıdır. Bu proxy diğer self-hosted uygulamalarınızın da önünde bulunuyorsa forward auth kullanarak self-hosted bir single sign-on katmanına yönlendirme yapılabilir. Böylece dizgi paneli, ekibinizin hâlihazırda kullandığı oturum açma mekanizmasının arkasında kalır ve bir kişinin erişimini tek bir yerden kaldırmanız bu kapıyı da kapatır.

İlk hesabı oluşturun, ardından bir model key tanımlayın

Dashboard'u açın ve hemen hesabınızı oluşturun. Her yeni hesap için ayrı bir organization oluşturulur; ekip arkadaşları davet yoluyla sizin organization'ınıza katılır. Bundan sonra kayıt işlemi açık kalır. Bu da dashboard'un tunnel veya kimlik doğrulamalı bir proxy arkasında tutulması için ek bir nedendir. Login özelliğinden önceki bir release sürümünden yükseltme yapıyorsanız hemen kayıt olun. Self-hosting dokümanında, mevcut verilerin ilk kayıt olan hesaba aktarılacağı belirtilir. Bu nedenle erişilebilir bir host üzerinde bu hesabın size ait olması gerekir.

Ardından bir agent oluşturmadan önce bir model key saklayın. Hosted agent için tanımlanmış bir model key gerekir ve sıra önemlidir: key'i dashboard'da saklayın, agent'a tanımlayın ve ancak bundan sonra bir conversation başlatın. Grant işlemini atlarsanız sandbox başlatılmaz. Agent, thread içinde model key'e ihtiyaç duyduğunu belirten bir yanıt verir.

Grant kapsamını dar tutun. Her agent yalnızca kendisine tanımlanan kaynaklara erişebilir ve gateway bu kuralı her request'te uygular. Bu nedenle tek bir repository okuyan bir agent'ın payment provider key'inize erişebileceği bir yol bulunmaz. Aynı grant listesi harcamaları kontrol etmenizi de sağlar. Sahip olduğunuz herhangi bir modeli çağırabilen kişisel bir agent, kişi başına ayrı bir fatura anlamına gelir. Bu nedenle on agent vermeden önce bir agent'ın model çağrılarına ne kadar harcayabileceğini sınırlama yöntemini incelemeniz gerekir.

Ağ geçidi anahtarları agent süreçlerinden nasıl uzak tutar

Ağ geçidi, Rust ile yazılmış ve 10255 numaralı portu dinleyen bir HTTPS proxy'sidir. Agent'ın HTTP istemcisi bu proxy'yi kullanacak şekilde yapılandırılır ve agent, gerçek kimlik bilgisi yerine bir yer tutucu kimlik bilgisi taşır. Ağ geçidi, giden isteği agent'a tanımlanan yetkilerle eşleştirir, gerçek sırrın şifresini çözer, sırrı isteğe ekler ve isteği upstream servise iletir. Sırlar PostgreSQL içinde AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) ile şifrelenmiş olarak tutulur ve yalnızca istek sırasında çözülür. Her çağrı agent kimliği ve hedefiyle birlikte loglanır. Bu, anahtarlar on kişinin shell profiline dağıldığında elde edilemeyecek bir denetim izi sağlar.

Dağıtım yöntemini iki mekanizma belirler.

  • HTTPS interception, man-in-the-middle işlemidir. Ağ geçidi yerel bir certificate authority oluşturur ve agent bu certificate authority'ye güvenir. Ardından ağ geçidi, agent'ın TLS bağlantısını sonlandırır ve upstream servise yeni bir bağlantı açar. Bu nedenle HTTP istemcisi ağ geçidinin certificate authority'sine güvenmeyen bir agent, authentication hatası yerine certificate verification hatası alır.
  • Agent kendisini bir Proxy-Authorization header ile tanımlar. Agent'ların ve ağ geçidinin dahili bir Docker network'ünü paylaştığı tek sunuculu kurulumda bu header, sahip olmadığınız bir ağdan geçmez. Sunucu dışındaki bir agent'ı ağ geçidine yönlendiriyorsanız bağlantıyı VPN veya TLS transport ile koruyun. Bu header bir bearer token'dır. Upstream, ham CONNECT proxy portu için VPN kullanılmasını önerir.

Gerçek ödünleşim şudur: Ağ geçidi, tasarım gereği agent'ların yaptığı her isteği plaintext olarak okur. Makinedeki en hassas süreç budur. Bu nedenle ağ geçidinin çalıştığı hostu uygun şekilde koruyun ve en az ayrıcalıklı Linux kullanıcıları ile oturum açabilen kişi sayısını düşük tutun.

Runner neden gelen bağlantılar için port gerektirmez

Runner yalnızca dışarıya bağlantı başlatır. Belgelerinde şu ifade yer alır: "dış dünyanın erişebileceği hiçbir portu açık tutmaz; bu nedenle laptop, homelab veya NAT arkasındaki bir VPC, gelen bağlantı, tünel ve TLS termination yapılandırması olmadan çalışır." NAT, ağ adresi çevirisidir ve ev router'larının yaptığı işlemdir. Runner control plane'e dışarıya doğru bağlantı kurar ve işleri buradan çeker. Bu nedenle yönlendirilecek veya açılacak bir port yoktur.

Bu tasarım sandbox ağında avantaj sağlar. Compose dosyası internal: true ile işaretlenmiş ikinci bir ağ tanımlar. Docker'da bu, dış ağ bağlantısının bulunmadığı anlamına gelir. Sandbox'lar bu ağa katılır. Gateway her iki ağa da bağlıdır ve dışarı çıkış için kullanılabilecek tek yoldur. Runner belgeleri amacı açıkça belirtir: "gateway'in her iki ağa da bağlı olduğu bir internal ağ, yalnızca gateway üzerinden dışarı çıkışın bir öneri değil, bir sınır olmasını sağlar." Bir agent, harici bir adrese doğrudan bağlantı açarak gateway'i atlayamaz. Hangi isteklerin gönderilmesine izin verileceğine yine gateway politikası karar verir.

Yukarıdaki açıklamaya güvenmek yerine bunu kendi sisteminizde doğrulayın.

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

"Internal": true çıktısını görmeniz gerekir. Çıktı false ise dışarı çıkış denetimi devre dışıdır ve gateway yeniden yalnızca bir öneri durumuna gelmiştir. docker network ls çıktısının yazdırdığı sandbox ağ adını kullanın; onecli-sandboxes yalnızca varsayılan değerdir.

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

Bu bölümü yavaş okuyun. Çünkü projenin kendi açıklamasında "sandboxed" ifadesine büyük anlam yükleniyor. Ancak mekanizma runner belgelerinde ve backend kodunda açıklanıyor.

README, her agent'ın "kendi yalıtılmış sandbox'ına, dosya sistemine ve shell'e" sahip olduğunu belirtir. Ayrıca Sandbox Supervisor bileşeninin "her sandbox'ın içinde çalıştığını ve agent runtime'ının değiştirilebilmesi için vendor-neutral bir harness arayüzü üzerinden iletişim kurduğunu" söyler. Bu iki ifade izolasyonun hangi mekanizmayla sağlandığını açıklamaz. Runner belgeleri bunu açıklar: varsayılan backend Docker'dır (RUNNER_BACKEND=docker). Sandbox, bellek, CPU ve işlem sınırları olan ve internal network'e bağlanan bir Docker container'ıdır. Kodda diğer backend'ler için de bir genişleme noktası bulunur. Güncel runner kodu, Helm chart'ın sandbox Job'ları ve kalıcı volume'lar için kullandığı bir Kubernetes backend'ı da uygular. Bu kılavuzdaki Compose kurulumunda sandbox, Docker container'ıdır.

Runner belgeleri artık Docker sınırını şöyle açıklar: agent, node olarak ve no-new-privileges ile çalışır; tüm Linux capability'leri kaldırılır ve Docker'ın varsayılan seccomp profili kullanılır. Backend, yalnızca agent'ın kalıcı home dizinini sandbox'a mount eder. Bu nedenle kapsamı dar yorumlayın. Sınırlar kaynak sınırlarıdır. Internal network gerçek bir dışa çıkış denetimidir. Agent ile host arasındaki izolasyon bu container denetimlerini kullanır. Container, host kernel'ını paylaşır.

Dikkate alınması gereken ikinci bir nokta daha vardır. Runner servisi /var/run/docker.sock mount eder. Çünkü sandbox'ları bu şekilde oluşturur. Rootful Docker daemon'ın socket'ine erişim, host üzerinde root yetkisine eşdeğerdir. Bunun nedeni, bu API'yi çağırabilen herkesin host dosya sistemini container içine mount ederek container başlatabilmesidir. Dağıtılan Docker tabanlı runner bu socket'i kullanır. Bunun sonucu olarak runner süreci gateway kadar hassastır. SSH terminator, sandbox container'larında exec çalıştırabilmek için aynı socket'i mount eder. Compose dosyasındaki yorumlar da bu mount işleminin host üzerinde root yetkisine eşdeğer olduğunu belirtir. Bu nedenle 10257 portunu açmak için özel bir nedeniniz yoksa loopback üzerinde tutun.

Paylaşılan kernel sınırını ihtiyatlı biçimde değerlendirin. Uygulamada bunun için üç alışkanlık edinilmelidir.

  1. OneCLI'ı başka iş yapmayan bir makinede çalıştırın. İlişkisiz bir production servisi, paylaşılan bir veritabanı veya başka bir ekibin verileri bu makinede bulunmamalıdır.
  2. Sandbox içinde rastgele kod çalıştırma yetkisi elde eden bir agent'ın host'a ulaşabileceğini varsayın. Bu sonucun etkilerini, makine dışında tutulan yedeklerle karşılanabilir hale getirin.
  3. Bir iş arkadaşınıza agent'ın yalıtıldığını söylemeden önce apps/runner/src dosyasını okuyun veya upstream'e danışın.

Belgelenmiş bir sınırın nasıl göründüğünü ve upstream'e sorulması gereken soruları görmek için bunu gerçek bir agent sandbox sınırının nasıl göründüğüyle karşılaştırın. Asıl soru, belgelenen mekanizmanın durdurmasını istediğiniz tehditleri kapsayıp kapsamadığıdır.

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 kaybedilemeyecek tek dosya

Yükseltmeler, servis image'larını ve ayrı agent image'ını güncellemeli, ardından çalışan sandbox'ları yeniden başlatmalıdır. Tek seferlik bir migrations servisi her up öncesinde API'den önce çalışır. Migration başarısız olursa stack, kısmen geçirilmiş bir şemayla hizmet vermek yerine başlatılmaz. İstenen davranış budur. Çünkü başarısız bir yükseltme sessiz veri bozulması yerine kesinti olarak görünür ve docker compose logs migrations bunun nedenini açıklar.

Bir adımın gözden kaçması kolaydır. Self-hosting belgesi, agent sandbox image'ı bir Compose servisi olmadığı için yalnızca docker compose pull && docker compose up -d kullanarak yükseltme yapılmaması gerektiği konusunda uyarır. Bu image, runner üzerindeki RUNNER_AGENT_IMAGE değeridir. Bu nedenle docker compose pull onu göremez ve hosted agent'lar herhangi bir uyarı olmadan eski bir sandbox image'ı kullanmaya devam edebilir. Checkout'u güncelleyin, pin değerini değiştirin ve sandbox image'ını çeken, ardından çalışan sandbox'ları yeniden başlatan belgelenmiş yükseltme aracını çalıştırın.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

2.17.0 değerini geçiş yaptığınız release ile değiştirin. Sandbox'ların yeniden başlatılması devam eden işleri keser. Her agent'ın kalıcı çalışma alanı korunur.

Bunun yerine install script ile kurulum yaptıysanız elle pull işlemi yapmak yerine bu script'i yeniden çalıştırın. Böylece Compose dosyası, başvurduğu image'larla uyumlu kalır. Belirli bir release kullanmak istiyorsanız önce ONECLI_VERSION değerini dışa aktarın. Çünkü script, yalnızca kendi .env dosyasında tutulan pin değerini geçersiz kılar.

Veritabanını, yapılandırmayı ve agent workspace volume'larını yedekleyin. PostgreSQL; agent'ları, konuşmaları, belleği ve şifrelenmiş secret'ları tutar. docker/.env dosyası SECRET_ENCRYPTION_KEY değerini içerir. Bu anahtar olmadan veritabanının geri kalanı geri yüklense bile şifrelenmiş secret'lar okunamaz. Her agent'ın /workspace değeri ayrı bir kalıcı volume üzerinde bulunur ve kendi yedeğini gerektirir.

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

Bu kopyaları ve workspace yedeklerini sunucunun dışında saklayın. İzlenecek yöntem, durum bilgisi tutan herhangi bir Compose stack'i için gereken yöntemle aynıdır. Bu nedenle zaten düzenli olarak Docker Compose stack'ini yedekleyip yükseltiyorsanız, veritabanı, yapılandırma ve workspace volume'larını bu sürece ekleyin ve konuyu ayrıca takip etmeyin.

Çalışmadığında

  • Stack sağlıklı duruma hiç gelmiyor ve docker compose up -d --wait sıfırdan farklı bir çıkış koduyla sonlanıyor. Önce docker compose logs migrations dosyasını okuyun; API bu servisi bilerek bekler.
  • Bir agent boşta kalıyor ve hiçbir sandbox görünmüyor. COMPOSE_PROFILES=runner değerinin docker/.env içinde bulunduğunu ve docker compose ps çıktısında bir runner listelendiğini doğrulayın. Ardından agent'a kullanılabilir bir model anahtarı verildiğini kontrol edin; sandbox'lar bu anahtar olmadan başlatılmaz.
  • Kullanılabilir slot kalmıyor. RUNNER_MAX_SANDBOXES varsayılan olarak 4 değerini kullanır. Arka plan süreci çalışan bir sandbox, held-awake sınırı tarafından sonlandırılana kadar slotunu tutar. docker ps gerçekten çalışan süreçleri gösterir.
  • Stack başlatılamıyor ve Docker bir portun zaten kullanımda olduğunu bildiriyor. runner profili etkin olduğunda SSH giriş noktası, diğer dört porta ek olarak 10257 portunu da kullanmak ister.
  • Container'lar kayboluyor veya host ağır çalışıyor. dmesg -T | grep -i oom ile bellek tükenmesini kontrol edin; varsayılan bellek sınırı, tek bir sandbox'ın 2048 MB'a kadar kullanmasına izin verir.
  • 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 gateway'in sertifika yetkilisine güvenmiyor.
  • Bir agent'ı sildikten sonra eski container'lar veya volume'lar kalıyor. Runner her 60 saniyede bir mevcut durumu beklenen durumla uzlaştırır ve RUNNER_ORPHAN_GRACE_SECONDS değerinden daha eski sahipsiz kaynakları siler. Bu değer varsayılan olarak 3600'dür. Bunu kaynak sızıntısı olarak değerlendirmeden ö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 yapı, herhangi bir fayda sağlamadan gereksiz bir operasyonel yük oluşturur. Tek bir agent çalıştırmak için PostgreSQL, bir control plane, bir gateway ve bir runner kurmanız gerekir. Gateway'in çözdüğü credential sorunu, anahtara sahip tek kişi siz olduğunuzda neredeyse ortadan kalkar. Bunun yerine daha küçük bir sunucuda tek bir harness çalıştırın: VPS üzerinde tek bir agent harness. Aynı işi belleğin çok daha küçük bir bölümünü kullanarak yapar. Henüz herhangi bir yön belirlemediyseniz self-hosted AI agent karşılaştırması içeren inceleme daha düşük maliyetli ilk adımdır. Sizin için yabancı olan konu agent'ların kendisiyse ve bunların çalıştığı sunucular değilse, önce agent'ların gerçekte nasıl çalıştığını öğrenmek için aşamalı yol içeriğini izleyin. Çünkü tool call ve memory store işlemlerinin gerçekte ne yaptığını bilmek, her kişinin agent'ına hangi izinlerin verilmesi gerektiğini belirlemenizi sağlar.

FAQ

OneCLI'yi self-host etmek için gereken minimum sunucu özellikleri nelerdir?

Compose plugin'li Docker 2.24.0 veya üzeri, burada kullanılan kurulum sihirbazı için Node.js ve pnpm ve yeterli bellek gerekir. PostgreSQL compose dosyasıyla birlikte gelir; ayrı olarak kurulması gerekmez. Planı belirleyen bellek miktarıdır: runner, her agent sandbox'ını varsayılan olarak 2048 MB ile sınırlar ve belgelerinde, dört sandbox için varsayılan sınırı karşılamak üzere temel stack'in üzerinde yaklaşık 10 GiB boş bellek bulunması istenir. Grafikte varsayılan 2 GB temel stack bütçesi esas alındığında, 4 GB'lık bir sunucuda tam sınırında çalışan bir sandbox için, 16 GB'lık bir sunucuda ise varsayılan eşzamanlılık sınırı için bütçe ayrılmış olur. Bunlar planlama değerleridir; ölçülmüş minimum gereksinimleri veya sabit bellek tahsislerini ifade etmez.

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

PostgreSQL gerekir. DATABASE_URL bir PostgreSQL bağlantı dizesi olarak belgelenmiştir, ürünle birlikte gelen compose dosyası postgres:18-alpine hizmetini pgdata volume'u ile çalıştırır ve ayrı bir migrations hizmeti, API başlatılmadan önce şemayı uygular. Belgelenmiş bir SQLite seçeneği yoktur. Harici bir PostgreSQL sunucusu kullanılacaksa API ve migrations hizmetinin ikisi de bu sunucuyu kullanacak şekilde yapılandırılmalıdır; ürünle birlikte gelen compose dosyası, bağlantı dizelerini kendi PostgreSQL hizmetine ayarlar.

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

Belgelenen Compose mekanizması, bellek, CPU ve süreç sınırları uygulanan bir Docker container'ıdır. Container, internal: true olarak işaretlenmiş bir ağa bağlanır; bu nedenle dış trafiği gateway üzerinden geçer. Egress denetimi gerçektir ve docker network inspect ile doğrulanabilir. Agent node olarak çalışır; no-new-privileges kullanır, tüm Linux yetenekleri kaldırılmıştır ve Docker'ın varsayılan seccomp profili kullanılır. Ancak host kernel'i paylaşılır. Runner ve SSH terminator /var/run/docker.sock yolunu mount eder. Bu, rootful Docker daemon kullanan bir host üzerinde root erişimine eşdeğerdir. OneCLI ayrı bir sunucuda çalıştırılmalı ve yedekler bu sunucunun dışında tutulmalıdır.

OneCLI için inbound port açmam gerekir mi?

Hayır. Runner yalnızca outbound bağlantı kurar ve dış dünyanın erişebileceği port açmaz. Bu nedenle tunnel olmadan NAT arkasında çalışabilir. Compose dosyası varsayılan olarak dashboard, gateway, API ve PostgreSQL hizmetlerini; ayrıca runner profili altında SSH front door'u 10257 portunda 127.0.0.1 adresine bind eder. Dashboard'a SSH tunnel üzerinden erişilebilir. Birden fazla kişinin erişmesi gerekiyorsa, TLS ile upstream reverse proxy yapılandırması ve gerekli dashboard, API ve gateway route'ları kullanılabilir. Ancak registration işleminin, bu hizmete erişebilen herkese açık kaldığı unutulmamalıdır. 10255 portundaki gateway agent'lar içindir. Tek sunuculu kurulumda bu agent'lar gateway'e dahili Docker ağı üzerinden erişir.

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

Çekirdek bileşen Apache-2.0 lisanslıdır ve self-hosted production kullanımına ticari lisans gerekmeksizin izin verilir. ee/ adındaki dizinler OneCLI Enterprise License kapsamındadır. Bu lisans geliştirme, test ve değerlendirme için ücretsizdir; production kullanımında subscription gerekir. Bileşenlerin ayrımı releases arasında değişebilir. 18 August 2026 tarihli v2.0.1 notlarında, GitHub tarafından algılanabilen Apache-2.0 lisans dosyasının geri getirildiği belirtilir. Bu nedenle tek bir özelliğe dayalı workflow oluşturmadan ve build almadan önce, dağıtılacak exact tag içindeki LICENSE ve ee/ dizinleri kontrol edilmelidir.

Bu yazı işinize yaradı mı?