تحریر: Matt Connor 2026-10-20

Octop کو VPS پر self-host کرنے کا مکمل طریقہ

Docker Compose کے ساتھ Octop v0.9.19 deploy کریں، ہر صارف کے لیے الگ workspace، OpenAI-compatible backend اور TLS حاصل کریں، اور curl installer سے گریز کی وجہ جانیں۔

Octop کیا ہے، اور اسے self-host کیوں کرنا چاہیے

Octop گھر یا چھوٹی ٹیم کے لیے self-hosted AI assistant ہے۔ سادہ chat front end کے بجائے Octop کو self-host کرنے کی وجہ یہ ہے کہ یہ صارفین کو ایک دوسرے سے الگ رکھتا ہے۔ Open WebUI آپ کو model کے سامنے browser interface فراہم کرتا ہے۔ Octop میں admin role والے accounts، ہر صارف کے لیے private workspace اور credentials کا الگ مجموعہ، اور specialist agents کی library شامل ہے جن کے درمیان ہر صارف کام کے لحاظ سے تبدیل ہو سکتا ہے۔ یہی فرق ایک VPS کو ایک صارف کے بجائے پانچ افراد کے لیے قابلِ استعمال بناتا ہے۔

یہ project github.com/TencentCloud/Octop پر موجود ہے۔ یہ ایک ہی process ہے جو web dashboard، command line interface، chat channels (Feishu, DingTalk, QQ, Discord, WeCom) اور scheduled jobs فراہم کرتا ہے۔ یہ سب ~/.octop/ کے تحت موجود ایک SQLite database سے چلتے ہیں۔ ذیل کی تمام معلومات tag v0.9.19 کے مطابق ہیں، جو 5 August 2026 کو release ہوا تھا۔ اگر آپ ابھی platforms کے درمیان فیصلہ کر رہے ہیں تو VPS پر چلائے جا سکنے والے Open WebUI alternatives کا موازنہ وسیع تر منظرنامہ پیش کرتا ہے۔

اس پر وقت صرف کرنے سے پہلے ایک بات واضح ہونی چاہیے۔ یہ guide لکھے جانے کے وقت Octop pre-1.0 software تھا، جو ایک vendor کی GitHub organisation سے published تھا، اور August 2026 تک اس کے تقریباً 900 stars تھے۔ اس کے بعد اس نے 14 September 2026 کو v1.0.0 tag کیا، اور 20 October 2026 تک newest tag v1.0.2 ہے۔ یہ stable release 18 October 2026 کو 1.0.2 beta tags کے سلسلے کے بعد published ہوئی، جبکہ repository کے تقریباً 10,400 stars ہیں۔ ذیل کے steps v0.9.19 کے مطابق لکھے گئے تھے اور 1.x پر دوبارہ test نہیں کیے گئے۔ یہ project تیزی سے تبدیل ہوتا ہے، اور version numbers اس کی تصدیق کرتے ہیں۔ یہاں stable upgrade path کی کوئی ضمانت نہیں ہے۔ کسی tag کو pin کریں، changelog پڑھیں، اور backups رکھیں۔

شروع کرنے سے پہلے درکار چیزیں

Ubuntu 24.04 چلانے والا VPS، جس پر Docker Engine اور Compose plugin نصب ہو۔ Compose سے نئے ہیں؟ VPS کے لیے Docker Compose کی بنیادی باتوں سے آغاز کریں۔
git، کیونکہ آپ image pull کرنے کے بجائے release tag check out کریں گے۔
VPS کی طرف اشارہ کرنے والا domain name، کیونکہ آپ کو اس کے سامنے TLS (transport layer security) درکار ہے۔
ایسا model backend جو OpenAI API کے ساتھ کام کرتا ہو: مقامی Ollama، self-hosted gateway، یا paid key۔

Octop خود کم وسائل استعمال کرتا ہے۔ یہ ایک Python process اور SQLite file ہے۔ زیادہ وسائل model backend استعمال کرتا ہے۔ اس لیے اگر آپ model اسی machine پر چلانے کا ارادہ رکھتے ہیں تو machine کے وسائل model کے مطابق مقرر کریں۔

ہم curl installer کی سفارش کیوں نہیں کرتے

README میں سطر پر مشتمل installation دی گئی ہے:

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

ہم ایسے server پر اس کی سفارش نہیں کرتے جس کی حفاظت آپ کے لیے اہم ہو۔ اس کی ایک واضح وجہ ہے: یہ script repository میں موجود نہیں ہے۔ اسے Tencent Cloud Object Storage bucket سے serve کیا جاتا ہے۔ git tag یا commit اس script کے کسی حصے کا احاطہ نہیں کرتا۔ اس لیے آپ آج کی script کا پچھلے ہفتے کی script سے diff نہیں دیکھ سکتے، اور نہ ہی ایسی history موجود ہے جو کسی تبدیلی کی وجہ بتائے۔ bucket کل مختلف bytes serve کر سکتی ہے، اور project میں اس کا کوئی record موجود نہیں ہوگا۔ نتیجہ براہ راست bash میں pipe کرنے کا مطلب یہ بھی ہے کہ machine اس script کو چلانے سے پہلے آپ کو اس کی ایک سطر بھی پڑھنے کا موقع نہیں دیتی۔

installer host پر لکھتا ہے، container کے اندر نہیں۔ یہ uv استعمال کرکے Python 3.12 fetch کرتا ہے اور ایسا environment بناتا ہے جس کے بارے میں آپ کا package manager کچھ نہیں جانتا۔ بعد میں اسے ہٹانا manual کام بن جاتا ہے۔

دو بہتر options موجود ہیں۔ پہلے script fetch کریں، اسے پڑھیں، پھر run کریں۔ اس میں صرف تیس seconds لگتے ہیں: curl -fsSL <url> -o install.sh، پھر less install.sh، پھر bash install.sh۔ یا Docker استعمال کریں، جس کی تفصیل اس guide کے باقی حصے میں ہے۔ PyPI package (pip install octop) کم از کم ایک versioned artifact ہے، جسے آپ کسی release کے ساتھ pin کر سکتے ہیں۔

Docker Compose کے ساتھ Octop تعینات کریں، v0.9.19 پر pinned

v0.9.19 کے ساتھ فراہم کی گئی Compose فائل image کو repository سے build کرتی ہے، اس لیے اس guide میں version pin کرنے کا مطلب git tag کو checkout کرنا ہے۔ Published images بھی موجود ہیں۔ v0.9.19 کے tree میں پہلے سے docker-publish.yml workflow شامل ہے، جو 15 July 2026 کو v0.9.8 میں شامل کیا گیا تھا۔ یہ workflow image build کرتا ہے اور ہر v* tag کے لیے اسے Docker Hub پر push کرتا ہے۔ 20 October 2026 تک project GitHub کے container registry (docker pull ghcr.io/tencentcloud/octop:1.0.2) پر بھی publish کرتا ہے۔ پھر بھی checked-out tag سے build کرنا زیادہ مضبوط pin ہے، کیونکہ آپ عین وہی code compile کرتے ہیں جسے آپ نے پڑھا ہے، بجائے اس کے کہ registry tag پر اعتماد کریں۔ یہ زیادہ تر self-hosted projects کے طریقے سے ایک قدم آگے ہے، کیونکہ self-hosted AFFiNE workspace جیسی چیز published image tag کو pin کرتی ہے اور آپ کے VPS پر کچھ بھی build نہیں کرتی۔ ذیل میں clone، checkout اور build کا routine وہی ہے جسے openGym deployment guide مرحلہ وار دکھاتی ہے۔ اس لیے اگر آپ نے اسے ایک بار set up کیا ہے تو اس کا طریقہ پہلے سے جانتے ہیں۔

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

یہ وہ service ہے جسے فائل define کرتی ہے۔ یہاں صرف متعلقہ حصے دکھائے گئے ہیں:

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: block پر توجہ دیں۔ image: octop:latest آپ کی اپنی build کا نام ہے، registry reference نہیں۔ اس لیے یہاں latest سے مراد وہ code ہے جسے آپ نے سب سے حال میں compile کیا ہے۔ Data path کو واضح جگہ پر set کریں، اسے default پر نہ چھوڑیں، اور پہلی boot سے پہلے admin account کے لیے حقیقی password مقرر کریں۔ اسے docker/.env میں رکھیں:

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

یہاں ایک اہم trap ہے جو باقی فائل سے زیادہ توجہ کا مستحق ہے۔ Compose docker/.env کو صرف YAML میں موجود ${...} placeholders کی interpolation کے لیے پڑھتا ہے۔ اس فائل میں شامل کیا گیا key container تک نہیں پہنچتا، جب تک اسے Compose فائل میں environment: کے تحت بھی درج نہ کیا جائے۔ صرف .env میں OCTOP_ACCESS_TOKEN_TTL شامل کرنے سے کچھ بھی نہیں ہوتا، اور کوئی error بھی ظاہر نہیں ہوتی۔ متبادل یہ ہے کہ mounted data directory کے اندر ~/.octop/env میں وہی keys لکھی جائیں۔ Octop startup کے وقت اسے load کرتا ہے۔ Docker Compose میں env files اور secrets کی guide وضاحت کرتی ہے کہ یہ دونوں mechanisms ایک جیسی کیوں نہیں ہیں۔

اسے build اور start کریں:

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

صحتمند instance health check کے جواب میں {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0} جیسا JSON object دیتا ہے۔ اس کے علاوہ کچھ ملے تو browser کھولنے سے پہلے docker compose -f docker/docker-compose.yml logs -f octop پڑھیں۔

اب ابھی build کی گئی image کو بامعنی نام دیں، کیونکہ اگلا --build، octop:latest کو overwrite کر دے گا اور آپ کے پاس دونوں میں فرق کرنے کا کوئی طریقہ نہیں رہے گا:

docker image tag octop:latest octop:0.9.19

پہلی boot octop init چلاتی ہے اور ابتدائی credentials data volume میں لکھتی ہے:

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

Defaults admin / octop ہیں، اور یہ صرف پہلی init پر لاگو ہوتے ہیں۔ اسی وجہ سے لوگ اکثر پوچھتے ہیں کہ container کے ایک بار start ہونے کے بعد OCTOP_DEFAULT_PASSWORD تبدیل کرنے سے کچھ کیوں نہیں بدلتا۔ اس وقت تک account پہلے ہی بن چکا ہوتا ہے۔ Password dashboard سے تبدیل کریں۔

8088 پورٹ public نہ کریں

اوپر موجود ports: لائن VPS پر ہر interface سے bind ہوتی ہے۔ Container شروع ہوتے ہی dashboard cleartext میں public internet پر دستیاب ہو جاتا ہے، اور اس پر default password ہوتا ہے۔ Octop کا اپنا OCTOP_BIND_HOST default، 127.0.0.1 ہے؛ Compose file اسے 0.0.0.0 سے override کرتی ہے، کیونکہ process کو اپنی network namespace کے باہر سے آنے والا traffic قبول کرنا ہوتا ہے۔ یہ override درست ہے۔ مسئلہ published port کی وجہ سے پیدا ہوتا ہے، جو سروس کو public طور پر expose کرتا ہے۔

docker/docker-compose.yml میں موجود ports: لائن کو edit کریں، تاکہ mapping صرف loopback پر listen کرے:

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

اسے صرف plain override file سے درست کرنے کی کوشش نہ کریں۔ Compose متعدد files کی ports lists کو replace کرنے کے بجائے concatenate کرتا ہے۔ اس طرح دونوں mappings publish ہو جاتی ہیں اور دوسری mapping bind ہونے میں ناکام رہتی ہے۔ اگر آپ upstream file کو تبدیل نہیں کرنا چاہتے تو sequence پر !override tag استعمال کریں۔ یہ append کرنے کے بجائے replace کرنے کا documented طریقہ ہے۔ Compose کے متعدد files کو merge کرنے کے طریقے کی وضاحت میں merge rules کی باقی تفصیل موجود ہے۔

Loopback پر bind کرنے سے firewall کا ایک مسئلہ بھی حل ہو جاتا ہے۔ Docker اپنی published-port rules، ufw کے زیر انتظام chains سے پہلے nat table میں لکھتا ہے۔ اس لیے ufw deny 8088 published container port کو نہیں روکتا۔ Docker Engine 28.0.0 یا اس کے بعد کے versions میں 127.0.0.1 سے bound port بیرونی hosts سے reachable نہیں ہوتا، چاہے ufw کی configuration کچھ بھی ہو۔ اسی لیے یہ second-best حل کے بجائے درست fix ہے۔ پرانے Engine releases میں اسی L2 segment پر موجود hosts، مثلاً provider کے switch سے منسلک دوسری machines، localhost پر publish کی گئی ports تک پہنچ سکتی تھیں۔ اس لیے docker version چلائیں اور اگر server 28 سے کم version report کرے تو upgrade کریں۔

ریورس پراکسی کے ذریعے TLS سامنے رکھیں

Caddy سب سے مختصر راستہ ہے، کیونکہ یہ خود ACME (خودکار certificate management environment) کے ذریعے certificate حاصل کرتا ہے اور ہدایت دیے بغیر WebSockets کو پراکسی کرتا ہے:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx کے لیے زیادہ احتیاط درکار ہے، کیونکہ Octop chat کو WebSocket کے ذریعے stream کرتا ہے:

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;
    }
}

اس میں ہر سطر ایک مخصوص کام کرتی ہے۔ Chat WS /api/agents/{id}/chat/ws کے ذریعے چلتی ہے، اس لیے proxy_http_version 1.1 اور دونوں upgrade headers کے بغیر nginx upgrade کی کوشش کا جواب 400 Bad Request سے دیتا ہے: dashboard معمول کے مطابق load ہوتا ہے، لیکن آپ کا بھیجا ہوا ہر message صفحے پر کسی error کے بغیر ہمیشہ رکا رہتا ہے۔ proxy_buffering off اہم ہے، کیونکہ human-in-the-loop resume endpoint text/event-stream واپس کرتا ہے، اور proxy buffer میں رکے ہوئے SSE (server-sent events) آخر میں ایک ہی مجموعے کی صورت میں موصول ہوتے ہیں، streaming کے طور پر نہیں۔ proxy_read_timeout طویل tool runs کا احاطہ کرتا ہے، کیونکہ 60 second کی default حد agent کو task کے دوران روک دیتی ہے اور logs میں upstream timed out (110: Connection timed out) درج ہو جاتا ہے۔

پراکسی کے پیچھے JWT authentication کیسے کام کرتی ہے

Octop bearer token کے ذریعے authentication کرتا ہے، cookie کے ذریعے نہیں۔ POST /api/auth/login، {access_token, role, user, ...} واپس کرتا ہے، اور بعد کی requests میں Authorization: Bearer <access_token> شامل ہوتا ہے۔ Reverse proxy کے لیے یہ اچھی بات ہے: cookie domain، Secure flag، یا SameSite rule موجود نہیں جسے غلط configure کیا جا سکے۔ اس لیے http://127.0.0.1:8088 پر کام کرنے والا session، https://octop.example.com پر بھی اسی طرح کام کرتا ہے۔

حقیقی users کو شامل کرنے سے پہلے دو نتائج سمجھ لینا ضروری ہے۔

WebSocket، token کو URL میں بھیجتا ہے۔ Endpoint WS /api/agents/{id}/chat/ws?token=<jwt> ہے، کیونکہ browser JavaScript، WebSocket handshake میں Authorization header set نہیں کر سکتی۔ TLS اس token کو transit کے دوران محفوظ رکھتا ہے۔ لیکن یہ token آپ کے اپنے logs سے محفوظ نہیں رہتا: nginx، default طور پر query string سمیت مکمل request line کو access_log میں لکھتا ہے۔ اس طرح حقیقی user کا فعال token server پر plaintext file میں محفوظ ہو جاتا ہے۔ Arguments کے بغیر path کو log کریں۔ $uri وہ normalised path ہے جس سے query string پہلے ہی حذف ہو چکی ہے۔ اسے http block میں شامل کریں اور server سے reference کریں:

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;

ہر session کے لیے الگ logout موجود نہیں ہے۔ OCTOP_ACCESS_TOKEN_TTL کی default value 86400 ہے، اس لیے login کے بعد token 24 گھنٹے تک valid رہتا ہے۔ کسی token کو invalidate کرنے کا واحد documented طریقہ octop admin rotate-jwt-secret ہے۔ یہ ~/.octop/secrets/jwt_secret میں محفوظ signing key کو rotate کرتا ہے اور تمام موجودہ tokens کو فوراً invalidate کر دیتا ہے، یعنی سب users کے لیے۔ اس لیے جب کوئی شخص team چھوڑے تو ترتیب یہ ہونی چاہیے: user delete کریں، secret rotate کریں، پھر باقی users کو دوبارہ login کرنے کو کہیں۔ اگر یہ طریقہ زیادہ سخت لگے تو lifetime کم کریں، لیکن variable کو environment: list کے ساتھ ساتھ .env میں بھی شامل کرنا یاد رکھیں:

OCTOP_ACCESS_TOKEN_TTL=28800

Brute force سے نمٹنے کا انتظام موجود ہے: OCTOP_LOGIN_MAX_ATTEMPTS کی default value 5 failures اور OCTOP_LOGIN_LOCKOUT_SECONDS کی 900 ہے۔ اس لیے locked-out user کو broken install سمجھنے کے بجائے صرف پندرہ منٹ انتظار کرنا پڑتا ہے۔ Octop کا اپنا user store ہے، اور v0.9.19 میں OIDC support documented نہیں ہے۔ اگر آپ کو حقیقی single sign-on درکار ہو تو اس کے سامنے authenticating proxy رکھیں۔ اسی مقصد کے لیے self-hosted Authentik server استعمال کیا جاتا ہے۔

ماڈل backend کی طرف Octop کو point کریں

Providers ہر agent کے لیے dashboard میں configure کیے جاتے ہیں، اور octop provider list سے معلوم ہوتا ہے کہ کیا set ہے۔ Octop، OpenAI-compatible APIs، DashScope (Qwen) اور Ollama کے لیے presets فراہم کرتا ہے، جبکہ credentials آپ کے اپنے SQLite database کی providers table میں محفوظ ہوتے ہیں۔ انتخاب سے یہ طے ہوتا ہے کہ آپ کی لاگت کتنی ہوگی اور server سے کیا data باہر جائے گا۔

Ollama کے ساتھ local model۔ کچھ بھی server سے باہر نہیں جاتا، اور tokens کے بجائے RAM استعمال ہوتی ہے۔ یہاں ایک wiring detail اکثر مسئلہ بنتی ہے: container، host کے Ollama تک 127.0.0.1:11434 پر نہیں پہنچ سکتا، کیونکہ یہ address container کا اپنا loopback ہے۔ Service میں host gateway entry شامل کریں:

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

پھر provider کا base URL http://host.docker.internal:11434/v1 پر set کریں، جو Ollama کا OpenAI-compatible path ہے۔ API key field میں کوئی بھی non-empty string درج کریں، کیونکہ Ollama اسے نظرانداز کرتا ہے، لیکن OpenAI clients خالی key بھیجنے سے انکار کرتے ہیں۔ اس کے لیے Ollama کا loopback سے آگے listen کرنا بھی ضروری ہے، یعنی اس کی systemd unit میں OLLAMA_HOST=0.0.0.0:11434 شامل ہونا چاہیے۔ یہی خطرناک حصہ ہے: Ollama میں authentication نہیں ہے، اس لیے public IP پر کھلا ہوا 11434 ہر اس شخص کے لیے مفت model server بن جاتا ہے جو اسے پہلے scan کرے۔ صرف Docker کی private range، sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp، کی اجازت دیں اور باقی تمام traffic کو deny کریں۔ VPS پر Ollama چلانا model sizing کا احاطہ کرتا ہے، جبکہ Ollama اور vLLM کا موازنہ بتاتا ہے کہ Ollama کب موزوں server نہیں رہتا۔

Local model کے بارے میں ایک اور warning ضروری ہے، کیونکہ یہ Octop میں bug جیسا نظر آتا ہے، حالانکہ ایسا نہیں ہے۔ Agents tools کو call کر کے کام کرتے ہیں، اور system prompt، tool definitions اور history مل کر ایک بڑا prompt بناتے ہیں۔ Ollama models کو نسبتاً مختصر default context window کے ساتھ serve کرتا ہے، اس لیے prompt کا ابتدائی حصہ، جہاں tool definitions موجود ہوتی ہیں، window سے باہر ہو جاتا ہے۔ اس کے بعد model tools call کرنا بند کر دیتا ہے یا ایسے tools بنا لیتا ہے جو موجود ہی نہیں ہوتے۔ num_ctx کو 16k یا 32k تک بڑھائیں اور ایسا model منتخب کریں جو function calling میں واقعی اچھا ہو۔ جو reply درمیان میں رک جائے، وہ اس کے برعکس مسئلہ اور الگ setting، num_predict، سے متعلق ہے۔ اس لیے اگر answers truncated واپس آئیں تو agent کو ذمہ دار ٹھہرانے سے پہلے دیکھیں کہ num_predict کہاں set ہے اور done_reason کیا بتاتا ہے۔ اگر آپ shortlist کے بجائے کسی مخصوص candidate سے شروع کرنا چاہتے ہیں تو Nemotron 3.5 Lightning آزمانے کے قابل ہے۔ اس تحریر میں pull کرنے کے لیے exact tag، مطلوبہ RAM اور یہ بھی بتایا گیا ہے کہ CPU-only کارکردگی برقرار رکھتا ہے یا نہیں۔

Self-hosted gateway۔ Octop اور باقی تمام سروسز کے درمیان self-hosted LiteLLM gateway رکھیں۔ اس سے ایک base URL، ہر user کے لیے الگ key، spend limits اور ایک مرکزی log ملتا ہے۔ آپ Octop میں کچھ تبدیل کیے بغیر اس gateway کے پیچھے model بھی تبدیل کر سکتے ہیں۔

Paid API۔ معیار عموماً بہترین ہوتا ہے، لیکن tradeoff واضح ہے: conversation content آپ کے server سے باہر جا کر provider تک پہنچتا ہے، جبکہ self-hosting کا بنیادی مقصد ہی اس data کو server کے اندر رکھنا تھا۔ Key docker/.env میں OPENAI_API_KEY کے طور پر درج کی جاتی ہے، اور Compose file اسے پہلے ہی pass through کرتی ہے۔

آپ جو بھی انتخاب کریں، Compose file OCTOP_LANGFUSE_ENABLED، LANGFUSE_PUBLIC_KEY، LANGFUSE_SECRET_KEY اور LANGFUSE_BASE_URL بھی منتقل کرتی ہے۔ اس سے آپ اپنے Langfuse instance کو traces بھیج سکتے ہیں اور chat window سے اندازہ لگانے کے بجائے دیکھ سکتے ہیں کہ agents حقیقت میں کیا کر رہے ہیں۔

صارفین، کردار، اور مشترکہ agent library

پہلے boot کے دوران بنایا گیا admin account دوسرے صارفین کو بناتا اور manage کرتا ہے۔ ہر صارف کو اپنے agents، workspace اور credentials ملتے ہیں، اور یہ isolation browser میں موجود token کے ذریعے برقرار رہتی ہے۔ اس کے ساتھ skills اور sub-agents کا ایک مشترکہ pool بھی ہوتا ہے جسے کوئی بھی استعمال کر سکتا ہے۔ یہی feature اسے family کے لیے چلانے کے قابل بناتا ہے: ایک شخص اچھا research agent صرف ایک بار بناتا ہے، اور کسی دوسرے کو اسے دوبارہ بنانے کی ضرورت نہیں رہتی۔

tooling استعمال کرتے وقت احتیاط کریں۔ Octop، tool approval اور shell command guardrails فراہم کرتا ہے، اور دونوں واقعی کام کرتے ہیں۔ لیکن جو agent shell commands چلاتا ہے، وہ انہیں Octop container کے اندر چلاتا ہے، جہاں آپ کا data volume mounted ہوتا ہے۔ Guardrails اس حد کو کم کرتے ہیں کہ ایک لاپرواہ prompt کیا کر سکتا ہے۔ وہ sandbox boundary نہیں ہیں۔ اس لیے ایسے ہر شخص کے لیے tool approval فعال رکھیں جسے آپ shell access نہیں دیں گے۔ اگر آپ اس کا موازنہ دوسرے options سے کر رہے ہیں تو self-hosted AI agents کا تقابلی جائزہ دکھاتا ہے کہ ہر option اس معاملے کو کیسے handle کرتا ہے۔

اتنی تیزی سے releases جاری کرنے والے project کو upgrade کرنا

چارٹDays between Octop releases, v0.9.16 to v0.9.19 (repository tags, 7 August 2026)

version

days_since_previous_release

v0.9.16

v0.9.17

v0.9.18

v0.9.19

اس چارٹ کے پیچھے کا ڈیٹا

[
  {
    "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
  }
]

یہ repository کے tag dates ہیں، جنہیں 7 August 2026 تک شمار کیا گیا ہے۔ 4 tagged releases نو دن میں جاری ہوئے، جن کے درمیان وقفہ صرف 1 دن تک رہا، جبکہ v0.9.19 اپنے سے پہلے والے tag کے 3 دن بعد جاری ہوا۔ یہ cadence project کے لیے اچھی علامت ہے، لیکن latest چلانے کی بری وجہ ہے۔ انہیں apply کرنے سے پہلے تبدیلیاں پڑھیں:

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"

اسے checkout کرنے سے پہلے دیکھیں کہ $NEW_TAG میں حقیقتاً کیا موجود ہے، کیونکہ project stable releases کے ساتھ v1.0.2b9 جیسی beta versions کو بھی tag کرتا ہے۔ 20 October 2026 تک تازہ ترین tag stable v1.0.2 ہے، جو 18 October 2026 کو شائع ہوا تھا، اور v0.9.19 سے v1.0.0 تک کا jump 14 September 2026 کی release سے گزرتا ہے، اس لیے یہ log طویل ہے اور اسے غور سے پڑھنا ضروری ہے۔

ہر بار پہلے backup لیں، کیونکہ startup کے وقت database migrations چلتی ہیں، اور اتنی تیزی سے releases جاری کرنے والے project میں ناکام migration کو درست کرنا آپ کی ذمہ داری ہے:

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

اس کے بعد نیا tag checkout کریں اور docker compose -f docker/docker-compose.yml up -d --build کے ساتھ rebuild کریں۔ اگر مسئلہ پیدا ہو تو پرانا tag checkout کرکے rebuild کرنے سے code واپس آ جائے گا، لیکن database صرف tarball سے واپس آئے گا۔

اس tarball میں octop.db، config.json، JWT signing secret اور credential.txt موجود ہیں، اس لیے یہ خود server جتنا حساس ہے۔ اس کا mode 600 رکھیں اور اس کی ایک copy server سے باہر محفوظ رکھیں۔ بڑے install کے لیے project docker/docker-compose.postgres.yml بھی فراہم کرتا ہے، جو SQLite کے بجائے pgvector کے ساتھ PostgreSQL چلاتا ہے۔

Failure modes، ان strings کے ساتھ جو آپ دیکھیں گے

Health check کبھی جواب نہیں دیتا۔ curl http://127.0.0.1:8088/api/health رک جاتا ہے یا connection مسترد کر دیتا ہے۔ docker compose -f docker/docker-compose.yml logs -f octop پڑھیں۔ جو container پہلی initialization کے دوران exit ہو جائے، وہ عموماً data directory میں لکھ نہیں سکتا، اس لیے اس چیز کی ownership چیک کریں جسے آپ نے OCTOP_DATA پر set کیا ہے۔

Dashboard load ہو جاتا ہے، لیکن chat رک جاتی ہے۔ Page پر کوئی error نہیں ہوتا اور کبھی reply نہیں آتا۔ Browser console کھولیں اور wss://octop.example.com/api/agents/.../chat/ws سے failed connection تلاش کریں۔ Proxy upgrade کو forward نہیں کر رہا۔ proxy_http_version 1.1، Upgrade اور Connection headers شامل کریں۔

پورا reply کئی seconds کی تاخیر کے بعد ایک ساتھ ظاہر ہوتا ہے۔ Streaming کام کر رہی ہے، لیکن buffering آن ہے۔ proxy_buffering off set کریں۔

bind: address already in use۔ 8088 پہلے ہی کسی چیز کے زیرِ استعمال ہے۔ sudo ss -tlnp | grep 8088 اس process کا نام دکھاتا ہے۔ یہ مسئلہ اس وقت بھی آتا ہے جب آپ نے override file میں اصل ports entry کو edit کرنے کے بجائے دوسری entry شامل کر دی ہو۔

درست password مسترد ہو جاتا ہے۔ پانچ غلط کوششوں کے بعد 900 seconds کا lockout فعال ہو جاتا ہے۔ دوبارہ install کرنے کے بجائے lockout ختم ہونے کا انتظار کریں۔

.env میں نیا password مؤثر نہیں ہوا۔ یہ credentials صرف پہلی initialization پر لاگو ہوتے ہیں۔ اسے dashboard میں تبدیل کریں۔

Agent reply دیتا ہے، لیکن کبھی tool نہیں چلاتا۔ تقریباً ہمیشہ مسئلہ local model میں ہوتا ہے: tool definitions کے لیے context window بہت چھوٹی ہے، یا model function calling میں کمزور ہے۔ num_ctx بڑھائیں اور tool use کے لیے تیار کردہ model آزمائیں۔

FAQ

کیا Octop، Open WebUI کا متبادل ہے؟

صرف اس صورت میں جب آپ کو وہ اضافی خصوصیات درکار ہوں جو یہ فراہم کرتا ہے۔ Open WebUI ماڈل کے سامنے ایک chat interface ہے، اور ایک فرد یا بااعتماد گھرانے کے لیے یہ کام اچھی طرح کرتا ہے۔ Octop میں admin role والے accounts، ہر صارف کے لیے الگ workspaces اور credentials، اور specialist agents کی قابلِ انتخاب library شامل ہے۔ اس لیے کئی افراد ایک ہی server استعمال کر سکتے ہیں، بغیر اس کے کہ سب ایک ہی history شیئر کریں۔ اگر آپ کے لیے ایک ہی account کافی ہے تو Open WebUI زیادہ سادہ اور کہیں زیادہ mature انتخاب ہے۔

مجھے Octop کی curl install script کیوں استعمال نہیں کرنی چاہیے؟

یہ script repository کے بجائے Tencent Cloud Object Storage bucket سے فراہم کی جاتی ہے، اس لیے کوئی git tag یا commit اسے cover نہیں کرتا۔ آپ آج یہ موازنہ نہیں کر سکتے کہ یہ script پچھلے ہفتے کیا کرتی تھی، اور اسے bash میں pipe کرنے سے پہلے پڑھے بغیر ہی execute ہو جاتی ہے۔ یہ host پر اپنے Python 3.12 environment کے ساتھ install بھی ہوتی ہے، جو آپ کے package manager سے باہر ہوتا ہے۔ اسے download کرکے پہلے پڑھیں، یا checked-out tag سے Docker Compose کے ذریعے deploy کریں۔

کیا Octop paid API کے بجائے local model استعمال کر سکتا ہے؟

ہاں۔ Octop OpenAI-compatible APIs استعمال کرتا ہے اور Ollama preset فراہم کرتا ہے۔ اس لیے http://host.docker.internal:11434/v1 کی طرف point کرنا اس وقت کام کرتا ہے جب آپ container میں extra_hosts: ["host.docker.internal:host-gateway"] شامل کریں اور host پر OLLAMA_HOST=0.0.0.0:11434 set کریں۔ Docker کی address range تک firewall port 11434 کھولیں، کیونکہ Ollama میں اپنی authentication موجود نہیں ہے۔ Ollama کی num_ctx کو 16k یا اس سے زیادہ کرنے کی توقع رکھیں، کیونکہ tool definitions والے agent prompts default context window سے بڑے ہو جاتے ہیں اور پھر model tools کو call کرنا بند کر دیتا ہے۔

کیا مجھے reverse proxy درکار ہے، یا میں port 8088 کھول سکتا ہوں؟

آپ کو reverse proxy درکار ہے۔ Octop کی فراہم کردہ Compose file ہر interface پر 8088 کو بغیر TLS کے publish کرتی ہے، اس لیے passwords اور bearer tokens internet پر cleartext میں منتقل ہوں گے۔ Published port کو 127.0.0.1:8088:8088 میں تبدیل کریں اور سامنے Caddy یا nginx کو certificate کے ساتھ رکھیں۔ nginx کے ساتھ WebSocket upgrade headers forward کریں اور proxy_buffering off set کریں، ورنہ page load ہو جائے گا لیکن chat خاموشی سے کبھی response نہیں دے گی۔

کیا Octop production کے لیے تیار ہے؟

August 2026 تک یہ pre-1.0 تھا اور ہر ہفتے کئی tagged releases جاری کر رہا تھا۔ اس نے 14 September 2026 کو v1.0.0 tag کیا، پھر 18 October 2026 کو stable v1.0.2 جاری کرنے سے پہلے 1.0.2 beta tags کا ایک سلسلہ جاری کیا۔ یہ رفتار اب بھی تیز ہے، اس لیے اسے مستحکم حل کے بجائے promising solution سمجھیں۔ اگر آپ exact tag pin کریں، ہر upgrade سے پہلے commit log پڑھیں، اور ہر rebuild سے پہلے data volume کا backup لیں تو یہ گھرانے یا چھوٹی internal team کے لیے قابلِ عمل ہے۔ اسے latest پر نہ چلائیں، اور ابھی اس میں customer data نہ رکھیں۔

کیا یہ مضمون مفید تھا؟

#octop#self-hosting #ai-assistant #docker-compose #ollama