Octop kendi sunucunuzda nasıl kurulur ve yapılandırılır

Octop nedir ve neden kendi sunucunuzda barındırmalısınız

Octop, bir hane veya küçük bir ekip için tasarlanmış, kendi sunucunuzda barındırabileceğiniz bir yapay zeka asistanıdır. Octop'u basit bir sohbet arayüzü yerine kendi sunucunuzda barındırmanızın temel nedeni, kullanıcıları birbirinden izole etmesidir. Open WebUI, bir modelin önünde tarayıcı tabanlı bir arayüz sunar. Octop ise buna yönetici rolüne sahip hesaplar, her kullanıcı için özel bir çalışma alanı ve kimlik bilgisi seti ile kullanıcıların görev bazında geçiş yapabileceği uzman aracı kütüphaneleri ekler. Bir VPS'in tek bir kişi yerine beş kişiye hizmet vermesini sağlayan fark budur.

Proje github.com/TencentCloud/Octop adresinde yer almaktadır. Web paneli, komut satırı arayüzü, sohbet kanalları (Feishu, DingTalk, QQ, Discord, WeCom) ve zamanlanmış görevleri yöneten tek bir süreçten oluşur; tüm veriler ~/.octop/ altındaki tek bir SQLite veritabanında tutulur. Aşağıdaki tüm bilgiler, 5 Ağustos 2026 tarihinde yayınlanan v0.9.19 etiketine göre hazırlanmıştır. Platformlar arasında hala karar verme aşamasındaysanız, VPS üzerinde çalıştırabileceğiniz Open WebUI alternatiflerinin karşılaştırması başlıklı yazı daha geniş bir perspektif sunmaktadır.

Bu işe bir akşamınızı ayırmadan önce netleştirilmesi gereken bir konu var. Bu rehber yazıldığında Octop, bir üreticinin GitHub organizasyonu üzerinden yayınlanan, 1.0 sürümü öncesi bir yazılımdı ve Ağustos 2026 itibarıyla yaklaşık 900 yıldızı bulunuyordu. Proje, 14 Eylül 2026 tarihinde v1.0.0 etiketini aldı. 20 Ekim 2026 itibarıyla en güncel sürüm, 1.0.2 beta etiketlerinden sonra 18 Ekim 2026'da yayınlanan v1.0.2 kararlı sürümüdür ve depo yaklaşık 10.400 yıldıza ulaşmıştır. Aşağıdaki adımlar v0.9.19 sürümü baz alınarak yazılmıştır ve 1.x sürümlerinde tekrar test edilmemiştir. Proje hızlı ilerlemektedir; sürüm numaraları bunu doğrulamaktadır ve buradaki hiçbir bilgi kararlı bir yükseltme yolu garantisi vermez. Bir etiketi sabitleyin, değişiklik günlüğünü (changelog) okuyun ve yedeklerinizi alın.

Başlamadan önce gerekenler

• Docker Engine ve Compose eklentisi kurulu bir Ubuntu 24.04 VPS. Compose konusunda yeniyseniz, VPS için Docker Compose temelleri ile başlayın.
• git, çünkü bir imajı çekmek yerine bir sürüm etiketini (release tag) kullanacaksınız.
• VPS'e yönlendirilmiş bir alan adı, çünkü ön tarafta TLS (transport layer security) kullanmak isteyeceksiniz.
• OpenAI API ile uyumlu bir model arka ucu: yerel bir Ollama, kendi barındırdığınız bir ağ geçidi veya ücretli bir anahtar.

Octop kendi başına hafiftir. Bir Python süreci ve bir SQLite dosyasından oluşur. Yük, model arka ucundan kaynaklanır; bu nedenle modeli aynı sunucuda çalıştırmayı planlıyorsanız, sunucuyu modelin gereksinimlerine göre boyutlandırın.

curl yükleyicisini neden önermiyoruz

README dosyası tek satırlık bir kurulum komutuyla başlar:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Önem verdiğiniz bir sunucuda bunu önermiyoruz, bunun somut bir nedeni var: söz konusu betik depoda yer almıyor. Bu betik, bir Tencent Cloud Object Storage bucket üzerinden sunulmaktadır. Betikle ilgili hiçbir şey bir git etiketi veya commit ile güvence altına alınmamıştır; bu nedenle bugünkü betiği geçen haftakiyle karşılaştıramazsınız ve yapılan değişikliği açıklayan bir geçmiş kaydı bulunmamaktadır. Söz konusu bucket yarın farklı veriler sunabilir ve projedeki hiçbir şey bunu kayıt altına almaz. Çıktıyı doğrudan bash komutuna yönlendirmek, betiğin tek bir satırını bile okumadan makinede çalıştırılması anlamına gelir.

Yükleyici ayrıca bir container yerine doğrudan ana makineye (host) yazma yapar. Python 3.12 sürümünü getirmek ve paket yöneticinizin hakkında hiçbir bilgiye sahip olmadığı bir ortam oluşturmak için uv kullanır; bu nedenle daha sonra kaldırmak manuel bir işlem gerektirir.

İki daha iyi seçenek mevcuttur. Betiği indirin, okuyun ve ardından çalıştırın; bu size otuz saniyenize mal olur: curl -fsSL <url> -o install.sh, ardından less install.sh ve son olarak bash install.sh. Veya bu kılavuzun geri kalanında anlatılan Docker yöntemini kullanın. PyPI paketi (pip install octop), en azından bir sürüme sabitleyebileceğiniz sürüm kontrollü bir yapıdır.

Octop'u Docker Compose ile v0.9.19 sürümüne sabitleyerek dağıtma

v0.9.19 sürümüyle birlikte sunulan Compose dosyası, imajı depodan derler; bu nedenle bu kılavuzda bir sürümü sabitlemek, bir git etiketini (tag) kontrol etmek anlamına gelir. Yayınlanmış imajlar mevcuttur. v0.9.19 ağacı, 15 Temmuz 2026 tarihinde v0.9.8 sürümünde eklenen ve her v* etiketi için bir imaj derleyip Docker Hub'a gönderen bir docker-publish.yml iş akışını halihazırda barındırır. 20 Ekim 2026 itibarıyla proje, GitHub'ın container registry'sine (docker pull ghcr.io/tencentcloud/octop:1.0.2) de yayın yapmaktadır. Kaynak koddan derleme yapmak, bir registry etiketine güvenmek yerine okuduğunuz kodun aynısını derlediğiniz için daha sıkı bir sabitleme yöntemidir. Bu, çoğu self-hosted projenin talep ettiğinden bir adım fazladır; çünkü self-hosted bir AFFiNE çalışma alanı gibi yapılar yayınlanmış bir imaj etiketine sabitlenir ve VPS üzerinde herhangi bir derleme yapmaz. Aşağıdaki klonlama, checkout ve derleme rutini, openGym dağıtım kılavuzunda izlenen yol ile aynıdır; dolayısıyla bunu bir kez kurduysanız, sürecin işleyişine zaten hakimsiniz demektir.

git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19

Dosyanın tanımladığı servis, önemli kısımları tutularak aşağıda özetlenmiştir:

services:
  octop:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: octop:latest
    container_name: octop
    restart: unless-stopped
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
    environment:
      - HOME=/data
      - OCTOP_BIND_HOST=0.0.0.0
      - OCTOP_PORT=${OCTOP_PORT:-8088}
      - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
      - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

build: bloğuna dikkat edin. image: octop:latest, kendi derlemenizin aldığı isimdir, bir registry referansı değildir; bu nedenle buradaki latest, en son neyi derlediyseniz onu ifade eder. Veri yolunu varsayılan değerlere bırakmak yerine açık bir konuma ayarlayın ve ilk başlatmadan önce yönetici hesabına gerçek bir parola atayın. Bunu docker/.env içine yerleştirin:

OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-data

Buradaki bir tuzak, dosyanın geri kalanından daha önemlidir. Compose, docker/.env dosyasını yalnızca YAML içindeki ${...} yer tutucularını doldurmak için okur. O dosyaya eklediğiniz bir anahtar, Compose dosyasındaki environment: altında listelenmediği sürece container içine ulaşmaz. OCTOP_ACCESS_TOKEN_TTL değerini yalnızca .env içine eklerseniz, hiçbir şey olmaz ve sistem sessiz kalır. Alternatif olarak, aynı anahtarları Octop'un başlangıçta yüklediği, mount edilmiş veri dizini içindeki ~/.octop/env dosyasına yazabilirsiniz. Docker Compose'da env dosyaları ve sırlar kılavuzu, bu iki mekanizmanın neden aynı şey olmadığını detaylıca açıklar.

Derleyin ve başlatın:

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/health

Sağlıklı bir örnek, sağlık kontrolüne {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0} benzeri bir JSON nesnesi ile yanıt verir. Başka bir sonuç alırsanız, tarayıcıya dokunmadan önce docker compose -f docker/docker-compose.yml logs -f octop dosyasını okuyun.

Şimdi, az önce derlediğiniz imaja anlamlı bir isim verin; çünkü bir sonraki --build işlemi octop:latest üzerine yazacaktır ve ikisini birbirinden ayırmanız mümkün olmayacaktır:

docker image tag octop:latest octop:0.9.19

İlk başlatma octop init komutunu çalıştırır ve başlangıç kimlik bilgilerini veri birimine yazar:

docker exec -it octop cat /data/.octop/credential.txt

Varsayılan değerler admin / octop şeklindedir ve bunlar yalnızca ilk başlatmada (init) uygulanır. İnsanların sürekli sorduğu bir sorunun arkasındaki mekanizma budur: container bir kez başlatıldıktan sonra OCTOP_DEFAULT_PASSWORD değerini değiştirmek hiçbir şeyi etkilemez, çünkü hesap zaten oluşturulmuştur. Parolayı bunun yerine panel üzerinden değiştirin.

8088 numaralı portu dış dünyaya açmayın

Yukarıdaki ports: satırı, VPS üzerindeki tüm ağ arayüzlerini dinlemeye alır. Container başladığı anda dashboard, varsayılan bir parola ile şifrelenmemiş biçimde internete açık hale gelir. Octop'un kendi OCTOP_BIND_HOST varsayılanı 127.0.0.1 değerindedir; Compose dosyası, sürecin kendi ağ ad alanı dışından gelen trafiği kabul etmesi gerektiği için bu değeri 0.0.0.0 olarak geçersiz kılar. Bu geçersiz kılma işlemi doğrudur. Sizi savunmasız bırakan kısım, portun dış dünyaya açılmasıdır.

docker/docker-compose.yml dosyasındaki ports: satırını, eşleştirme yalnızca loopback üzerinde dinleme yapacak şekilde düzenleyin:

    ports:
      - "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

Bu sorunu basit bir geçersiz kılma (override) dosyası ile çözmeye çalışmayın. Compose, ports listelerini değiştirmek yerine birden fazla dosyadan birleştirir; bu durumda her iki eşleştirme de yayınlanır ve ikincisi bağlanmaya çalışırken hata verir. Eğer orijinal dosyayı değiştirmeden bırakmak istiyorsanız, diziler için belgelenmiş değiştirme yöntemi olan !override etiketini kullanın. Compose'un birden fazla dosyayı nasıl birleştirdiğine dair açıklama, bu birleştirme kurallarının geri kalanını kapsamaktadır.

Loopback adresine bağlanmak, aksi takdirde güvenlik duvarı ile yaşayacağınız bir sorunu da çözer. Docker, yayınlanan port kurallarını ufw tarafından yönetilen zincirlerin önüne, nat tablosuna yazar; bu nedenle ufw deny 8088, yayınlanan bir container portunu engellemez. Docker Engine 28.0.0 veya daha yeni sürümlerde, 127.0.0.1 adresine bağlanan bir port, ufw'nin ne düşündüğünden bağımsız olarak dışarıdan erişilemez durumdadır; bu yüzden bu yöntem, ikinci en iyi seçenek yerine doğru çözümdür. Daha eski Engine sürümleri, aynı L2 segmentindeki ana bilgisayarların (örneğin sağlayıcınızın switch'indeki diğer makineler) localhost'a yayınlanan portlara erişmesine izin verir; bu nedenle docker version komutunu çalıştırın ve sunucu 28'in altında bir sürüm bildiriyorsa yükseltme yapın.

TLS katmanını bir reverse proxy ile öne alın

Caddy, sertifikayı ACME (otomatik sertifika yönetim ortamı) üzerinden kendiliğinden talep ettiği ve WebSockets trafiğini ek bir yapılandırma gerektirmeden proxy üzerinden ilettiği için en kısa yoldur:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx daha fazla dikkat gerektirir, çünkü Octop sohbet akışını bir WebSocket üzerinden iletir:

server {
    listen 443 ssl;
    server_name octop.example.com;

    ssl_certificate     /etc/letsencrypt/live/octop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Buradaki her satır belirli bir işlevi yerine getirir. Sohbet WS /api/agents/{id}/chat/ws üzerinden çalıştığından, proxy_http_version 1.1 ve iki upgrade başlığı olmadan nginx, yükseltme girişimine 400 Bad Request ile yanıt verir: dashboard normal şekilde yüklenir ancak gönderdiğiniz her mesaj, sayfada herhangi bir hata görünmeksizin süresiz olarak askıda kalır. proxy_buffering off önemlidir çünkü insan müdahalesi gerektiren devam etme uç noktası text/event-stream döndürür ve proxy arabelleğinde tutulan SSE (sunucu tarafından gönderilen olaylar), akış halinde iletilmek yerine sonunda tek bir blok halinde ulaşır. proxy_read_timeout uzun süren araç işlemlerini kapsar; zira 60 saniyelik varsayılan değer, bir ajanı görev ortasında keser ve upstream timed out (110: Connection timed out) hatasını loglara düşürür.

JWT kimlik doğrulamasının proxy arkasındaki davranışı

Octop, çerez yerine bearer token ile kimlik doğrulaması yapar. POST /api/auth/login, {access_token, role, user, ...} değerini döndürür ve sonraki çağrılar Authorization: Bearer <access_token> başlığını taşır. Reverse proxy için bu iyi bir haberdir: yanlış yapılandırılabilecek bir çerez etki alanı, Secure bayrağı veya SameSite kuralı yoktur; bu nedenle http://127.0.0.1:8088 üzerinde çalışan bir oturum, https://octop.example.com üzerinde de aynı şekilde davranır.

Gerçek kullanıcıları sisteme dahil etmeden önce bilinmesi gereken iki sonuç vardır.

WebSocket, token bilgisini URL içinde taşır. Uç nokta WS /api/agents/{id}/chat/ws?token=<jwt> şeklindedir, çünkü tarayıcı JavaScript'i bir WebSocket el sıkışmasında Authorization başlığı ayarlayamaz. TLS, bu token bilgisini iletim sırasında korur. Ancak kendi günlük kayıtlarınızdan korumaz: nginx, varsayılan olarak tam istek satırını ve sorgu dizisini access_log dosyasına yazar; bu nedenle gerçek bir kullanıcıya ait geçerli bir token, sunucudaki düz metin bir dosyaya kaydedilir. Günlük kayıtlarında yolu argümanlar olmadan tutun. $uri, sorgu dizisinden arındırılmış normalleştirilmiş yoldur; bu yüzden bunu http bloğuna yerleştirin ve sunucu yapılandırmasından buna referans verin:

log_format octop_noargs '$remote_addr [$time_local] '
                        '"$request_method $uri $server_protocol" '
                        '$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;

Oturum bazlı çıkış işlemi yoktur. OCTOP_ACCESS_TOKEN_TTL varsayılan olarak 86400 değerindedir, bu nedenle bir token girişten sonra 24 saat boyunca geçerli kalır. Bir token'ı geçersiz kılmanın belgelenmiş tek yolu octop admin rotate-jwt-secret işlemidir; bu işlem ~/.octop/secrets/jwt_secret konumunda saklanan imzalama anahtarını döndürür ve mevcut tüm token'ları herkes için anında geçersiz kılar. Dolayısıyla bir kişi ekipten ayrıldığında izlenmesi gereken sıra şudur: kullanıcıyı silin, gizli anahtarı döndürün ve ardından kalan kullanıcılardan tekrar giriş yapmalarını isteyin. Bu süreç ağır geliyorsa, değişkeni environment: listesine ve .env dosyasına eklemeyi unutmadan ömrü kısaltın:

OCTOP_ACCESS_TOKEN_TTL=28800

Brute force saldırıları yönetilmiştir: OCTOP_LOGIN_MAX_ATTEMPTS varsayılan olarak 5 başarısız denemeye ayarlanmıştır ve OCTOP_LOGIN_LOCKOUT_SECONDS değeri 900'dür; bu sayede kilitlenen bir kullanıcı, bozuk bir kurulumla karşılaşmak yerine sadece on beş dakika bekler. Octop'un kendi kullanıcı deposu vardır ve v0.9.19 sürümünde belgelenmiş OIDC desteği bulunmamaktadır. Bu nedenle gerçek bir tek oturum açma (SSO) sistemine ihtiyacınız varsa, önüne bir kimlik doğrulama proxy'si koymanız gerekir; kendi sunucunuzda barındırdığınız bir Authentik sunucusu bunun içindir.

Octop'u bir model arka ucuna yönlendirme

Sağlayıcılar panel üzerinden her bir aracı (agent) için ayrı ayrı yapılandırılır ve octop provider list size nelerin ayarlandığını gösterir. Octop, OpenAI uyumlu API'ler, DashScope (Qwen) ve Ollama için hazır ayarlar sunar; kimlik bilgileri ise kendi SQLite veritabanınızdaki providers tablosunda saklanır. Yapılan seçim, ödeyeceğiniz ücreti ve sunucudan dışarı çıkan veriyi belirler.

Ollama ile yerel bir model. Hiçbir veri sunucudan dışarı çıkmaz ve token yerine RAM harcarsınız. İnsanların gözünden kaçan bağlantı detayı şudur: Bir container, 127.0.0.1:11434 adresindeki ana makine (host) Ollama'sına erişemez; çünkü bu adres container'ın kendi loopback arayüzüdür. Servise bir host gateway girişi ekleyin:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Ardından sağlayıcı temel URL'sini, Ollama'nın OpenAI uyumlu yolu olan http://host.docker.internal:11434/v1 olarak ayarlayın. API anahtarı alanına boş olmayan herhangi bir karakter dizisi girin; Ollama bunu görmezden gelir ancak OpenAI istemcileri boş anahtar gönderilmesini reddeder. Bunun çalışması için Ollama'nın yalnızca loopback üzerinde değil, dışarıdan da dinleme yapması gerekir; bu da systemd birim dosyasında OLLAMA_HOST=0.0.0.0:11434 ayarını gerektirir. Buradaki riskli nokta şudur: Ollama kimlik doğrulama içermez, bu nedenle herkese açık bir IP üzerinde 11434 numaralı portu açık bırakmak, tarama yapan herkesin ücretsiz model sunucunuza erişmesine neden olur. Yalnızca Docker'ın özel IP aralığı olan sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp adresine izin verin ve geri kalanını engelleyin. VPS üzerinde Ollama çalıştırma rehberi model boyutlandırmayı, Ollama ve vLLM karşılaştırması ise Ollama'nın ne zaman yetersiz kalacağını açıklar.

Yerel modellerle ilgili bir uyarı daha; bu durum Octop'ta bir hata gibi görünse de aslında değildir. Aracılar araçları (tools) çağırarak çalışır; sistem istemi (system prompt), araç tanımları ve geçmiş birleştiğinde ortaya büyük bir istem çıkar. Ollama, modelleri varsayılan olarak mütevazı bir bağlam penceresi (context window) ile sunar; bu nedenle araç tanımlarının bulunduğu istemin baş kısmı pencerenin dışında kalır. Model daha sonra araç çağırmayı bırakır veya var olmayan araçlar uydurur. num_ctx değerini 16k veya 32k seviyesine yükseltin ve fonksiyon çağırma konusunda gerçekten başarılı bir model seçin. Yanıtın cümle ortasında kesilmesi ise farklı bir sorundur ve num_predict ayarı ile ilgilidir; bu nedenle yanıtlar kesik geliyorsa, aracı suçlamadan önce num_predict değerinin nerede ayarlandığını ve done_reason değerinin ne olduğunu kontrol etmek faydalıdır. Kısa bir liste yerine belirli bir adaydan başlamayı tercih ederseniz, Nemotron 3.5 Lightning denemeye değerdir; ilgili yazı, çekilecek etiketi, ihtiyaç duyulan RAM miktarını ve yalnızca CPU ile çalışıp çalışmayacağını belirtir.

Self-hosted bir ağ geçidi. Octop ile diğer her şey arasına self-hosted bir LiteLLM ağ geçidi yerleştirirseniz; tek bir temel URL, kullanıcı başına ayrı anahtar, harcama limitleri ve tek bir günlük kaydı elde edersiniz. Ayrıca Octop üzerinde hiçbir şeyi düzenlemeden arka plandaki modeli değiştirebilirsiniz.

Ücretli bir API. En yüksek kaliteyi sunar ancak dürüst bir takas gerektirir: Konuşma içeriği sunucunuzdan çıkar ve sağlayıcıya ulaşır; bu da self-hosting amacının büyük bir kısmını devre dışı bırakır. Anahtar, Compose dosyası tarafından zaten aktarılan OPENAI_API_KEY değişkeni olarak docker/.env içine girilir.

Hangisini seçerseniz seçin, Compose dosyası OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY ve LANGFUSE_BASE_URL değişkenlerini de taşır; böylece izleme verilerini kendi Langfuse örneğinize gönderebilir ve sohbet penceresinden tahmin yürütmek yerine aracıların gerçekte ne yaptığını görebilirsiniz.

Kullanıcılar, roller ve paylaşılan aracı kütüphanesi

İlk kurulumda oluşturulan yönetici hesabı, diğer hesapları oluşturur ve yönetir. Her kullanıcı kendi aracısına, çalışma alanına ve kimlik bilgilerine sahiptir; bu izolasyon, tarayıcıda tutulan token ile sağlanır. Bunun yanı sıra, herkesin kullanabileceği paylaşılan bir yetenek ve alt aracı havuzu bulunur; bu özellik, sistemin bir aile için kullanılmasını değerli kılan unsurdur: Bir kişi iyi bir araştırma aracısı oluşturduğunda, diğerlerinin bunu tekrar oluşturmasına gerek kalmaz.

Araç kullanımı konusunda dikkatli olun. Octop, araç onayı ve shell komutu koruma mekanizmaları sunar; bunlar gerçek özelliklerdir ancak shell komutlarını çalıştıran bir aracı, bu komutları veri biriminizin (data volume) mount edildiği Octop container'ı içerisinde yürütür. Koruma mekanizmaları, dikkatsizce yazılmış bir istemin (prompt) verebileceği zararı azaltır. Bunlar bir sandbox sınırı değildir; bu nedenle, shell erişimi vermeyeceğiniz hiç kimse için araç onayını devre dışı bırakmayın. Eğer bu sistemi diğer seçeneklerle kıyaslıyorsanız, self-hosted yapay zeka aracıları karşılaştırması her birinin bu durumu nasıl yönettiğini göstermektedir.

Bu kadar hızlı sürüm çıkaran bir projeyi yükseltmek

[
  {
    "version": "v0.9.16",
    "days_since_previous_release": 2
  },
  {
    "version": "v0.9.17",
    "days_since_previous_release": 3
  },
  {
    "version": "v0.9.18",
    "days_since_previous_release": 1
  },
  {
    "version": "v0.9.19",
    "days_since_previous_release": 3
  }
]

Bunlar, 7 Ağustos 2026 itibarıyla depodaki etiket tarihleridir. Dokuz gün içinde 4 adet etiketli sürüm yayınlanmıştır; sürümler arası süre 1 güne kadar düşmüş ve v0.9.19 sürümü, bir önceki etiketten 3 gün sonra gelmiştir. Bu sürüm sıklığı proje için olumlu bir işaret olsa da latest çalıştırmak için kötü bir nedendir. Değişiklikleri uygulamadan önce mutlaka okuyun:

cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"

Proje, v1.0.2b9 gibi beta sürümlerini kararlı sürümlerle birlikte etiketlediği için, checkout yapmadan önce $NEW_TAG içerisinde gerçekte ne olduğunu kontrol edin. 20 Ekim 2026 itibarıyla en yeni etiket, 18 Ekim 2026 tarihinde yayınlanan kararlı v1.0.2 sürümüdür. v0.9.19 sürümünden yapılan geçiş, 14 Eylül 2026 tarihli v1.0.0 sürümünü de kapsadığı için ilgili günlük oldukça uzundur ve dikkatle incelenmelidir.

Her seferinde önce yedek alın; çünkü veritabanı migrasyonları başlangıçta çalışır ve bu kadar hızlı sürüm çıkaran bir projede başarısız olan bir migrasyonu düzeltmek sizin sorumluluğunuzdadır:

docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml start

Ardından yeni etiketi checkout yapın ve docker compose -f docker/docker-compose.yml up -d --build ile yeniden derleyin. Bir sorun çıkarsa, eski etikete dönüp yeniden derlemek kodu geri getirir ancak veritabanını yalnızca tarball yedeği ile geri yükleyebilirsiniz.

Bu tarball dosyası octop.db, config.json, JWT imzalama anahtarı ve credential.txt verilerini içerir; bu nedenle sunucunun kendisi kadar hassastır. Dosya izinlerini 600 modunda tutun ve bir kopyasını sunucu dışında saklayın. Daha büyük kurulumlar için proje, SQLite yerine pgvector ile PostgreSQL çalıştıran docker/docker-compose.postgres.yml sürümünü de sunmaktadır.

Hata modları ve karşılaşacağınız dizgeler

Sistem sağlık kontrolü yanıt vermiyor. curl http://127.0.0.1:8088/api/health asılı kalıyor veya bağlantıyı reddediyor. docker compose -f docker/docker-compose.yml logs -f octop kısmını okuyun. İlk başlatma sırasında kapanan bir container genellikle veri dizinine yazma iznine sahip değildir; bu nedenle OCTOP_DATA olarak ayarladığınız dizinin sahiplik izinlerini kontrol edin.

Panel yükleniyor ancak sohbet yanıt vermiyor. Sayfada hata yok ancak yanıt da gelmiyor. Tarayıcı konsolunu açın ve wss://octop.example.com/api/agents/.../chat/ws adresine yapılan başarısız bağlantıyı arayın. Proxy, yükseltme (upgrade) isteğini iletmiyor. proxy_http_version 1.1 ayarını ve Upgrade ile Connection başlıklarını ekleyin.

Tüm yanıt birkaç saniye gecikmeli olarak tek seferde geliyor. Akış (streaming) çalışıyor ancak arabelleğe alma (buffering) aktif. proxy_buffering off ayarını yapılandırın.

bind: address already in use. 8088 numaralı port zaten kullanımda. sudo ss -tlnp | grep 8088 komutu bu portu kullanan süreci listeler. Bu hata, orijinal dosyayı düzenlemek yerine geçersiz kılma (override) dosyasına ikinci bir ports girdisi eklediğinizde de oluşur.

Doğru parola reddediliyor. Beş hatalı deneme, 900 saniyelik bir kilitlenmeyi tetikler. Yeniden kurulum yapmak yerine sürenin dolmasını bekleyin.

.env içindeki yeni parola etkisiz kaldı. Bu kimlik bilgileri yalnızca ilk başlatma sırasında geçerlidir. Parolayı panel üzerinden değiştirin.

Ajan yanıt veriyor ancak hiçbir aracı çalıştırmıyor. Bu durum neredeyse her zaman yerel model kaynaklıdır: bağlam penceresi (context window) araç tanımları için çok küçüktür veya model fonksiyon çağırma konusunda yetersizdir. num_ctx değerini yükseltin ve araç kullanımı için optimize edilmiş bir model deneyin.

FAQ

Octop, Open WebUI'nin yerini tutar mı?

Yalnızca sunduğu ek özelliklere ihtiyacınız varsa tutar. Open WebUI, bir modelin önünde yer alan bir sohbet arayüzüdür ve bu işi tek bir kullanıcı veya güvene dayalı bir hane halkı için gayet iyi yapar. Octop ise yönetici rolüne sahip hesaplar, kullanıcı bazlı çalışma alanları ve kimlik bilgileri ile değiştirilebilir uzman ajan kütüphanesi ekler; böylece birden fazla kişi tek bir geçmişi paylaşmadan aynı sunucuyu kullanabilir. Tek bir hesap sizin için yeterliyse, Open WebUI çok daha basit ve olgun bir tercihtir.

Neden Octop curl kurulum betiğini kullanmamalıyım?

Betik, depodan değil bir Tencent Cloud Object Storage bucket üzerinden sunulduğu için herhangi bir git etiketi veya commit ile ilişkilendirilmemiştir. Bugün yaptığı işle geçen hafta yaptığı işi karşılaştıramazsınız; ayrıca betiği doğrudan bash komutuna yönlendirmek, içeriğini okumadan çalıştırmanıza neden olur. Ayrıca betik, paket yöneticinizin dışında, kendi Python 3.12 ortamıyla ana makineye kurulum yapar. Betiği önce indirin ve okuyun ya da kontrol edilmiş bir etiket üzerinden Docker Compose ile dağıtın.

Octop, ücretli bir API yerine yerel bir model kullanabilir mi?

Evet. Octop, OpenAI uyumlu API'leri destekler ve bir Ollama ön ayarı ile gelir. http://host.docker.internal:11434/v1 adresine yönlendirme yapmak için konteynere extra_hosts: ["host.docker.internal:host-gateway"] eklemeniz ve ana makinede OLLAMA_HOST=0.0.0.0:11434 ayarını yapmanız yeterlidir. Ollama'nın kendi kimlik doğrulama mekanizması bulunmadığından, güvenlik duvarı üzerinden 11434 numaralı portu Docker'ın adres aralığına kısıtlayın. Ollama'nın num_ctx değerini 16k veya üzerine çıkarmayı planlayın; çünkü araç tanımlarını içeren ajan istemleri varsayılan bağlam penceresini aşar ve model araç çağırmayı durdurur.

Reverse proxy kullanmam gerekiyor mu, yoksa 8088 numaralı portu açabilir miyim?

Proxy kullanmanız gerekir. Octop ile gelen Compose dosyası, 8088 numaralı portu TLS olmadan tüm arayüzlere açar; bu da parolaların ve taşıyıcı belirteçlerin (bearer tokens) internet üzerinden açık metin olarak iletilmesine neden olur. Yayınlanan portu 127.0.0.1:8088:8088 olarak değiştirin ve önüne sertifikalı bir Caddy veya nginx yerleştirin. nginx kullanıyorsanız, WebSocket yükseltme başlıklarını iletin ve proxy_buffering off ayarını yapın; aksi takdirde sayfa yüklenir ancak sohbet yanıt vermez.

Octop üretime hazır mı?

Ağustos 2026 itibarıyla 1.0 öncesi sürümdeydi ve haftada birkaç etiketli sürüm yayınlıyordu. 14 Eylül 2026'da v1.0.0 etiketini aldı, ardından 18 Ekim 2026'daki kararlı v1.0.2 sürümünden önce bir dizi 1.0.2 beta etiketi yayınladı. Geliştirme hızı hala yüksek olduğundan, ürünü yerleşik bir yapıdan ziyade gelecek vadeden bir çözüm olarak değerlendirin. Belirli bir etiketi sabitleyip, her yükseltme öncesinde commit kayıtlarını okuyup her yeniden oluşturma işleminden önce veri biriminin yedeğini alırsanız, bir aile veya küçük bir kurum içi ekip için kullanılabilir durumdadır. Henüz latest üzerinde çalıştırmayın ve içine müşteri verisi eklemeyin.