VPS پر OpenCode کیسے چلائیں؟ محفوظ مکمل طریقہ

OpenCode کیا ہے، اور آپ کیا ترتیب دے رہے ہیں

OpenCode ٹرمینل کے لیے بنایا گیا ایک open source AI coding agent ہے۔ آپ اسے project directory کے اندر شروع کرتے ہیں، اور یہ آپ کا code پڑھتا، تبدیلیاں تجویز کرتا، files میں ترمیم کرتا اور commands چلاتا ہے۔ یہ سب terminal user interface (TUI) کے ذریعے ہوتا ہے۔ اسے MIT license حاصل ہے، یہ 75 سے زیادہ model providers سے connect ہوتا ہے، اور mid-2026 تک تقریباً 165,000 GitHub stars کے ساتھ یہ سب سے زیادہ stars والا open source coding agent ہے۔ VPS پر OpenCode چلانے کے لیے اسے ایک dedicated unprivileged user کے تحت install کریں، اپنی model API key ایک private file میں رکھیں، اور اسے tmux کے اندر شروع کریں تاکہ connection منقطع ہونے پر بھی session برقرار رہے۔ یہ guide یہی کام اسی ترتیب سے کرتی ہے۔

نام سے متعلق ایک بات الجھن دور کر دیتی ہے۔ canonical repository anomalyco/opencode ہے، جسے Anomaly team maintain کرتی ہے؛ اسے پہلے SST کے نام سے جانا جاتا تھا۔ یہ project پہلے sst/opencode پر موجود تھا۔ GitHub پر opencode-ai/opencode نام کی ایک پرانی، غیر متعلقہ repository بھی موجود ہے، اس لیے تصدیق کریں کہ آپ درست project کی documentation پڑھ رہے ہیں۔ official site opencode.ai ہے۔

VPS پر OpenCode چلانے کی وجوہات

coding agent کا session طویل ہوتا ہے۔ OpenCode کو refactor یا test suite مکمل کرنے میں کئی منٹ لگ سکتے ہیں۔ اگر یہ آپ کے laptop پر چل رہا ہو تو lid بند کرنے یا Wi-Fi connection منقطع ہونے سے session کام کے درمیان ختم ہو جاتا ہے۔ VPS پر tmux کے اندر agent آپ کے disconnect ہونے کے بعد بھی کام کرتا رہتا ہے، اور آپ بعد میں دوبارہ attach ہو کر دیکھ سکتے ہیں کہ اس نے کیا کیا۔ یہ اسی طریقے کی مثال ہے جیسے VPS پر tmux کے ساتھ Claude Code چلانا، اور agent کو laptop سے منتقل کرنے کا سب سے نمایاں عملی فائدہ بھی یہی ہے۔

دوسری وجہ تعیناتی کی جگہ ہے۔ VPS اس code کے قریب ہوتا ہے جسے آپ deploy کرتے ہیں۔ Repository، build tools، test database اور اکثر staging environment پہلے ہی وہاں یا اس کے قریب موجود ہوتے ہیں۔ جو agent code میں ترمیم کرے اور tests چلائے، وہ اسی machine پر سب سے بہتر کام کرتا ہے جہاں وہ tests حقیقت میں چلتے ہیں۔ چونکہ یہ box آپ کے کنٹرول میں موجود server ہے، اس لیے آپ agent کے لیے جان بوجھ کر ایک محدود environment بھی فراہم کر سکتے ہیں، جس کی وضاحت اگلے section میں ہے۔

اگر آپ ابھی tool منتخب کر رہے ہیں تو VPS پر coding AI agent چلانا وسیع تر options کا تقابل پیش کرتا ہے، جن میں Aider اور Goose بھی شامل ہیں۔

OpenCode کے لیے الگ صارف بنائیں

حقیقت یہ ہے کہ coding agent فائلوں میں ترمیم کرتا ہے اور commands چلاتا ہے۔ یہی اس کا کام ہے، اور یہی خطرہ بھی ہے۔ OpenCode builds، tests اور وہ shell commands چلائے گا جن کی task کو بظاہر ضرورت ہو، لیکن model کا فیصلہ درست ہونے کے باوجود بے خطا نہیں ہوتا۔ Agent جس account کے طور پر چلتا ہے، خراب command کی رسائی اسی account کی اجازتوں تک محدود رہتی ہے۔ اس لیے اسے root کے طور پر نہ چلائیں، اور نہ ہی اس صارف کے طور پر چلائیں جو server کا انتظام کرتا ہے۔

Background agent کے برعکس، OpenCode interactive ہے۔ اس لیے اس کے صارف کو حقیقی shell اور home directory درکار ہوتی ہے:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

جن projects پر آپ اسے کام کرانا چاہتے ہیں، انہیں /home/opencode کے تحت رکھیں اور انہیں اسی صارف کے ذریعے clone کریں۔ اس account کو sudo کی کوئی اجازت نہ دیں۔ اگر agent کوئی تباہ کن command چلاتا ہے تو وہ صرف اسی account کی ملکیت والی چیزیں تباہ کر سکتا ہے۔ یہی اصول غیر مراعات یافتہ صارف کے طور پر services چلانے پر بھی لاگو ہوتا ہے۔ اس کے علاوہ git repository کے اندر کام کریں، کیونکہ repository کسی بھی غلط ترمیم کو loss کے بجائے git revert میں بدل دیتی ہے۔

OpenCode انسٹال کریں

پروجیکٹ میں انسٹالیشن کے 2 طریقے درج ہیں۔ انسٹال اسکرپٹ سب سے تیز طریقہ ہے، اور اسے opencode صارف کے طور پر چلانے سے تمام فائلیں اسی صارف کی home directory میں رہتی ہیں:

curl -fsSL https://opencode.ai/install | bash

معمول کی curl | bash احتیاط یہاں بھی لاگو ہوتی ہے: جس سرور کی آپ کو پروا ہو، اس پر اسکرپٹ پہلے download کریں، اسے پڑھیں، پھر چلائیں۔ انسٹالیشن کے بعد نیا shell شروع کریں تاکہ installer کی جانب سے PATH میں کی گئی تبدیلی مؤثر ہو جائے، پھر binary کا جواب چیک کریں:

opencode --version

اگر آپ package manager کو ترجیح دیتے ہیں اور Node.js پہلے سے server پر موجود ہے، تو npm طریقہ وہی tool system-wide انسٹال کرتا ہے۔ اس سے opencode binary ہر صارف کے PATH میں شامل ہو جاتی ہے:

sudo npm install -g opencode-ai

دونوں صورتوں میں جانچ ایک جیسی ہے: opencode --version version number دکھاتا ہے۔ اسکرپٹ سے انسٹالیشن کے بعد command not found کا ظاہر ہونا بتاتا ہے کہ موجودہ shell نے ابھی updated PATH نہیں پڑھا۔ اس لیے opencode صارف کے طور پر log out کریں اور دوبارہ log in کریں۔

API key کو نجی فائل میں رکھیں

OpenCode کو آپ کے استعمال کردہ model provider کے لیے ایک key درکار ہوتی ہے۔ یہ key آپ کے پیسے خرچ کر سکتی ہے، اس لیے اسے password کی طرح محفوظ رکھیں۔ ایسی فائل بنائیں جسے صرف opencode user پڑھ سکے اور جس کا mode 600 ہو۔ key کو commands میں لکھنے کے بجائے اسی فائل میں رکھیں، کیونکہ commands آپ کی shell history میں محفوظ ہو سکتی ہیں:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

اس فائل میں اپنے provider کا variable درج کریں، مثلاً ANTHROPIC_API_KEY=... یا اپنے provider کے لیے اس کے مساوی variable۔ OpenCode standard provider environment variables سے values حاصل کرتا ہے۔ agent شروع کرنے سے پہلے فائل کو اپنی shell میں load کریں:

set -a; source ~/opencode.env; set +a

OpenCode میں ایک interactive متبادل بھی موجود ہے۔ TUI کے اندر /connect command provider شامل کرنے کے مراحل دکھاتی ہے اور credential کو user کی home directory میں ~/.local/share/opencode/auth.json میں محفوظ کرتی ہے۔ اگر آپ یہ طریقہ استعمال کریں تو chmod 600 ~/.local/share/opencode/auth.json سے تصدیق کریں کہ فائل private ہے۔ دونوں طریقے key کو command lines سے باہر رکھتے ہیں؛ ایک طریقہ منتخب کریں اور اسی پر مستقل رہیں۔

tmux کے اندر OpenCode شروع کریں

tmux ہی VPS setup کو مفید بناتا ہے، کیونکہ SSH connection ختم ہونے کے بعد بھی tmux session چلتا رہتا ہے۔ ایک session شروع کریں، اپنے project directory میں جائیں، اور agent لانچ کریں:

tmux new -s opencode
cd ~/my-project
opencode

آپ کو TUI کھلا ہوا نظر آنا چاہیے۔ نیچے prompt اور interface میں اپنے project کا نام دکھائی دے گا۔ اسے عام زبان میں task دیں۔ یہ files پڑھنا اور تبدیلیاں تجویز کرنا شروع کر دے گا۔ جب آپ باہر نکلنا چاہیں تو Ctrl-b پھر d دبا کر detach کریں۔ اس کے بعد آپ کا laptop بند ہونے پر بھی agent کام کرتا رہے گا۔ بعد میں اس سے دوبارہ attach ہونے کے لیے یہ command چلائیں:

tmux attach -t opencode

session، گفتگو اور چل رہا task اسی جگہ موجود رہیں گے جہاں آپ نے انہیں چھوڑا تھا۔ یہ آپ کے connection منقطع ہونے کے بعد بھی برقرار رہتا ہے، لیکن server reboot کے بعد نہیں۔ اس لیے reboot کے بعد اسی طریقے سے نیا tmux session شروع کریں۔ آپ دوسری tmux window کھول کر پہلے agent کے ساتھ ایک اور agent بھی چلا سکتے ہیں۔ تاہم OpenCode sessions ایک دوسرے سے الگ رہتے ہیں، جبکہ اسی machine پر Claude Code sessions ایک دوسرے کو messages بھیج سکتے ہیں۔ یہ task کو 2 حصوں میں تقسیم کرنے کا مختلف طریقہ ہے۔

اسے کسی model سے منسلک کریں

OpenCode provider agnostic ہے۔ یہ AI SDK اور Models.dev catalog استعمال کرتے ہوئے 75 سے زیادہ providers کو support کرتا ہے، اس لیے یہی tool Anthropic، OpenAI، Google اور درجنوں دیگر providers کے ساتھ کام کرتا ہے، جن میں local servers بھی شامل ہیں۔ فوری طریقہ TUI کے اندر /connect command ہے، جو providers کی فہرست دکھاتا ہے اور credential کا انتظام کرتا ہے۔ ایسی setup کے لیے جسے commit اور دوبارہ reproduce کیا جا سکے، project root میں opencode.json رکھیں اور model کو provider/model-id کے طور پر set کریں:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

Local model بھی اسی file کے ذریعے کام کرتا ہے، کیونکہ ہر OpenAI-compatible server کو provider کے طور پر declare کیا جا سکتا ہے۔ اگر آپ اسی VPS پر Ollama کے ذریعے model serve کرتے ہیں تو config اس کے local API کی طرف اشارہ کرتی ہے، اور model name وہی ہوگا جو ollama list آپ کے system پر دکھاتا ہے:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

شروع ہی سے ایک built-in طریقہ اپنانا مفید ہے۔ OpenCode میں دو agents شامل ہیں، جن کے درمیان Tab key سے switch کیا جا سکتا ہے: Build، جو default agent ہے اور اسے مکمل access حاصل ہے؛ اور Plan، جو تبدیلیاں کرنے کی صلاحیت disable کر دیتا ہے۔ نیا task Plan میں شروع کریں، اسے code پڑھنے اور طریقہ تجویز کرنے دیں، اور صرف اس وقت Build پر switch کریں جب آپ plan سے متفق ہوں۔ Server پر read-only ابتدائی جائزہ ایک سستا حفاظتی اقدام ہے۔ Claude Code اسی فیصلے کو agents کے بجائے permission modes کے طور پر پیش کرتا ہے، اور اس کے default کے طور پر auto mode پر منتقل ہونے کے بارے میں پڑھنا مفید ہے اگر آپ دونوں tools چلاتے ہیں، کیونکہ session جس mode میں شروع ہوتا ہے وہ طے کرتا ہے کہ بغیر نگرانی کے agent کتنی تبدیلیاں کر سکتا ہے۔

اس نقصان کی حد، حقیقتاً

Coding agent غیر فعال نہیں ہوتا، اس لیے واضح طور پر بتائیں کہ یہ setup کن چیزوں کو محدود کرتا ہے اور کن چیزوں کو نہیں۔ یہ file damage کو محدود کرتا ہے: opencode user اپنے home directory کا مالک ہے، کسی اور چیز کا نہیں، اس لیے edits اور deletions اسی حد پر رک جاتے ہیں۔ یہ credential exposure کو بھی محدود کرتا ہے: key ایک ہی file میں mode 600 کے ساتھ، ایک ہی account کے اندر موجود ہے۔ لیکن یہ ان کاموں کو محدود نہیں کرتا جو account قانونی طور پر انجام دے سکتا ہے۔ اگر project directory میں production deploy credentials موجود ہوں تو agent انہیں استعمال کر سکتا ہے۔ ان credentials کو agent کے account سے مکمل طور پر باہر رکھیں۔

OpenClaw جیسے gateway agent کے برعکس، OpenCode ایک interactive terminal program ہے، daemon نہیں۔ یہ کوئی listening port نہیں کھولتا اور اس کی کوئی long-running service نہیں ہوتی۔ اس لیے agent کے لیے کوئی systemd unit لکھنے یا اس کے لیے کسی port کو firewall میں محدود کرنے کی ضرورت نہیں۔ Containment کی بنیاد user account اور project directory ہیں، اسی لیے اس guide کا پہلا section سب سے زیادہ اہم ہے۔

اس کے اردگرد موجود server کو پھر بھی معمول کی security درکار ہے، کیونکہ coding VPS اب بھی public server ہوتا ہے: root login disabled کے ساتھ key-only SSH، جیسا کہ VPS پر SSH hardening میں بیان کیا گیا ہے، default-deny firewall، اور باقاعدہ updates۔ Agent کی تیار کردہ تبدیلیوں کا بھی جائزہ لیں۔ انہیں push کرنے سے پہلے diffs پڑھیں، بالکل اسی طرح جیسے کسی نئے contributor کی pull request پڑھتے ہیں، کیونکہ نتیجہ deploy آپ ہی کرتے ہیں۔

آخر میں خود tool کو بھی تازہ رکھیں۔ OpenCode کثرت سے releases جاری کرتا ہے، اور updates ایسے fixes لاتی ہیں جو server پر commands چلانے والے program کے لیے اہم ہوتے ہیں۔ Update اسی طریقے سے کریں جس سے اسے install کیا تھا: opencode user کے طور پر install script دوبارہ چلائیں، یا اگر npm کے ذریعے install کیا تھا تو sudo npm update -g opencode-ai چلائیں، پھر opencode --version سے نئی version کی تصدیق کریں۔ وقتاً فوقتاً ایک منٹ کی maintenance، کئی ماہ پرانی build کے پہلے ہی حل کیے گئے مسئلے کے behavior کو debug کرنے سے سستی ہوتی ہے۔

FAQ

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

ہاں۔ OpenCode کسی بھی OpenAI-compatible server کو provider سمجھتا ہے، اس لیے اسی VPS پر Ollama کے ذریعے فراہم کیا جانے والا model کام کرتا ہے۔ opencode.json میں provider کو local baseURL اور Ollama کے رپورٹ کردہ model name کے ساتھ declare کریں۔ مسئلہ hardware کا ہے، کیونکہ حقیقی coding کام کے لیے کافی اچھے model کو خاصی memory درکار ہوتی ہے۔ اس لیے model download کرنے سے پہلے server کا سائز اس کے مطابق مقرر کریں۔

laptop بند کرنے کے بعد OpenCode کو کیسے چلتا رکھوں؟

اسے VPS پر tmux کے اندر چلائیں۔ tmux new -s opencode کے ذریعے agent کو named session میں شروع کریں، Ctrl-b پھر d دبا کر detach کریں۔ SSH connection ختم ہونے کے بعد بھی session server پر چلتا رہے گا۔ tmux attach -t opencode کے ذریعے کسی بھی وقت دوبارہ attach کریں؛ conversation اور چلتا ہوا task وہیں موجود ہوگا۔ server reboot ہونے سے session ختم ہو جاتا ہے، اس لیے reboot کے بعد نیا session شروع کریں۔

کیا OpenCode کو میرے VPS پر commands چلانے دینا محفوظ ہے؟

اگر اسے محدود رکھا جائے تو یہ قابل انتظام ہے۔ OpenCode کے لیے ایک dedicated unprivileged user بنائیں جسے sudo حاصل نہ ہو۔ اس کے projects کو git میں رکھیں تاکہ ہر edit واپس کی جا سکے۔ API key کو mode 600 والی file میں محفوظ کریں۔ کسی بھی تبدیلی کی اجازت دینے سے پہلے read-only ابتدائی جائزے کے لیے اس کے Plan agent کو استعمال کریں، پھر Build agent کو تبدیلیاں کرنے دیں۔ اس طرح agent صرف ان چیزوں کو نقصان پہنچا سکتا ہے جن کی ملکیت اس کے اپنے account کے پاس ہے، جبکہ server کا باقی حصہ اس کی دسترس سے باہر رہتا ہے۔

OpenCode اور Claude Code میں کیا فرق ہے؟

OpenCode open source (MIT) ہے اور provider agnostic ہے۔ یہ ایک ہی interface کے ذریعے 75 سے زیادہ model providers، بشمول local providers، سے connect ہوتا ہے۔ Claude Code، Anthropic کا اپنا terminal agent ہے جو Anthropic کے models کے لیے بنایا گیا ہے۔ اگر آپ متعدد providers کے لیے ایک ہی tool، یا local model کے ساتھ مکمل self-hosted stack چاہتے ہیں تو OpenCode موزوں ہے۔ دونوں VPS پر tmux کے اندر اسی unprivileged-user setup کے ساتھ اچھی طرح چلتے ہیں۔