VPS پر OpenCode کیسے انسٹال کریں

OpenCode کیا ہے، اور آپ کیا سیٹ اپ کر رہے ہیں

OpenCode ایک اوپن سورس AI کوڈنگ ایجنٹ ہے جسے ٹرمینل کے لیے بنایا گیا ہے۔ آپ اسے کسی پروجیکٹ ڈائریکٹری کے اندر شروع کرتے ہیں۔ یہ آپ کا کوڈ پڑھتا ہے، تبدیلیوں کی تجویز دیتا ہے، فائلوں کو ایڈٹ کرتا ہے، اور کمانڈز چلاتا ہے، یہ سب ٹرمینل یوزر انٹرفیس (TUI) کے ذریعے ہوتا ہے۔ یہ MIT لائسنس کے تحت دستیاب ہے اور 75 سے زیادہ ماڈل فراہم کنندگان (model providers) سے منسلک ہے۔ mid-2026 تک، تقریباً 165,000 GitHub stars کے ساتھ، یہ سب سے زیادہ اسٹارز والا اوپن سورس کوڈنگ ایجنٹ ہے۔ VPS پر OpenCode چلانے کے لیے، آپ اسے ایک مخصوص unprivileged صارف کے تحت انسٹال کرتے ہیں، اپنی ماڈل API key کو ایک پرائیویٹ فائل میں رکھتے ہیں، اور اسے tmux کے اندر شروع کرتے ہیں تاکہ کنکشن ٹوٹنے کی صورت میں سیشن برقرار رہے۔ یہ گائیڈ اسی ترتیب سے یہ تمام کام انجام دیتی ہے۔

نام کے حوالے سے ایک وضاحت الجھن سے بچاتی ہے۔ اصل ریپوزٹری anomalyco/opencode ہے، جسے Anomaly ٹیم (جسے پہلے SST کہا جاتا تھا) مینیٹین کرتی ہے، اور یہ پروجیکٹ پہلے sst/opencode پر موجود تھا۔ GitHub پر opencode-ai/opencode نام کی ایک پرانی اور غیر متعلقہ ریپوزٹری بھی موجود ہے، اس لیے یقینی بنائیں کہ آپ صحیح پروجیکٹ کی دستاویزات پڑھ رہے ہیں۔ آفیشل سائٹ opencode.ai ہے۔

VPS پر OpenCode کیوں چلائیں

Coding agent کا سیشن طویل ہوتا ہے۔ OpenCode کسی refactor یا test suite پر کام کرنے میں کئی منٹ لگا سکتا ہے۔ اگر یہ آپ کے laptop پر چل رہا ہو، تو lid بند ہونے یا Wi-Fi منقطع ہونے سے کام کے دوران ہی سیشن ختم ہو جائے گا۔ VPS پر tmux کے اندر، agent آپ کے disconnect ہونے کے بعد بھی کام جاری رکھتا ہے، اور آپ بعد میں reattach کر کے اس کا کام دیکھ سکتے ہیں۔ یہ بالکل وہی طریقہ ہے جو running Claude Code on a VPS with tmux میں استعمال ہوتا ہے۔ agent کو laptop سے VPS پر منتقل کرنے کا سب سے بڑا فائدہ یہی ہے۔

دوسری وجہ اس کی جگہ (placement) ہے۔ VPS اس کوڈ کے قریب ہوتا ہے جسے آپ deploy کرتے ہیں: repository، build tools، test database، اور اکثر staging environment پہلے سے وہیں یا اس کے قریب موجود ہوتے ہیں۔ وہ agent جو کوڈ ایڈٹ کرتا ہے اور tests چلاتا ہے، اس مشین پر بہترین کام کرتا ہے جہاں وہ tests درحقیقت چلتے ہیں۔ چونکہ یہ server آپ کے کنٹرول میں ہوتا ہے، اس لیے آپ agent کو جان بوجھ کر ایک محدود (contained) environment دے سکتے ہیں، جس کا ذکر اگلے section میں کیا گیا ہے۔

اگر آپ ابھی بھی کسی tool کا انتخاب کر رہے ہیں، تو running a coding AI agent on a VPS میں Aider اور Goose سمیت دیگر options کا موازنہ کیا گیا ہے۔

OpenCode کے لیے علیحدہ صارف بنائیں

حقیقت یہ ہے: ایک کوڈنگ ایجنٹ فائلوں میں ترمیم کرتا ہے اور کمانڈز چلاتا ہے۔ یہ اس کا کام ہے، اور یہی خطرہ بھی ہے۔ OpenCode بلڈز، ٹیسٹ اور وہ تمام shell commands چلا سکتا ہے جن کی کام کے دوران ضرورت ہو، اور ماڈل کا فیصلہ درست ہوتا ہے لیکن مکمل طور پر درست نہیں ہوتا۔ ایجنٹ جس اکاؤنٹ سے چلتا ہے، وہ اس کی حد (ceiling) ہے کہ کوئی غلط کمانڈ کتنا نقصان پہنچا سکتی ہے، اس لیے اسے root کے طور پر نہ چلائیں، اور نہ ہی اسے اسی صارف کے طور پر چلائیں جو سرور کا ایڈمنسٹریٹر ہے۔

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

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

جن پر آپ اسے کام کرنے کے لیے استعمال کرنا چاہتے ہیں، ان پروجیکٹس کو /home/opencode کے تحت رکھیں، اور انہیں اسی صارف کے ذریعے کلون (clone) کریں۔ اس اکاؤنٹ کو sudo کے حقوق نہ دیں۔ اگر ایجنٹ کوئی تباہ کن (destructive) کمانڈ چلا دیتا ہے، تو وہ صرف اسی چیز کو نقصان پہنچا سکے گا جس کا مالک یہ اکاؤنٹ ہے، یہی وہی منطق ہے جو running services as an unprivileged user میں استعمال ہوتی ہے۔ کام کے لیے git repository کا استعمال بھی کریں، کیونکہ ریپوزٹری کسی بھی غلط ترمیم کو نقصان کے بجائے git revert میں بدل دیتی ہے۔

OpenCode انسٹال کریں

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

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

یہاں بھی وہی عام curl | bash اصول لاگو ہوتا ہے جو ہر جگہ ہوتا ہے: کسی بھی اہم سرور پر، پہلے اسکرپٹ ڈاؤن لوڈ کریں، اسے پڑھیں، اور پھر اسے چلائیں۔ انسٹالیشن کے بعد، ایک نیا shell شروع کریں تاکہ انسٹالر کے ذریعے کیا گیا PATH تبدیلی لاگو ہو سکے، پھر بائنری کو چیک کرنے کے لیے یہ کمانڈز استعمال کریں:

opencode --version

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

sudo npm install -g opencode-ai

دونوں طریقوں میں، چیک کرنے کا طریقہ ایک ہی ہے: opencode --version ورژن نمبر پرنٹ کرتا ہے۔ اگر اسکرپٹ انسٹالیشن کے بعد command not found آئے، تو اس کا مطلب ہے کہ موجودہ shell نے ابھی تک اپ ڈیٹ شدہ PATH نہیں پڑھا ہے۔ اس صورت میں، opencode صارف کے طور پر log out کریں اور دوبارہ log in کریں۔

Put the API key in a private file

OpenCode needs a key for whatever model provider you use, and that key can spend your money, so treat it like a password. Create a file only the opencode user can read, with mode 600, and keep the key there instead of typing it into commands where it would land in your shell history:

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

Put your provider's variable in it, for example ANTHROPIC_API_KEY=... or the equivalent for your provider, because OpenCode picks up the standard provider environment variables. Load the file into your shell before you start the agent:

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

OpenCode also has an interactive alternative: the /connect command inside the TUI walks you through adding a provider and saves the credential to ~/.local/share/opencode/auth.json in the user's home. If you use that route, confirm the file is private with chmod 600 ~/.local/share/opencode/auth.json. Both routes keep the key out of your command lines; pick one and stay consistent.

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

tmux اس VPS سیٹ اپ کو مفید بناتا ہے کیونکہ tmux session آپ کے SSH کنکشن ختم ہونے کے بعد بھی چلتا رہتا ہے۔ ایک session شروع کریں، اپنے پروجیکٹ کے فولڈر میں جائیں، اور agent کو لانچ کریں:

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

آپ کو TUI نظر آنا چاہیے جس کے نیچے ایک prompt اور انٹرفیس میں آپ کے پروجیکٹ کا نام ہوگا۔ اسے سادہ زبان میں کوئی کام دیں، اور یہ فائلوں کو پڑھنا اور تبدیلیوں کی تجویز دینا شروع کر دے گا۔ جب آپ نکلنا چاہیں، تو Ctrl-b کے بعد d دبا کر detach کریں، اور آپ کا laptop بند ہونے کے باوجود agent کام کرتا رہے گا۔ بعد میں دوبارہ reattach کرنے کے لیے یہ استعمال کریں:

tmux attach -t opencode

Session، گفتگو، اور کوئی بھی چلنے والا کام بالکل اسی حالت میں ہوگا جہاں آپ نے اسے چھوڑا تھا۔ یہ آپ کے disconnection سے محفوظ رہتا ہے، لیکن server reboot ہونے پر نہیں، اس لیے reboot کے بعد اسی طرح ایک نیا tmux session شروع کریں۔

اسے ایک ماڈل کے ساتھ منسلک کریں

OpenCode کسی خاص فراہم کنندہ (provider) تک محدود نہیں ہے۔ یہ 75 سے زیادہ فراہم کنندگان کو سپورٹ کرنے کے لیے AI SDK اور Models.dev کیٹلاگ کا استعمال کرتا ہے۔ اس طرح یہی ٹول Anthropic، OpenAI، Google اور مقامی سرورز سمیت درجنوں دیگر کے ساتھ کام کرتا ہے۔ سب سے تیز طریقہ TUI کے اندر /connect کمانڈ کا استعمال ہے، جو فراہم کنندگان کی فہرست دکھاتا ہے اور credentials کو سنبھالتا ہے۔ ایسی سیٹنگ کے لیے جسے آپ commit اور دوبارہ استعمال کر سکیں، پروجیکٹ کی روٹ ڈائریکٹری میں opencode.json رکھیں اور ماڈل کو provider/model-id کے طور پر سیٹ کریں:

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

مقامی ماڈل بھی اسی فائل کے ذریعے کام کرتا ہے، کیونکہ کسی بھی OpenAI-compatible سرور کو فراہم کنندہ کے طور پر استعمال کیا جا سکتا ہے۔ اگر آپ اسی VPS پر Ollama کے ذریعے ماڈل چلا رہے ہیں، تو کنفیگریشن اس کے مقامی API کی طرف اشارہ کرتی ہے، اور ماڈل کا نام وہی ہوگا جو آپ کے سسٹم پر ollama list دکھاتا ہے:

{
  "$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" } }
    }
  }
}

پہلے دن سے ہی ایک عادت اپنانا فائدہ مند ہے۔ OpenCode میں دو ایجنٹس شامل ہیں جن کے درمیان آپ Tab key کے ذریعے سوئچ کر سکتے ہیں: Build، جو مکمل رسائی والا ڈیفالٹ ایجنٹ ہے، اور Plan، جو تبدیلی کرنے کی صلاحیت کو غیر فعال کر دیتا ہے۔ Plan میں نیا کام شروع کریں، اسے کوڈ پڑھنے اور طریقہ کار تجویز کرنے دیں، اور صرف تب Build پر سوئچ کریں جب آپ پلان سے متفق ہوں۔ سرور پر، پہلے مرحلے میں صرف پڑھنے (read-only) کی صلاحیت رکھنا ایک محفوظ طریقہ ہے۔

Blast radius کا حقیقت پسندانہ جائزہ

Coding agent غیر فعال (passive) نہیں ہوتا، اس لیے یہ واضح طور پر سمجھنا ضروری ہے کہ یہ setup کیا کر سکتا ہے اور کیا نہیں۔ اس میں file damage کا خطرہ شامل ہے: opencode user صرف اپنے home directory کا مالک ہے، اس لیے edits اور deletions اسی حد تک محدود رہیں گی۔ اس میں credential exposure کا خطرہ بھی شامل ہے: key صرف ایک فائل میں موجود ہے جس کا 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 لکھنے یا firewall میں port block کرنے کی ضرورت نہیں ہے۔ Containment کا طریقہ کار user account اور project directory ہے، اسی وجہ سے اس guide کا پہلا حصہ سب سے اہم ہے۔

اس کے گرد حفاظتی حصار (box) کو اب بھی معیاری دیکھ بھال کی ضرورت ہے، کیونکہ coding VPS اب بھی ایک public server ہے: SSH hardening on a VPS کی طرح root login کو disable کریں اور صرف key-only SSH استعمال کریں، default-deny firewall لگائیں، اور routine updates کرتے رہیں۔ اور agent جو کچھ produce کرتا ہے اس کا جائزہ لیں۔ code push کرنے سے پہلے اس کے diffs کو پڑھیں، بالکل اسی طرح جیسے آپ کسی نئے contributor کے pull request کو پڑھتے ہیں، کیونکہ result deploy کرنے والے آپ خود ہیں۔

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

FAQ

کیا OpenCode پیڈ API کے بجائے لوکل ماڈل استعمال کر سکتا ہے؟

جی ہاں۔ OpenCode کسی بھی OpenAI-compatible سرور کو فراہم کنندہ (provider) کے طور پر تسلیم کرتا ہے۔ اس لیے اسی VPS پر Ollama کے ذریعے چلایا جانے والا ماڈل کام کر سکتا ہے۔ اس کے لیے opencode.json میں provider کا نام، لوکل baseURL، اور Ollama کا بتایا ہوا ماڈل نام درج کریں۔ اہم مسئلہ ہارڈ ویئر کا ہے، کیونکہ کوڈنگ کے لیے موزوں ماڈل کو زیادہ میموری کی ضرورت ہوتی ہے۔ اس لیے ماڈل ڈاؤن لوڈ کرنے سے پہلے سرور کی صلاحیت کا اندازہ لگا لیں۔

لیپ ٹاپ بند کرنے کے بعد بھی OpenCode کو کیسے چلتا ہوا رکھا جائے؟

اسے VPS پر tmux کے اندر چلائیں۔ tmux new -s opencode کے ذریعے ایک نامیڈ (named) سیشن میں ایجنٹ شروع کریں، پھر Ctrl-b اور d کے ساتھ اسے ڈیٹیک (detach) کر دیں۔ آپ کے SSH کنکشن ختم ہونے کے بعد بھی سیشن سرور پر چلتا رہے گا۔ tmux attach -t opencode کے ذریعے کسی بھی وقت دوبارہ کنیکٹ (reattach) کریں، آپ کی گفتگو اور جاری کام وہیں موجود ہوں گے۔ سرور ریبوٹ ہونے پر سیشن ختم ہو جاتا ہے، اس لیے ریبوٹ کے بعد نیا سیشن شروع کریں۔

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

اگر آپ اسے محدود رکھیں تو یہ قابلِ انتظام ہے۔ OpenCode کو ایک الگ غیر-اعلیٰ (unprivileged) یوزر دیں جس کے پاس sudo کی اجازت نہ ہو، اپنے پروجیکٹس کو git میں رکھیں تاکہ ہر تبدیلی کو واپس (reverse) کیا جا سکے، API key کو 600 موڈ والی فائل میں محفوظ کریں، اور Build agent کو کچھ بھی تبدیل کرنے کی اجازت دینے سے پہلے اس کے Plan agent کو صرف پڑھنے (read-only) کے لیے استعمال کریں۔ اس طرح ایجنٹ صرف اسی چیز کو نقصان پہنچا سکے گا جس کا وہ خود مالک ہے، اور باقی سرور محفوظ رہے گا۔

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

OpenCode اوپن سورس (MIT) ہے اور یہ کسی خاص فراہم کنندہ تک محدود نہیں ہے۔ یہ ایک ہی انٹرفیس کے ذریعے 75 سے زیادہ ماڈل فراہم کنندگان، بشمول لوکل ماڈلز، سے منسلک ہو سکتا ہے۔ Claude Code، Anthropic کے اپنے ماڈلز کے لیے بنایا گیا ایک ٹرمینل ایجنٹ ہے۔ اگر آپ کو بہت سے فراہم کنندگان کے لیے ایک ہی ٹول چاہیے، یا لوکل ماڈل کے ساتھ مکمل خود مختار (self-hosted) سسٹم چاہیے، تو OpenCode بہترین ہے۔ دونوں ہی VPS پر tmux کے اندر اسی غیر-اعلیٰ یوزر سیٹ اپ کے ساتھ بہتر کام کرتے ہیں۔