VPS پر Agentlas OS self-host کرنے کا طریقہ

Agentlas OS اصل میں کیا ہے

Agentlas OS ایک open source agent runtime ہے جو specialist agents کو packages کی صورت میں disk پر محفوظ رکھتا ہے اور ہر task کے لیے عارضی orchestrator تیار کرتا ہے۔ آپ اسے Linux VPS پر اپنے user account میں install کرکے self-host کرتے ہیں۔ یہ کوئی service نہیں ہے۔ اس میں کوئی daemon، listening port، web interface یا repository میں container image موجود نہیں ہے۔

اس آخری جملے سے اس صفحے کی باقی تمام باتیں واضح ہو جاتی ہیں۔ زیادہ تر multi-agent systems ایک supervisor process چلاتے ہیں جو مسلسل فعال رہتا ہے اور agents کو اپنے اندر رکھتا ہے۔ Agentlas اس طریقے کو الٹ دیتا ہے: specialist agents مستقل فائلوں کی صورت میں موجود رہتے ہیں، جبکہ orchestrator صرف task کے دوران موجود ہوتا ہے۔ عملی نتیجہ یہ ہے کہ idle hub کے لیے memory کے بجائے صرف disk درکار ہوتی ہے۔

یہ project اپنے open core کو Hephaestus کہتا ہے، اور commands، paths اور environment variables میں آپ یہی نام دیکھیں گے۔ repository agentlas-ai/Agentlas-OS ہے، Apache-2.0 کے تحت licensed ہے، اور زیادہ تر Python میں لکھی گئی ہے۔

یہ project حقیقت میں کتنا ابتدائی مرحلے میں ہے؟

یہ repository 4 June 2026 کو بنائی گئی تھی۔ 12 August 2026 تک اسے تقریباً دس ہفتے ہوئے ہیں، اور اس کے تقریباً 1,150 stars اور 112 forks ہیں۔ حقیقی کام کے لیے استعمال ہونے والے project کے لحاظ سے یہ کم عمر ہے۔

release cadence، عمر سے زیادہ اہم ہے۔ Version v1.1.103، 8 August 2026 کو publish ہوا، جبکہ v1.2.0، 12 August 2026 کو جاری ہوا۔ 1.1 series میں سو سے زیادہ tagged releases ہیں، جن میں بعض دنوں میں کئی releases شامل ہیں، اور یہ سب automation کے ذریعے publish ہوئے ہیں۔ اتنی تیزی سے آگے بڑھنے والے project میں منگل اور جمعرات کے درمیان آپ کے استعمال کے دوران behaviour تبدیل ہو سکتا ہے۔

اس لیے release کو pin کریں۔ installer اس مقصد کے لیے ایک environment variable پڑھتا ہے، اور نیچے دی گئی پوری guide اسی variable کو استعمال کرتی ہے۔ دن میں کئی بار releases جاری کرنے والے project کی unpinned installation آپ کو ہر گھنٹے main پر موجود تازہ ترین حالت دے گی۔

VPS پر درکار چیزیں

تقاضے کم ہیں کیونکہ پس منظر میں کچھ نہیں چلتا۔

• ایک Linux VPS۔ Ubuntu 24.04 ایک مناسب بنیادی انتخاب ہے۔ installer uname -s کے ذریعے operating system معلوم کرتا ہے اور Linux کے لیے non-macOS branch استعمال کرتا ہے، اس لیے headless box معاونت یافتہ ہے۔
• box پر curl، tar اور git، اور ایک فعال Python interpreter۔
• raw.githubusercontent.com اور github.com تک outbound HTTPS۔ installer release archive download کرتا ہے اور اس کا SHA-256 چیک کرتا ہے، اس لیے outbound رسائی نہ رکھنے والا box اسے install نہیں کر سکتا۔
• ایک host harness، یعنی coding agent جو model سے براہ راست رابطہ کرتا ہے۔ Claude Code، Codex، opencode، goose اور Hermes سب supported adapters ہیں۔

آپ کو root درکار نہیں۔ installer صرف آپ کی home directory اور ~/.local/bin میں لکھتا ہے، اور جب کوئی path writable نہ ہو تو abort کرنے کے بجائے warning دیتا ہے۔ اگر آپ ابھی box کا انتخاب کر رہے ہیں تو VPS پر coding agent چلانا اس بنیادی image اور access setup کا احاطہ کرتا ہے جس کے اوپر یہ ترتیب قائم ہوتی ہے۔

پِن کی گئی release انسٹال کریں

upstream README میں ایک single-line command درج ہے جو main سے ایک script کو براہِ راست bash میں pipe کرتی ہے۔ اسے download کریں اور پہلے پڑھیں۔ یہ آپ کی shell configuration اور اسے ملنے والے ہر agent harness میں تبدیلیاں لکھتی ہے، اس لیے اس پر دس سیکنڈ توجہ دینا مفید ہے۔

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF pin ہے۔ Script کے اندر یہ line version="${HEPHAESTUS_REF:-v1.2.0}" ہے، اس لیے اسے unset چھوڑنے سے آج v1.2.0 ملتا ہے، لیکن اگلے ہفتے کوئی اور version مل سکتا ہے۔ اسے صراحت کے ساتھ set کریں تاکہ اکتوبر میں rebuild کرنے پر وہی version انسٹال ہو جسے آپ نے اگست میں test کیا تھا۔

ایک اہم حد یہ ہے: اوپر دیا گیا script URL main کو track کرتا ہے، جبکہ HEPHAESTUS_REF اس runtime payload کو pin کرتا ہے جسے script download کرتی ہے۔ یہ دو الگ چیزیں ہیں۔ دونوں کو pin کرنے کے لیے main کے بجائے tag سے script fetch کریں۔ اس URL میں main کو v1.2.0 سے replace کریں۔

کامیاب run کے بعد وہ ان paths کو print کرتا ہے جہاں اس نے files لکھی ہیں، جن میں یہ دو lines شامل ہیں:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

دوسری line اکثر نظرانداز کر دی جاتی ہے۔ نئی Ubuntu machine پر ~/.local/bin اکثر PATH میں موجود نہیں ہوتا، اس لیے ہر hep-* command command not found کے ساتھ fail ہوتی ہے، حالانکہ installation کامیاب ہو چکی ہوتی ہے۔ اسے درست کریں اور تصدیق کریں:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status یہ بتاتا ہے کہ global router نے کیا install کیا اور اسے کون سے harnesses ملے۔ اگر یہ command بالکل run ہو جائے تو آپ کا PATH درست ہے۔

حالت کہاں محفوظ رہتی ہے

آپ کی home directory کے تحت ہر چیز ایک file ہے، اس لیے backup اور migration آسان رہتے ہیں۔

• ~/.agentlas/runtime/v1.2.0/ میں خود runtime موجود ہوتا ہے، جبکہ ~/.agentlas/runtime/current/ فعال version کی طرف symlink ہوتا ہے۔ دو pinned versions ساتھ ساتھ رکھے جا سکتے ہیں۔
• ~/.local/bin/ میں shell wrappers موجود ہوتے ہیں: hephaestus، hep-build، hep-network، hep-search، hep-storm، hep-cloud اور hep-upload۔
• ~/.agentlas/networking/memory/ میں مستقل memory موجود ہوتی ہے: playbook-registry.json، playbook-candidates.jsonl اور memory-events.jsonl۔
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite میں ہر agent کا تجربہ owner کے دائرہ کار کے مطابق محفوظ ہوتا ہے۔
• <project>/.agentlas/ontology-runtime.sqlite میں ہر project کی state موجود ہوتی ہے، اس لیے یہ server کے بجائے repository کے ساتھ منتقل ہوتی ہے۔
• ~/.cache/agentlas/python میں Linux پر Python cache موجود ہوتا ہے۔ macOS مختلف path استعمال کرتا ہے، اور installer uname کے ذریعے درست branch منتخب کرتا ہے۔

Memory documentation واضح کرتی ہے کہ کسی بھی memory scope میں secrets، raw credentials اور مکمل transcripts شامل نہیں کیے جانے چاہییں۔ Credential values مقامی gitignored files میں رہتی ہیں، جبکہ memory صرف names اور paths ریکارڈ کرتی ہے۔ ~/.agentlas اور اپنے project کی .agentlas directories کا backup لے لیں، تو نئے VPS پر system دوبارہ بنایا جا سکتا ہے۔

یہ کن model backends کو استعمال کر سکتا ہے

یہاں ایک اہم تفصیل پوری ترتیب کا مفہوم واضح کرتی ہے: Agentlas براہِ راست model API کو call نہیں کرتا۔ یہ کام host harness انجام دیتا ہے۔

Architecture document میں runtime adapters کا ذکر ہے، جو ایک core کو ہر harness کے لیے موزوں شکل میں تبدیل کرتے ہیں۔ اس میں یہ بھی بتایا گیا ہے کہ model credentials کی ملکیت host runtime کے پاس ہوتی ہے۔ Agentlas دو ایسے interfaces فراہم کرتا ہے جنہیں harness استعمال کرتا ہے: ایک AgentSkills file اور ایک MCP (model context protocol) server، جو stdio کے ذریعے رابطہ کرتا ہے۔ اس لیے سوال "Agentlas کن models کو support کرتا ہے" دراصل یہ ہے کہ "آپ کا harness کن models کو support کرتا ہے"۔ جواب یہ ہے کہ وہ تمام models جن تک Claude Code، Codex، opencode، goose یا Hermes رسائی حاصل کر سکتے ہیں۔

Codex-style TOML config میں MCP server کو اس طرح register کیا جاتا ہے:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

Install کے دوران یہی server خودکار طور پر ~/.cursor/mcp.json، ~/.config/goose/config.yaml اور دیگر harness configs میں بھی register ہو جاتا ہے۔ اگر آپ ایک ہی box پر ان میں سے کئی servers configure کر رہے ہیں تو VPS پر MCP servers چلانا stdio اور process model کی مزید تفصیل فراہم کرتا ہے۔

مقامی میزبانی والے Ollama endpoint کی طرف route کریں

چونکہ harness ماڈل connection کا انتظام کرتا ہے، اس لیے Agentlas کو local models کی طرف point کرنے کا مطلب ہے کہ اپنے harness کو Ollama کی طرف point کریں۔ Ollama نے v0.15 میں اسی مقصد کے لیے launch subcommand شامل کیا تھا، اور 11 August 2026 تک یہ v0.32.9 میں بھی شامل ہے۔ یہ کسی environment variables کے بغیر موجودہ harness کو local models کے لیے configure کرتا ہے:

ollama pull qwen3-coder:30b
ollama launch opencode

اپنے نصب کردہ harness کے مطابق opencode کی جگہ claude، codex یا droid استعمال کریں۔ اس کے بعد local runtime کے ذریعے ایک request route کریں:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

کامیاب route ایک JSON decision واپس کرتا ہے، جس میں منتخب کردہ agent یا team کا نام اور receipt_id شامل ہوتا ہے۔ اگر مفید output واپس نہ آئے تو عام وجہ context length ہوتی ہے۔ Agentlas کی documentation routing-heavy sessions کے لیے کم از کم 64k context والے model کا تقاضا کرتی ہے اور qwen3-coder، gemma3 اور deepseek-r1 کو مثالوں کے طور پر پیش کرتی ہے۔ Coding tools کے لیے Ollama کی اپنی guidance بھی یہی 64k حد مقرر کرتی ہے۔ Routing decisions میں prompt کے اندر agents کی فہرست شامل ہوتی ہے، اس لیے 8k یا 32k context والا model اس فہرست کو truncate کر دیتا ہے اور غلط انتخاب کرتا ہے۔

ایک اہم بات tagline میں نہیں بتائی جائے گی۔ Ollama، Gemma اور DeepSeek کا اپنا کوئی plugin یا command system نہیں ہے، اس لیے /agentlas slash commands وہاں موجود نہیں ہوتیں۔ Local-model setup میں آپ system کو اس کے بجائے MCP server اور hephaestus route command کے ذریعے چلاتے ہیں۔ یہ system کی سطح میں حقیقی کمی ہے، لیکن weights کو اپنے سرور پر رکھنے کی یہی عملی قیمت ہے۔

غیر فعال specialists کے hub کی RAM لاگت

کچھ بھی نہیں۔ یہی مکمل جواب ہے، اور آپ اس پر بھروسا کرنے کے بجائے اسے ثابت کر سکتے ہیں۔

ادھار لیے گئے hub specialists processes کے طور پر نہیں بلکہ package artifacts کے طور پر آتے ہیں۔ ایک specialist، agent.md اور JSON کی .agentlas/ directory پر مشتمل ہوتا ہے: triggers اور capabilities کے لیے routing-card.json، write boundaries کے لیے memory-map.json، اور اس بات کے لیے mode-map.json کہ یہ اکیلا چلتا ہے یا team کے طور پر۔ Hephaestus Network کو ایک in-process scheduler کے طور پر بیان کیا گیا ہے جس کی کوئی background service نہیں ہے۔ tasks کے درمیان خود جانچنے کے لیے:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

پہلے دو commands idle box پر کچھ بھی print نہیں کرتے، کیونکہ کوئی چیز memory میں resident نہیں ہوتی۔ تیسرا command اس parked hub کی واحد لاگت دکھاتا ہے جو آپ پر عائد ہوتی ہے، یعنی disk۔ یہ لاگت ان specialists کی تعداد کے ساتھ بڑھتی ہے جنہیں آپ برقرار رکھتے ہیں، اور اس bundled embedding model کے ساتھ بھی جسے runtime فراہم کرتا ہے۔

لہٰذا memory کا سوال مکمل طور پر burst کی لاگت سے متعلق ہے، اور burst کی لاگت آپ کے harness اور model backend پر مشتمل ہوتی ہے۔ اگر harness کسی hosted API سے رابطہ کرتا ہے تو resident cost چند سو megabytes کا ایک process ہوتی ہے۔ اگر آپ weights کو self-host کرتے ہیں تو اصل لاگت weights ہیں:

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

یہ Ollama کی model library میں شائع کردہ download sizes ہیں، benchmark run سے حاصل کردہ پیمائشیں نہیں۔ 64k context کے لیے KV cache ہر صفر سے بڑی اوپر دی گئی قدر کے علاوہ درکار ہوتی ہے۔ Agentlas docs میں پہلے درج model، qwen3-coder:30b، context سے پہلے 19 GB weights کا تقاضا کرتا ہے، جبکہ 27B Gemma variant بھی 17 GB مانگتا ہے۔ ان اعداد کے مقابلے میں Agentlas layer خود budget میں نمایاں نہیں ہوتی۔

ایک harness چلانے کے مقابلے میں یہ کیسے مختلف ہے

ایک hosted API کے خلاف ایک harness چلائیں تو آپ کا VPS ایک process چلاتا ہے۔ Agentlas شامل کرنے پر بھی یہی ایک process چلتا ہے، اس کے ساتھ files بھی موجود ہوتی ہیں۔ Orchestrator کوئی اضافی طویل مدت تک چلنے والا program نہیں ہے۔ یہ disk پر موجود packages سے تیار کیا جانے والا ایک بڑا prompt ہے، جسے کام مکمل ہونے کے بعد ختم کر دیا جاتا ہے۔

جو لاگت واقعی بدلتی ہے وہ memory نہیں بلکہ context ہے۔ ایسا orchestrator جو کئی specialist cards اور ان کے routing metadata کو شامل کرتا ہے، ہر task کے لیے bare harness کے مقابلے میں زیادہ tokens استعمال کرتا ہے۔ Hosted API پر یہ RAM کے بجائے رقم کی لاگت ہے۔ Local weights پر یہ وقت کی لاگت ہے، کیونکہ طویل prompt کا مطلب CPU پر زیادہ طویل prefill یا GPU پر زیادہ مصروفیت ہے۔

اسی لیے اس طرح کے box کے لیے sizing advice کا انحصار agent framework کے بجائے model کے انتخاب پر ہوتا ہے۔ coding agent VPS کے لیے RAM اور CPU کی sizing میں اس کی تفصیل موجود ہے، اور نتیجہ یہاں بھی یہی ہے: جس backend کو چلانا ہو، plan اسی کے مطابق منتخب کریں، پھر harness کے لیے چند gigabytes اضافی گنجائش رکھیں۔ اگر اس کے بجائے موازنے کے لیے ہمیشہ چلنے والے supervisor design کی ضرورت ہو تو Omnigent multi-agent harness اپنے coordinator کو resident رکھتا ہے۔ یہ اس کے برعکس trade-off ہے اور idle memory میں براہ راست نظر آتا ہے۔

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

hep-build: command not found صاف installation کے فوراً بعد۔ Installer نے ~/.local/bin میں لکھا، جو default Ubuntu image میں PATH پر موجود نہیں ہے۔ آخری سطر میں اس کی وضاحت تھی، لیکن وہ سطر اسکرول ہو گئی۔ اوپر دکھایا گیا export شامل کریں۔

Box دوبارہ build کرنے کے بعد رویہ بدل جاتا ہے۔ آپ نے HEPHAESTUS_REF مقرر نہیں کیا، اس لیے installer نے اس دن موجودہ tag کو default کے طور پر استعمال کیا۔ اسے pin کریں، اور اس pin کو اپنے دوسرے version numbers کے ساتھ درج کریں۔

Local model میں routing غلط specialist منتخب کرتی ہے۔ Model کی context window agent inventory کے لیے بہت چھوٹی ہے۔ 64k یا اس سے زیادہ والے model پر منتقل ہوں اور Ollama کی context length بھی اسی کے مطابق مقرر کریں، کیونکہ default value coding tools کی ضرورت سے کم ہے۔

ollama launch کو تسلیم نہیں کیا جاتا۔ یہ subcommand Ollama v0.15 میں شامل ہوئی تھی۔ Distribution repository کے پرانے packages اس سے پہلے کے ہیں، اس لیے موجودہ Ollama انسٹال کریں۔

Installation ان harnesses میں لکھتی ہے جن کی آپ کو توقع نہیں تھی۔ Script ہر اس harness کو detect اور configure کرتی ہے جو اسے ملتا ہے، اور ~/.claude/، ~/.codex/، ~/.gemini/، ~/.cursor/ وغیرہ میں لکھتی ہے۔ Shared build box پر اسے چلانے سے پہلے script پڑھیں اور طے کریں کہ ان میں سے کن directories کی آپ کو ضرورت ہے۔

ابھی اسے چلانا چاہیے؟

دس ہفتے پرانے ایسے project کو، جس میں دن میں کئی بار automated releases آتی ہوں، production workload کے لیے استعمال نہیں کرنا چاہیے۔ اس کا architecture واقعی دلچسپ ہے، اس کا license Apache-2.0 ہے، اور file-based design کی وجہ سے اسے uninstall کرنے کے لیے صرف دو directories delete کرنا پڑتی ہیں۔ ان خصوصیات کی وجہ سے اسے آزمانا آسان اور اس پر انحصار کرنا مہنگا ہے۔

فی الحال مناسب طریقہ یہ ہے: v1.2.0 کو pin کریں، اسے ایسے box پر چلائیں جسے دوبارہ build کیا جا سکے، ~/.agentlas کو اپنے backups میں شامل رکھیں، اور pin تبدیل کرنے سے پہلے changelog دوبارہ پڑھیں۔ اس space میں موجود دیگر options اور ہر option کی maturity کا وسیع جائزہ لینے کے لیے self-hosted AI agents کا جائزہ بہتر نقطۂ آغاز ہے، جبکہ VPS پر Hermes agent کو self-host کرنا ان harnesses میں سے ایک کو بیان کرتا ہے جنہیں Agentlas adapt کرتا ہے۔

FAQ

کیا Agentlas OS میرے VPS پر server کے طور پر چلتا ہے؟

نہیں۔ Repository میں کوئی daemon، listening port یا container image موجود نہیں ہے۔ Installer ~/.agentlas/runtime/ کے تحت runtime اور ~/.local/bin میں command wrappers لکھتا ہے، جبکہ Hephaestus Network پس منظر کی service کے بجائے in-process scheduler ہے۔ آپ idle box پر اس کی تصدیق کر سکتے ہیں: pgrep -af hephaestus کچھ بھی output نہیں کرتا، اور enable کرنے کے لیے کوئی systemd unit موجود نہیں ہے۔ یہاں self-hosting سے مراد یہ ہے کہ code اور state آپ کی machine پر موجود ہیں، نہ کہ کوئی service listening کر رہی ہے۔

idle specialists کے hub کو کتنی RAM درکار ہوتی ہے؟

کوئی نہیں، کیونکہ idle specialists processes نہیں ہوتے۔ specialist ایک agent.md file اور .agentlas/ directory پر مشتمل ہوتا ہے، جس میں routing-card.json، memory-map.json اور اسی نوعیت کا metadata ہوتا ہے؛ اس لیے parked hub صرف disk space استعمال کرتا ہے۔ اسے du -sh ~/.agentlas سے measure کریں۔ Memory صرف task چلنے کے دوران استعمال ہوتی ہے، اور اسے Agentlas layer نہیں بلکہ آپ کا harness process اور model backend استعمال کرتے ہیں۔

میں کون سے models استعمال کر سکتا ہوں، اور کیا اسے اپنے Ollama کی طرف point کر سکتا ہوں؟

Agentlas خود model APIs کو call نہیں کرتا۔ Credentials اور connection host harness کے زیر انتظام ہوتے ہیں، اس لیے supported models وہی ہیں جنہیں آپ کا harness support کرتا ہے۔ Local weights کے لیے ollama launch opencode چلائیں، اور claude، codex یا droid میں سے متعلقہ value استعمال کریں۔ اس سے environment variables کے بغیر harness آپ کے Ollama server کے خلاف configure ہو جاتا ہے۔ کم از کم 64k context والا model استعمال کریں، جیسے qwen3-coder یا gemma3، کیونکہ routing prompts میں agent inventory شامل ہوتی ہے اور چھوٹی windows پر یہ بری طرح truncate ہو جاتی ہیں۔

مجھے کون سا version install کرنا چاہیے، اور یہاں pinning کیوں اہم ہے؟

v1.2.0 install کریں۔ یہ 12 August 2026 کو موجودہ tagged release تھا۔ اس کے لیے installer چلانے سے پہلے HEPHAESTUS_REF=v1.2.0 set کریں۔ Script کی اپنی default value version="${HEPHAESTUS_REF:-v1.2.0}" ہے، جو maintainers کے اگلے tag کے مطابق بدلتی رہتی ہے۔ یہاں pinning معمول سے زیادہ اہم ہے، کیونکہ project نے اپنی 1.1 series میں 100 سے زیادہ releases شائع کیں، اور بعض دنوں میں کئی releases بھی آئیں۔ اس لیے چند ہفتوں بعد unpinned rebuild کرنے سے وہی system حاصل نہیں ہوگا جسے آپ نے test کیا تھا۔