Agentbox کو تعینات کرنے اور اپنے براؤزر سے Claude Code یا Codex چلانے کا طریقہ

Agentbox کیا ہے؟

Agentbox ایک self-hosted ماحول ہے جو براؤزر سے Claude Code اور Codex CLI چلانے کے لیے استعمال ہوتا ہے۔ یہ AI چیٹ، ٹرمینل، پروجیکٹ فائلز، Git جائزہ، اکاؤنٹ انتظامیہ، اور استعمال کی نگرانی کو آپ کے اپنے سرور پر hosted مستقل ورک اسپیسز میں یکجا کرتا ہے۔

سرور ایک واحد Go بائنری کے طور پر تقسیم کیا جاتا ہے جس میں TypeScript فرنٹ اینڈ شامل ہوتا ہے۔ یہ ایپلیکیشن کی حالت اور چیٹ کی تاریخ SQLite میں محفوظ کرتا ہے اور coding ورک اسپیسز کو الگ رکھنے کے لیے Docker کنٹینرز استعمال کرتا ہے۔ مستقل ڈائریکٹریز کنٹینر کے lifecycle سے آزاد ہو کر پروجیکٹ فائلز، home configuration، اور مشترکہ وسائل محفوظ رکھتی ہیں۔

Agentbox خاص طور پر اس وقت مفید ہے جب آپ ایک ڈیوائس پر coding task شروع کرنا اور ماحول دوبارہ بنائے بغیر کسی دوسری جگہ سے اسے جاری رکھنا چاہتے ہوں۔ آپ task-oriented کام کے لیے streaming Web چیٹ استعمال کر سکتے ہیں یا اصل Claude Code یا Codex CLI کے ساتھ براہِ راست کام کرنے کے لیے browser terminal کھول سکتے ہیں۔

اہم خصوصیات

• مستقل ورک اسپیسز: پروجیکٹ فائلز، home configuration، مشترکہ فائلز، اور چیٹ کی تاریخ آپ کے سرور پر برقرار رہتی ہیں۔
• دو agent انٹرفیسز: براؤزر چیٹ اور اصل command-line ٹولز کے درمیان تبدیل ہوں۔
• مربوط delivery workflow: پروجیکٹ upload یا clone کریں، task تفویض کریں، فائلز کا معائنہ کریں، Git diffs کا جائزہ لیں، اور نتیجہ commit یا download کریں۔
• مرکزی اکاؤنٹ pool: منتظمین Claude اور Codex OAuth subscriptions، API keys، relay endpoints، access scopes، اور egress proxies ترتیب دے سکتے ہیں۔
• استعمال اور لاگت کے ریکارڈز: صارف، model، اور وقت کے لحاظ سے استعمال filter کریں اور tokens، pricing sources، latency، اور ریکارڈ شدہ اخراجات کا معائنہ کریں۔
• قابلِ استعمال وسائل: ہر صارف کو ایک مشترکہ directory ملتی ہے جو اس کے تمام ورک اسپیسز میں /shared کے طور پر mount ہوتی ہے۔ Home templates، Claude skills، اور MCP configuration بھی معاونت یافتہ ہیں۔
• اختیاری private-network رسائی: abox-link client واضح طور پر اجازت دی گئی repositories، databases، اور services کو cloud-hosted ورک اسپیسز کے لیے دستیاب کر سکتا ہے۔
• Responsive interface: console deep links، light اور dark themes، اور mobile layouts کو support کرتا ہے۔

Architecture سمجھیں

آپ کا براؤزر HTTP یا HTTPS اور WebSocket connections کے ذریعے Agentbox سرور سے connect ہوتا ہے۔ سرور local Docker API کے ذریعے workspace containers کو control کرتا ہے اور application records کو SQLite میں محفوظ کرتا ہے۔ ہر workspace کا اپنا container اور persistent directories ہوتی ہیں۔

ایک workspace میں متعدد chat threads ہو سکتے ہیں، اگرچہ اس workspace میں ایک وقت میں صرف ایک Web chat turn چلتا ہے۔ اہم persistent locations /workspace، /home/agent، اور /shared ہیں۔ وہ فائلز جو container replacement کے بعد بھی برقرار رہنی چاہئیں، ان میں سے کسی location میں محفوظ کی جانی چاہئیں۔

اہم: Persistent files کا مطلب persistent processes نہیں ہے۔ terminal network interruption کے بعد reconnect کرنے سے tmux session بحال ہو سکتا ہے، لیکن container روکنے یا دوبارہ بنانے سے اس کے running processes ختم ہو جاتے ہیں۔

ضروریات

تنصیب کا تیز ترین طریقہ systemd والے Linux server کے لیے ہے۔ Release packages Linux x86_64 اور arm64 کو support کرتے ہیں۔

• Ubuntu 22.04 یا اس کے بعد کے ورژن، یا Debian 12 یا اس کے بعد کے ورژن، missing dependencies اور Docker خودکار طور پر install کر سکتے ہیں۔
• دیگر Linux distributions کو Python 3.9 یا اس کے بعد کا ورژن، Git، curl، CA certificates، timezone data، اور local Docker Engine درکار ہیں۔
• پہلی workspace image build کے لیے container registries، Debian package repositories، اور npm تک رسائی درکار ہے۔
• Remote access کے لیے TCP port 8180 کو server firewall یا security group کے ذریعے اجازت یافتہ ہونا چاہیے، جب تک کہ آپ SSH forwarding یا reverse proxy استعمال نہ کریں۔

Prebuilt installations کے لیے server پر Go یا Node.js کی ضرورت نہیں ہوتی۔

Release installer کے ذریعے Agentbox انسٹال کریں

1. Installer چلائیں

Linux server سے connect کریں اور یہ command چلائیں:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

Installer بطورِ ڈیفالٹ تازہ ترین stable release منتخب کرتا ہے۔ README میں v0.1.5 کو موجودہ stable release کے طور پر درج کیا گیا ہے۔ اس version کو مقرر کرنے کے لیے یہ command استعمال کریں:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --version v0.1.5

تنصیب کا عمل release package کی تصدیق کرتا ہے، مقررہ tool versions کے ساتھ workspace image بناتا ہے، configuration بناتا ہے، random administrator password تیار کرتا ہے، اور agentbox.service شروع کرتا ہے۔ ابتدائی image build میں کئی منٹ لگ سکتے ہیں۔

2. Console کھولیں

تنصیب مکمل ہونے پر terminal میں دکھایا گیا administrator password نوٹ کریں۔ درج ذیل address کھولیں اور placeholder کی جگہ server address لکھیں:

http://YOUR_SERVER_IP:8180

Username boxadmin اور تیار کردہ password سے sign in کریں۔ Agentbox کو مستقل عوامی استعمال کے لیے دستیاب کرنے سے پہلے HTTPS configure کریں۔

3. Agentbox کو reverse proxy تک محدود کریں

اگر Agentbox کو صرف local connections قبول کرنے چاہئیں تو installation کے دوران listen option شامل کریں:

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --listen 127.0.0.1:8180

اس کے بعد آپ service کے سامنے WebSocket support والا HTTPS reverse proxy رکھ سکتے ہیں۔ Release installations configuration کو /etc/agentbox میں اور application data کو /var/lib/agentbox میں محفوظ کرتی ہیں۔

Claude یا Codex اکاؤنٹ configure کریں

Sign in کرنے کے بعد System settings → Account pool کھولیں، جو موجودہ چینی interface میں 系统设置 → 账号池 کے طور پر دکھایا گیا ہے۔ Claude یا Codex میں سے کوئی ایک account شامل کریں۔

Agentbox کنکشن کے درج ذیل طریقوں کو سپورٹ کرتا ہے:

• Claude سبسکرپشن: Subscription OAuth منتخب کریں اور اجازت دینے والا کوڈ پیسٹ کریں۔
• Codex سبسکرپشن: Subscription OAuth منتخب کریں اور مکمل callback URL پیسٹ کریں۔
• API یا relay اکاؤنٹ: فراہم کنندہ کا endpoint اور key درج کریں۔ Codex relay کو فراہم کنندہ کے متوقع پروٹوکول سے مطابقت رکھنی چاہیے۔

ایک قابل شناخت اکاؤنٹ نام، ضرورت پڑنے پر اس کا egress proxy، اور رسائی کا دائرہ مقرر کریں۔ اکاؤنٹ تمام صارفین، منتخب صارفین، یا صرف منتظمین کے لیے دستیاب ہو سکتا ہے۔ منتظمین ہر تشکیل شدہ اکاؤنٹ استعمال کر سکتے ہیں۔

ٹرمینل رسائی رکھنے والے ورک اسپیس صارفین اپنے containers کے اندر command-line tools کو فراہم کردہ credentials پڑھ سکتے ہیں۔ اس لیے مشترکہ اکاؤنٹ pools کو قابل اعتماد صارفین تک محدود رکھنا چاہیے۔ رسائی منسوخ کرنے سے نئی کارروائیاں اور credentials کی ہم وقت سازی رک جاتی ہے، لیکن مکمل منسوخی کے لیے متاثرہ containers کو روکنا اور upstream credentials کو تبدیل کرنا بھی ضروری ہو سکتا ہے۔

اپنا پہلا ورک اسپیس بنائیں

1. ایک ورک اسپیس بنائیں اور اسے وضاحتی نام دیں۔
2. Claude Code یا Codex CLI کو agent کے طور پر منتخب کریں۔
3. ایسا اکاؤنٹ منتخب کریں جسے آپ کا صارف استعمال کرنے کا مجاز ہو۔
4. Files کے ذریعے اپ لوڈ کر کے یا Terminal میں clone کر کے project درآمد کریں۔
5. Chat کھولیں اور coding کا واضح کام جمع کریں۔
6. ترمیم شدہ فائلوں کا معائنہ کریں اور Changes کے تحت Git diff کا جائزہ لیں۔
7. تبدیلیاں مقامی طور پر commit کریں یا project فائلیں ڈاؤن لوڈ کریں۔

Project فائلیں اپ لوڈ اور معائنہ کریں

Files interface project اور مشترکہ directories کے لیے directory tree، uploads، editing، previews، اور archive downloads فراہم کرتا ہے۔ Source viewer میں line numbers، syntax highlighting، line اور column navigation، موجودہ لائن کی highlighting، اور fullscreen mode شامل ہیں۔

Web file operations محدود directory handles استعمال کرتی ہیں اور symbolic links کو follow نہیں کرتیں۔ Uploads کی عارضی directories میں توثیق کی جاتی ہے، اور editor saves atomic replacement استعمال کرتے ہیں۔ Container کے اندر command-line tools اب بھی templates کے ذریعے فراہم کردہ links استعمال کر سکتے ہیں۔

Terminal سے repository clone کریں

Terminal کھولیں اور معمول کے shell commands چلائیں۔ مثال کے طور پر:

cd /workspace
git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
git status

Agentbox اپنی workspace image میں اصل agent CLIs اور عام development tools شامل کرتا ہے۔ Terminal sessions tmux استعمال کرتی ہیں، اس لیے browser یا network کے منقطع ہونے کے بعد آپ دوبارہ منسلک ہو سکتے ہیں۔

Web chat میں کام تفویض کریں

Chat کھولیں اور مطلوبہ تبدیلی، متعلقہ پابندیوں، اور متوقع validation کی وضاحت کریں۔ مثال کے طور پر:

Inspect this project and add input validation to the user registration endpoint. Preserve the existing API response format, add tests for invalid email addresses, and run the relevant test suite.

Chat model اور reasoning-effort کے انتخاب کو سپورٹ کرتا ہے۔ ہر response میں اس کا وقت، model، settings snapshot، اور cost درج ہوتی ہے۔ Claude streaming headless turns چلاتا ہے۔ Codex اپنی app-server integration کو ترجیح دیتا ہے اور handshake ناکام ہونے کی صورت میں execution mode پر آ جاتا ہے۔

نتیجے کا جائزہ لیں اور اسے فراہم کریں

Agent کے مکمل ہونے کے بعد، ترمیم شدہ فائلوں اور رنگین diffs کا معائنہ کرنے کے لیے Changes کھولیں۔ جب diff میں کافی context نہ ہو تو مکمل فائل کا جائزہ لیں۔

Web commits مقامی ہوتے ہیں اور خودکار طور پر remote repository پر push نہیں ہوتے۔ یہ Git hooks یا signing بھی نہیں چلاتے۔ جب hooks یا signed commits درکار ہوں تو terminal استعمال کریں۔

Agentbox repository connections، cloning، fetching، fast-forward pulls، previewed pushes، branch operations، اور GitHub یا GitLab pull request اور merge request بنانے کے لیے Git management بھی فراہم کرتا ہے۔ Repository connections HTTPS tokens یا SSH private keys استعمال کر سکتے ہیں۔

Source سے build اور run کریں

Source workflow اس وقت استعمال کریں جب آپ Agentbox میں ترمیم کرنے یا project میں تعاون دینے کا ارادہ رکھتے ہوں۔ دستاویزی build environment میں Docker کے ساتھ Linux، Go 1.26.6 یا compatible automatic toolchain، Git، Python 3، curl، iproute2، اور OpenSSL شامل ہیں۔ Node.js 22 اور npm صرف main TypeScript console میں ترمیم کرتے وقت درکار ہوتے ہیں۔

1. Clone اور build کریں

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox

go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh

Image build چلانے والے صارف کو Docker تک رسائی درکار ہے۔ Startup کے وقت server کو mounted directory کی ownership بھی 1000:1000 پر مقرر کرنی ہوگی؛ فراہم کردہ systemd service root کے طور پر چلتی ہے۔

2. Configuration بنائیں

cp config.example.json config.json
openssl rand -hex 24

تیار کردہ random value کو auth_token میں کاپی کریں۔ ابتدائی test کے لیے accounts اور proxies کو خالی چھوڑیں اور بعد میں Web UI کے ذریعے حقیقی اکاؤنٹس شامل کریں۔

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

Startup سے پہلے placeholder کو تبدیل کریں، کیونکہ configuration validation اسے مسترد کر دیتی ہے۔

3. Server شروع کریں

sudo ./agentbox -config config.json

ایسے server کے لیے جو صرف localhost پر listen کرے، اپنے computer سے SSH tunnel بنائیں:

ssh -N -L 8180:127.0.0.1:8180 user@your-server

مقامی طور پر http://127.0.0.1:8180 کھولیں اور boxadmin اور ترتیب دیے گئے auth_token کے ساتھ سائن اِن کریں۔ منتظم اکاؤنٹ بن جانے کے بعد اس کا پاس ورڈ SQLite میں محفوظ ہو جاتا ہے؛ بعد میں auth_token تبدیل کرنے سے وہ پاس ورڈ ری سیٹ نہیں ہوتا۔

4. systemd سروس انسٹال کریں

فوگراؤنڈ پراسیس روکنے کے بعد، ریپوزٹری سے سروس انسٹال اور تعینات کریں:

sudo ./deploy/install.sh
sudo ./deploy/deploy.sh

پہلی اسکرپٹ سروس اور ٹائمرز انسٹال کرتی ہے۔ دوسری بائنریز بناتی اور تبدیل کرتی ہے، سروس دوبارہ شروع کرتی ہے، اور ہیلتھ چیک انجام دیتی ہے۔

استعمال اور اخراجات کی نگرانی کریں

Usage صفحہ ماڈل کی سرگرمی ریکارڈ کرتا ہے اور منتظمین کو صارف، ماڈل اور وقت کے لحاظ سے فلٹر کرنے دیتا ہے۔ ہر ریکارڈ میں ٹوکن کا استعمال، اخراجات کے ذرائع اور تاخیر شامل ہوتی ہے۔ عام صارفین اپنے ریکارڈ دیکھ سکتے ہیں، جبکہ منتظمین تمام صارفین کے ریکارڈ دیکھ سکتے ہیں۔

قیمتوں کے کیٹلاگ models.dev سورس پری سیٹ یا حسب ضرورت HTTPS سورسز استعمال کر سکتے ہیں۔ قیمتوں کی تازہ کاریوں میں تاریخی اسنیپ شاٹس برقرار رہتے ہیں، اور حسب ضرورت قیمتیں محفوظ رہتی ہیں۔ Web ٹرنز کی قیمت اس ٹیبل کے مطابق مقرر ہوتی ہے جو ٹرن شروع ہونے پر پن کیا گیا ہو۔

کریڈٹ کی حدود حقیقی وقت کی سخت حدیں نہیں ہیں۔ Web ٹرن مکمل ہونے کے بعد اس کا حساب طے ہوتا ہے، اس لیے بیلنس ختم کرنے والا ٹرن مقررہ حد سے زیادہ خرچ کر سکتا ہے۔ بیک فل کیا گیا ٹرمینل استعمال ریکارڈ کیا جاتا ہے، لیکن کریڈٹس میں سے منہا نہیں ہوتا۔

اعلیٰ درجے کی تجاویز

ورک اسپیسز میں مشترکہ وسائل استعمال کریں

ہر صارف کی مشترکہ ڈائریکٹری اس صارف کی تمام ورک اسپیسز میں /shared پر ماؤنٹ ہوتی ہے۔ قابلِ دوبارہ استعمال اسکرپٹس، حوالہ جاتی فائلیں یا آرٹی فیکٹس ہر پروجیکٹ میں نقل کرنے کے بجائے وہاں محفوظ کریں۔ Agentbox سسٹم اور فی صارف ہوم ٹیمپلیٹس کو بھی سپورٹ کرتا ہے۔

abox-link کے ذریعے نجی سروسز تک رسائی حاصل کریں

اختیاری abox-link کلائنٹ کلاؤڈ ورک اسپیس کو آپ کے کمپیوٹر یا کسی دوسری نجی مشین سے دستیاب اجازت یافتہ سروسز تک رسائی دیتا ہے۔ یہ مقامی پینل کے ذریعے یا --server کے ساتھ کمانڈ لائن سرور موڈ میں چل سکتا ہے۔

محدود اجازت نامہ استعمال کریں اور صرف وہی ریپوزٹریز، ڈیٹابیسز یا سروسز ظاہر کریں جن کی ورک اسپیس کو ضرورت ہے۔ Agentbox کلائنٹ اور ورک اسپیس، دونوں کی کنکشن تیاری دکھاتا ہے۔ عام براؤزر استعمال کے لیے abox-link ضروری نہیں ہے۔

کنٹینر کی گنجائش کا منصوبہ بنائیں

ہر ورک اسپیس کنٹینر میں پہلے سے 2048 MiB میموری، 2 CPUs اور 512 پراسیسز ہوتے ہیں۔ سرور کی گنجائش بیک وقت چلنے والی متوقع ورک اسپیسز کی تعداد کے مطابق مقرر کریں۔ منتظمین عالمی اور فی صارف کنٹینر حدود اور مختص ڈسک اسپیس بھی ترتیب دے سکتے ہیں۔

درست ڈیٹا کا بیک اپ لیں

پہلے سے طے شدہ سسٹم بیک اپ میں ڈیٹابیس، کنفیگریشن، اکاؤنٹ کی اسناد اور ٹیمپلیٹ لیئرز شامل ہوتی ہیں، لیکن ورک اسپیس کا ڈیٹا شامل نہیں ہوتا۔ جب صارف کی فائلیں اور تاریخ بھی محفوظ کرنا مقصود ہو تو agentbox backup --full استعمال کریں۔ مکمل بیک اپ کے لیے پہلے سروس اور متعلقہ کنٹینرز روکنا ضروری ہے۔ آرکائیو کی توثیق کے لیے backup-verify اور اسے نئی ڈائریکٹری میں بحال کرنے کے لیے restore --to استعمال کریں۔

سکیورٹی کی حد کو سمجھیں

ایجنٹس ورک اسپیس کنٹینرز کے اندر کوڈ چلا سکتے ہیں۔ پہلے سے طے شدہ اجازت موڈ bypassPermissions ہے۔ کنٹینرز غیر روٹ صارف کے طور پر، وسائل کی حدود اور no-new-privileges کے ساتھ چلتے ہیں، لیکن Agentbox سرور کو خود Docker تک رسائی حاصل ہے۔ اس لیے تعیناتی اور انتظام قابلِ اعتماد آپریٹرز کے ہاتھ میں رہنا چاہیے۔

اختیاری ریموٹ براؤزر احتیاط سے استعمال کریں

Agentbox ورک اسپیس کے اندر مکمل ڈیسک ٹاپ براؤزر فراہم کر سکتا ہے، جس میں مستقل لاگ اِن حالت، ٹیبز، فل اسکرین، قابلِ تنظیم تصویر کا معیار، کلپ بورڈ سپورٹ اور ڈاؤن لوڈز شامل ہیں۔ منتظمین کو اختیاری agentbox-agent:browser امیج بنانی اور منتخب کرنی ہوگی۔ ویب سائٹ کی تصدیق Claude یا Codex CLI کی اجازت سے الگ رہتی ہے۔

یاد رکھنے کے لیے عملی حدود

• صرف ایک Agentbox پراسیس کسی مخصوص data_dir کو استعمال کر سکتا ہے۔
• موجودہ پروڈکشن آرکیٹیکچر میں ایک مشین، ایک سرور پراسیس اور مقامی Docker ڈیمون استعمال ہوتا ہے۔
• تعیناتیوں اور دوبارہ آغاز کے دوران منسلک کلائنٹس کا کنکشن مختصر وقت کے لیے منقطع ہو جاتا ہے۔
• ریموٹ Git اسٹیٹس تازہ کرنے سے fetch نہیں ہوتا؛ ahead اور behind کی قدریں مقامی کیش سے آتی ہیں۔
• اکاؤنٹ منسوخ کرنے سے پہلے سے چلتے ہوئے کنٹینر کو فراہم کی گئی اسناد حذف نہیں ہوتیں۔
• ورک اسپیس کنٹینر روکنے یا دوبارہ بنانے سے اس کے پراسیس ختم ہو جاتے ہیں، اگرچہ مستقل فائلیں برقرار رہتی ہیں۔
• Git review کسی روکی ہوئی ورک اسپیس کو شروع کر سکتا ہے اور ٹرمینل رسائی جیسی کریڈٹ اجازت کی جانچیں لاگو کرتا ہے۔

نتیجہ

Agentbox ایک Linux سرور کو Claude Code اور Codex CLI کے لیے مستقل، براؤزر پر مبنی کوڈنگ ماحول میں تبدیل کرتا ہے۔ ریلیز انسٹالر سے آغاز کریں، اکاؤنٹ شامل کریں، ورک اسپیس بنائیں، اور مربوط Files، Terminal اور Changes ویوز کے ذریعے چیٹ ٹاسک سے جائزہ لیے گئے کوڈ تک پہنچیں۔ پروڈکشن استعمال کے لیے HTTPS شامل کریں، اکاؤنٹ کی رسائی کو احتیاط سے کنٹرول کریں، وسائل کے استعمال کی نگرانی کریں، اور ضرورت پڑنے پر ورک اسپیس ڈیٹا سمیت بیک اپ کا منصوبہ بنائیں۔

مزید گہری کنفیگریشن اور عملی رہنمائی کے لیے Agentbox ریپوزٹری، دستاویزات کا اشاریہ، اور تعیناتی اور آپریشنز گائیڈ دیکھیں۔