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

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 اور credential set، اور 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 کو جاری ہوا تھا۔ اگر آپ ابھی platforms کے درمیان فیصلہ کر رہے ہیں تو VPS پر چلنے والے Open WebUI alternatives کا موازنہ وسیع تر منظرنامہ پیش کرتا ہے۔

اس پر ایک شام صرف کرنے سے پہلے ایک بات واضح ہونی چاہیے۔ Octop pre-1.0 software ہے، جو ایک vendor کی GitHub organisation سے شائع کیا گیا ہے، اور August 2026 تک اس کے تقریباً 900 stars ہیں۔ اس کی development تیز ہے، 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 پر مقرر

August 2026 تک pull کرنے کے لیے کوئی published image موجود نہیں ہے۔ فراہم کردہ Compose file repository سے image build کرتی ہے، اس لیے version مقرر کرنے کا مطلب git tag checkout کرنا ہے۔ یہ زیادہ تر self-hosted projects کے مقابلے میں ایک اضافی مرحلہ ہے، کیونکہ self-hosted AFFiNE workspace جیسی سروس published image tag مقرر کرتی ہے اور آپ کے VPS پر کچھ بھی build نہیں کرتی۔ ذیل میں clone، checkout اور build کا routine وہی ہے جسے openGym deployment guide میں بیان کیا گیا ہے۔ اگر آپ نے اسے ایک بار ترتیب دیا ہے تو اس کا طریقہ پہلے سے معلوم ہے۔

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

یہ وہ service ہے جسے file 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 سے مراد وہ image ہے جسے آپ نے حال ہی میں compile کیا ہے۔ data path کو کسی واضح location پر مقرر کریں، اسے 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

یہاں ایک اہم مسئلہ ہے جو file کے باقی حصوں سے زیادہ توجہ کا مستحق ہے۔ Compose docker/.env کو صرف YAML میں موجود ${...} placeholders کی interpolation کے لیے پڑھتا ہے۔ اس file میں شامل کیا گیا کوئی key container تک نہیں پہنچتا، جب تک اسے Compose file میں environment: کے تحت بھی درج نہ کیا جائے۔ صرف OCTOP_ACCESS_TOKEN_TTL کو .env میں شامل کرنے سے کچھ بھی نہیں ہوتا، اور کوئی error بھی ظاہر نہیں ہوتی۔ متبادل طریقہ یہ ہے کہ یہی keys mounted data directory کے اندر ~/.octop/env میں لکھی جائیں۔ 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 کے لیے {"status":"ok","version":"..."} واپس کرتا ہے۔ اس کے علاوہ کوئی بھی نتیجہ آئے تو 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

default credentials admin / octop ہیں، اور یہ صرف پہلی init کے وقت لاگو ہوتے ہیں۔ اسی وجہ سے ایک سوال بار بار سامنے آتا ہے: container کے ایک بار start ہونے کے بعد OCTOP_DEFAULT_PASSWORD تبدیل کرنے سے کچھ نہیں بدلتا، کیونکہ account پہلے ہی بن چکا ہوتا ہے۔ اس کے بجائے dashboard میں password تبدیل کریں۔

8088 کا port شائع نہ کریں

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

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

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

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

Loopback پر bind کرنے سے firewall کا وہ مسئلہ بھی حل ہو جاتا ہے جس کا سامنا بصورت دیگر ہوتا۔ Docker اپنے published-port rules کو nat table میں ان chains سے پہلے لکھتا ہے جنہیں ufw manage کرتا ہے۔ اس لیے ufw deny 8088 published container port کو نہیں روکتا۔ 127.0.0.1 پر bind کیا گیا port، ufw کی configuration سے قطع نظر، باہر سے کبھی reachable نہیں ہوتا۔ اسی لیے یہ درست حل ہے، محض ثانوی متبادل نہیں۔

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

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

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx کو زیادہ احتیاط درکار ہے، کیونکہ Octop چیٹ کو 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;
    }
}

اس configuration کی ہر سطر ایک مخصوص کام کرتی ہے۔ چیٹ WS /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 seconds کی 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 /agents/{id}/chat/ws?token=<jwt> ہے، کیونکہ browser JavaScript، WebSocket handshake پر Authorization header set نہیں کر سکتی۔ TLS دورانِ ترسیل اس token کو محفوظ رکھتا ہے۔ لیکن یہ 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 attacks کا انتظام موجود ہے: OCTOP_LOGIN_MAX_ATTEMPTS کی default value 5 failures اور OCTOP_LOGIN_LOCKOUT_SECONDS کی default value 900 ہے۔ اس لیے locked-out user خراب installation سمجھنے کے بجائے صرف پندرہ منٹ انتظار کرتا ہے۔ Octop کا اپنا user store ہے اور v0.9.19 میں OIDC support documented نہیں ہے۔ اگر آپ کو حقیقی single sign-on درکار ہو تو Octop کے سامنے 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 کرتا ہے۔

اتنی تیزی سے release ہونے والے project کو upgrade کرنا

[
  {
    "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 چلانے کی خراب وجہ ہے۔ تبدیلیاں پڑھ کر ہی انہیں لاگو کریں:

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"

ہر بار پہلے backup لیں، کیونکہ database migrations startup کے وقت چلتی ہیں، اور pre-1.0 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 سے باہر بھی محفوظ کریں۔ بڑے installation کے لیے project docker/docker-compose.postgres.yml بھی فراہم کرتا ہے، جو SQLite کے بجائے pgvector کے ساتھ PostgreSQL چلاتا ہے۔

خرابی کی صورتیں، اور نظر آنے والے پیغامات

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

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

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

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

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

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

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

FAQ

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

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

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

یہ script repository کے بجائے Tencent Cloud Object Storage bucket سے فراہم کی جاتی ہے، اس لیے کوئی git tag یا commit اس کا احاطہ نہیں کرتا۔ آپ آج اس کے عمل کا گزشتہ ہفتے کے عمل سے موازنہ نہیں کر سکتے، اور اسے bash میں pipe کرنے سے پہلے پڑھے بغیر ہی چلایا جاتا ہے۔ یہ اپنے Python 3.12 environment کے ساتھ host پر 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 کرنا اس وقت کام کرتا ہے جب آپ extra_hosts: ["host.docker.internal:host-gateway"] کو container میں شامل کریں اور 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 کھول سکتا ہوں؟

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

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

August 2026 تک یہ pre-1.0 ہے اور ہر ہفتے کئی tagged releases جاری کر رہا ہے، اس لیے اسے مستحکم حل کے بجائے امید افزا software سمجھیں۔ اگر آپ exact tag pin کریں، ہر upgrade سے پہلے commit log پڑھیں، اور ہر rebuild سے پہلے data volume کا backup لیں تو یہ خاندان یا چھوٹی internal team کے لیے قابلِ استعمال ہے۔ اسے latest پر نہ چلائیں، اور فی الحال اس میں customer data نہ رکھیں۔