SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

VPS پر Rakazo self-host کریں: اپنا AI bot چلائیں

VPS پر Rakazo چلائیں: Node 22، pnpm، Postgres اور Graphile Worker کو Docker Compose میں ترتیب دیں، sandbox provider، keys اور حقیقی server sizing سمجھیں۔

Rakazo کی self-hosting میں اصل میں کیا چلتا ہے

Rakazo کی self-hosting کا مطلب ہے کہ ایک Linux سرور پر پانچ چیزیں چلائی جائیں: PostgreSQL، Graphile Worker process، API، web app، اور ایک sandbox container جو bots کے computer کے طور پر کام کرتا ہے۔ Rakazo، Grok Bot کا open-source متبادل ہے، جسے elie222 نے Apache 2.0 licence کے تحت شائع کیا ہے۔ ہر bot کو اپنی conversations، memory، routines اور history ملتی ہے۔ یہ workspace کے دوسرے bots کے ساتھ ایک Team Computer شیئر کرتا ہے، الا یہ کہ اسے Private Computer دیا جائے۔ یہ ہم مرتبہ bots یا مختصر مدت کے subagents بھی شروع کر سکتا ہے۔ اگر اس جملے میں memory، subagent اور tool call جیسے الفاظ آپ کے لیے مانوس نہیں ہیں تو پہلے agents کے حقیقی کام کرنے کے طریقے کا مرحلہ وار راستہ پڑھنے کے لیے ایک دوپہر مختص کرنا مفید ہوگا، کیونکہ ذیل کی زیادہ تر settings اسی وقت سمجھ آتی ہیں جب آپ تصور کر سکیں کہ bot بیدار ہونے پر کیا کرتا ہے۔

آخری نکتہ ہی وجہ ہے کہ اسے desktop کے بجائے VPS (virtual private server) پر چلانا چاہیے۔ جس bot کے پاس memory ہو اور جو scheduled work چلاتا ہو، اسے آپ کے سونے کے دوران بھی reachable رہنا چاہیے۔ Laptop کے suspend ہونے سے queue رک جاتی ہے۔

October 2026 تک Rakazo خود کو beta ہی بیان کرتا ہے، اگرچہ اب یہ stable-numbered releases شائع کرتا ہے۔ اس لیے اسے مکمل appliance کے بجائے working setup سمجھیں۔ پورا stack TypeScript میں ہے: web app کے لیے React 19 اور Vite، API کے لیے Hono، database کے لیے Postgres with Prisma، accounts کے لیے Better Auth، اور background jobs کے لیے Graphile Worker۔ Graphile Worker اپنی queue Postgres کے اندر محفوظ کرتا ہے، اس لیے Redis یا چلانے کے لیے دوسرے data store کی ضرورت نہیں ہوتی۔ .env.example، WAKEUP_DRIVER=graphile کو set کرتا ہے، جس کا مطلب ہے کہ bot کا بیدار ہونا Postgres-backed job ہے۔ Postgres روک دیں تو ہر scheduled bot action بھی رک جاتا ہے۔ اگر آپ کسی اور کی product چلانے کے بجائے مختلف اجزا سے اپنا agent بنانا چاہتے ہیں تو components سے اپنا agent بنانا دوسرا راستہ ہے۔

یہ 1 GB پلان اسے کیوں نہیں سنبھال سکے گا

Processes گنیں۔ Postgres ایک ہے۔ API ایک Node process ہے۔ worker دوسرا ہے۔ web app تیسرا ہے۔ sandbox supervisor چوتھا ہے۔ اس کے بعد bots کا computer آتا ہے: بطور default ایک مشترکہ Team Computer container، جس میں graphical Linux desktop ہوتا ہے، اور ہر active bot کے لیے الگ X display اور Chrome process چلتا ہے۔

پروجیکٹ کی self-host دستاویز اب host size نہیں بتاتی۔ v0.3.5 پر موجود دستاویز، جسے 27 October 2026 کو چیک کیا گیا، صرف software requirements درج کرتی ہے۔ تاہم اس میں ہر computer کی حد دی گئی ہے: Docker sandboxes کے ساتھ RAKAZO_COMPUTER_MEMORY بطور default 2g اور RAKAZO_COMPUTER_CPUS کو 2 پر set کیا جاتا ہے۔ یہ حد ہر computer پر لاگو ہوتی ہے، ہر bot پر نہیں۔ ہر workspace کو بطور default ایک Team Computer ملتا ہے، اور ہر active Team bot اپنا desktop اور browser اسی میں چلاتا ہے، اس لیے سب 2 GB اور دو cores کا اشتراک کرتے ہیں۔ صرف Private Computer پر منتقل کیا گیا bot اپنا container اور اپنی حد حاصل کرتا ہے۔ SANDBOX_PROVIDER=docker set کریں تو یہ desktops آپ کے VPS پر منتقل ہو جاتے ہیں اور control plane کے علاوہ اضافی وسائل استعمال کرتے ہیں، اس لیے 4 GB ہدف نہیں بلکہ کم از کم سطح ہے۔ اگر آپ ایک سے زیادہ bots کو فعال رکھنا چاہتے ہیں تو 8 GB سے شروع کریں، RAKAZO_COMPUTER_MEMORY بڑھائیں تاکہ مشترکہ computer واقعی اتنی memory استعمال کر سکے، اور bots کے کام کرنے کے دوران docker stats سے حقیقی استعمال ناپیں۔ memory کا استعمال sandbox کے اندر موجود browser بڑھاتا ہے، اس لیے spec sheet آپ کو درست جواب نہیں دے گی۔ کسی چھوٹے سرور کو بیک وقت بہت سے browsers چلانے سے روکنے کے لیے مثبت SANDBOX_TEAM_SCREEN_LIMIT set کریں۔ یہ Docker Team Computer پر active desktops کی زیادہ سے زیادہ تعداد مقرر کرتا ہے۔ فراہم کردہ 0 میں اس کی کوئی حد مقرر نہیں ہے۔ اگر مجموعی memory کم ہو تو RAKAZO_COMPUTER_MEMORY میں 1536m جیسی کم قدر بھی set کی جا سکتی ہے۔ agent work کے لیے server size مقرر کرنے کے عمومی طریقے کے لیے agent VPS کو درکار حقیقی RAM اور CPU میں measurement کی تفصیل موجود ہے۔

ایک setting اس مسئلے کو مزید بڑھنے سے روکتی ہے۔ .env.example بطور default SANDBOX_IDLE_MS=600000 ہے، اور اس کا comment بتاتا ہے کہ اتنے idle milliseconds کے بعد computers کو pause یا stop کر دیا جاتا ہے۔ دس منٹ idle رہنے پر computer بند ہو جاتا ہے۔ قبول کی جانے والی کم از کم قدر 30000 ہے، جبکہ 0 idle sleep کو غیر فعال کرتا ہے۔ یہی comment Docker self-hosts کے لیے 0 تجویز کرتا ہے، جہاں idle computer کی کوئی لاگت نہیں ہوتی، تاکہ طویل عرصے تک چلنے والی apps اور sessions فعال رہیں۔ یہ مالی لاگت کے لحاظ سے درست ہے، memory کے لحاظ سے نہیں۔ چھوٹے VPS پر timer فعال رکھیں، کیونکہ اس کے بغیر آپ نے جتنے بھی computers شروع کیے ہوں، اور ان کے اندر موجود جتنے بھی browsers ہوں، سب چلتے رہیں گے۔

Disk space بھی اہم ہے۔ sandbox image، Node modules اور Postgres volume ایک ہی disk میں جگہ لیتے ہیں، اس لیے 40 GB مناسب ابتدائی قدر ہے۔

کلون کرنے سے پہلے ورژن pin کریں

Rakazo تیزی سے بدلتا ہے، اور main کوئی release نہیں ہے۔ 9 November 2026 تک v0.8.0، جو 4 November 2026 کو شائع ہوا، Latest کے نشان والا release ہے۔ یہ گائیڈ v0.3.5 پر pinned ہے، جو 25 October 2026 کو شائع ہوا تھا۔

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'

یہ وہ commit ہے جس کی طرف v0.3.5 اشارہ کرتا ہے۔ branch یا tag کے بجائے commit کو pin کریں۔ اگلے git pull میں branch آپ کے نیچے تبدیل ہو جاتی ہے، جبکہ tag ایک متحرک label ہے جسے maintainer کسی دوسرے commit کی طرف دوبارہ مقرر کر سکتا ہے۔ اس لیے ان میں سے کوئی بھی ایسی tree کی شناخت نہیں کرتا جس پر آپ واپس آ سکیں۔ Commit identifier تبدیل نہیں ہو سکتا۔ اسے اپنے سرور کی دیگر معلومات کے ساتھ لکھ کر رکھیں، کیونکہ upgrade خراب ہونے پر کم خرچ حل git checkout <old commit> اور rebuild ہے، اور یہ صرف اسی وقت ممکن ہے جب آپ کو معلوم ہو کہ کون سا commit کام کر رہا تھا۔ Pinned README Rakazo کو beta کہتا ہے، اس لیے اسے درست طور پر pin کرنا معمولی اضافی محنت کے قابل ہے۔ جس project میں طویل عرصے سے سوچ سمجھ کر releases جاری کیے گئے ہوں، اسے شائع شدہ tag پر بھی روکا جا سکتا ہے؛ چھوٹا self-hosted stack جیسے openGym یہی طریقہ اختیار کرتا ہے۔

تقاضے: Node 22، pnpm 9، اور Docker

node -v
pnpm -v
docker --version

package.json میں "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } اور "packageManager": "pnpm@9.15.0" شامل ہیں۔ اس لیے node -v کو v22.22.2 یا بعد کا 22.x، کوئی بھی v24، یا v26 اور اس کے بعد کا ورژن دکھانا چاہیے۔ v22 کا 22.22.2 سے پرانا ورژن اس حد میں شامل نہیں ہے، اور README میں واضح طور پر کہا گیا ہے کہ Node.js 23.x اور 25.x معاون نہیں ہیں۔ Node کا معاون ورژن NodeSource یا nvm سے انسٹال کریں۔ Corepack، Node 22 اور 24 کے ساتھ شامل ہوتا ہے؛ Node 26 اور اس کے بعد کے ورژن پر پہلے اسے npm install -g corepack کے ذریعے انسٹال کریں۔ پھر pnpm فعال کریں:

corepack enable
corepack prepare pnpm@9.15.0 --activate

باقی ضروریات Docker Engine اور compose plugin پوری کرتے ہیں۔ self-host دستاویز bot home volume subpaths کے لیے Docker Engine 26 یا اس کے بعد کا ورژن، API 1.45 یا اس کے بعد کا ورژن، اور curl اور OpenSSL طلب کرتی ہے۔ آپ کے صارف کو daemon تک بھی رسائی حاصل ہونی چاہیے۔ اگر docker ps کا جواب permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock ہو، تو اپنے صارف کو docker گروپ میں شامل کریں اور نیا login shell کھولیں۔ پہلے یہ سمجھ لیں کہ اس سے کیا اختیار ملتا ہے: docker کی رکنیت مشین پر root کے مساوی ہے، کیونکہ اس گروپ کا کوئی بھی رکن ایسا container شروع کر سکتا ہے جو host filesystem کو mount کرے۔

.env کو configure کریں، پھر Postgres شروع کریں

cp .env.example .env
chmod 600 .env

کچھ شروع ہونے سے پہلے کئی values تبدیل کرنا ضروری ہیں۔ .env.example میں BETTER_AUTH_SECRET=replace-with-32-plus-character-secret، ENCRYPTION_KEY=replace-with-64-random-hex-characters، SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret اور SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token شامل ہوتے ہیں، جبکہ POSTGRES_PASSWORD اور POSTGRES_APP_PASSWORD خالی چھوڑے جاتے ہیں۔ یہ تمام placeholders repository میں موجود ہوتے ہیں، اس لیے جس deploy میں ان میں سے کوئی placeholder باقی رہ جائے وہ ایسے secret کے ساتھ چل رہا ہوتا ہے جسے کوئی بھی پڑھ سکتا ہے۔ ہر ایک کے لیے الگ random value دیں۔ ENCRYPTION_KEY میں 64 random hex characters ہونے چاہییں، اور یہی value openssl rand -hex 32 بالکل درست طور پر print کرتا ہے۔ دوسرے secrets کے لیے 32 یا اس سے زیادہ characters درکار ہیں، اس لیے base64 والی line ہر secret کے لیے ایک بار چلائیں۔ دونوں Postgres passwords کے لیے self-host doc میں URL-safe values مطلوب ہیں، جو آخری line فراہم کرتی ہے؛ اسے بھی ہر password کے لیے ایک بار چلائیں۔ Database میں دو logins ہیں۔ DATABASE_MIGRATION_URL میں postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo شامل ہوتا ہے، جو migrations چلانے والا owner ہے، جبکہ DATABASE_URL میں postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo شامل ہوتا ہے، جو app کا اپنا login ہے۔ اسے superuser rights حاصل نہیں ہوتے اور row-level security اس پر لاگو ہوتی ہے۔ ہر password کو اس کے اپنے URL میں رکھیں۔ pnpm db:migrate، rakazo_app login کو آپ کی مقرر کردہ password کے ساتھ بناتا ہے۔

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

اس کے بعد database کو الگ سے شروع کریں اور migrations چلائیں۔

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build، package.json میں docker build -t rakazo/computer:local infra/sandboxes/computer کے طور پر بیان کردہ bot computer image بناتا ہے۔ یہ graphical image ہے، اس لیے پہلی build میں بہت سا data download ہوتا ہے اور وقت لگتا ہے۔ docker image ls rakazo/computer سے تصدیق کریں کہ image بن چکی ہے؛ اس command کو ایک row print کرنی چاہیے۔

بنیادی compose file کوئی Postgres port publish نہیں کرتی۔ اس command میں موجود docker-compose.postgres-host.yml overlay اسے 127.0.0.1:5433 کے طور پر publish کرتا ہے، جو صرف loopback interface تک محدود ہے، اس لیے host-side tools جیسے pnpm db:migrate اور pnpm dev اس تک پہنچ سکتے ہیں۔ اسے اسی طرح رہنے دیں۔ .env میں POSTGRES_PASSWORD کے بغیر Compose، Postgres شروع کرنے سے انکار کرتا ہے، لیکن internet سے قابلِ رسائی Postgres port password attacks کو دعوت دیتا ہے۔ production compose file بھی یہی variable پڑھتی ہے اور database کا کوئی port publish نہیں کرتی۔

پہلی بار چلانا

pnpm dev

اس سے چار چیزیں شروع ہوتی ہیں: port 3100 پر API، Graphile Worker، port 5173 پر Vite web app، اور default طور پر port 7091 پر sandbox supervisor۔ اگر یہ ports مصروف ہوں تو pnpm dev کسی دوسرے خالی block کا انتخاب کرتا ہے اور URLs دکھاتا ہے۔ Default ports پر app http://127.0.0.1:5173 پر دستیاب ہوتی ہے، اور آپ کو sign-in page نظر آنا چاہیے۔

VPS پر آپ اس machine کے سامنے موجود نہیں ہوتے، اس لیے اسے استعمال کرنے کے لیے port 5173 کو public نہیں کرنا چاہیے۔ اس کے بجائے اپنی machine سے SSH (secure shell) کے ذریعے ports forward کریں۔

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

اسے چلانے کے مختلف طریقوں کا فرق سمجھیں۔ pnpm dev host پر Vite چلاتا ہے اور اسے مقامی طور پر bind کرتا ہے۔ Development compose file کی web service 127.0.0.1:5173:5173 کو publish کرتی ہے، اور اس کی api service 127.0.0.1:3100:3100 کو publish کرتی ہے؛ دونوں صرف loopback پر دستیاب ہوتی ہیں، اس لیے یہی tunnel اس کے لیے بھی کام کرتی ہے۔ Production file میں web app کوئی host port publish نہیں کرتی اور صرف اپنی networks پر موجود containers کے لیے 5173 expose کرتی ہے، جبکہ صرف Caddy ports 80 اور 443 publish کرتا ہے۔ اس لیے جو چیز آپ چلتی رہنے دیں، اس کے لیے production file اور اس کا reverse proxy استعمال کریں۔

سرور پر کون سا sandbox provider محفوظ ہے؟

یہ وہ واحد setting ہے جسے درست کرنا ضروری ہے۔ SANDBOX_PROVIDER، .env میں default طور پر docker ہے، اور pinned checkout، self-host doc میں درج providers کے ساتھ Railway کو بھی support کرتا ہے۔

  • docker default ہے۔ Bot computers آپ کی machine پر containers کے طور پر چلتے ہیں۔ یہ containers pnpm sandbox:build سے build ہوتے ہیں اور supervisor کے تحت run کرتے ہیں۔ By default، ایک workspace کے bots ایک Team Computer share کرتے ہیں، جبکہ bot کو صرف Private Computer پر اپنا container ملتا ہے۔ E2B account کی ضرورت نہیں۔
  • e2b bot computers کو E2B پر چلاتا ہے اور E2B_API_KEY درکار ہے۔ v0.3.5 پر factory production میں اسے اس وقت قبول کرتی ہے جب key فراہم کی گئی ہو، اور کوئی NODE_ENV restriction نہیں ہوتی۔ self-host doc کے مطابق یہ public یا multi-user production کے لیے موزوں ہے، کیونکہ bot computers اس host سے الگ رہتے ہیں جو آپ کی API اور database چلا رہا ہے۔
  • daytona، createos اور boat مزید remote providers ہیں۔ ہر ایک کے لیے اپنی key درکار ہے: DAYTONA_API_KEY، CREATEOS_SANDBOX_API_KEY یا BOAT_API_KEY۔
  • railway computers کو Railway پر چلاتا ہے اور API اور worker پر RAILWAY_API_TOKEN اور واضح طور پر منتخب کیا گیا RAILWAY_ENVIRONMENT_ID درکار ہے۔ Sandboxes کے لیے الگ Railway project یا environment استعمال کریں۔
  • desktop bot کے commands کو براہ راست API اور worker host پر چلاتا ہے، جیسا کہ doc میں بیان کیا گیا ہے۔ v0.3.5 پر API اور worker اسے اس وقت تک قبول نہیں کرتے جب تک NODE_ENV، development یا test نہ ہو، لیکن .env.example کے ساتھ NODE_ENV=development ship ہوتا ہے، اس لیے pnpm dev چلانے والا server اب بھی اسے قبول کرتا ہے۔ اسے public یا shared service پر enable نہ کریں۔
  • fake صرف verification کے لیے emulator ہے۔ یہ runtime نہیں ہے۔
  • none product کو کسی computer host کے بغیر شروع کرتا ہے۔

اسے لفظی طور پر سمجھیں۔ Desktop mode میں isolation boundary بالکل نہیں ہوتی۔ اس لیے bot shell commands اس user کے طور پر چلاتا ہے جو API process چلا رہا ہے۔ اسے اسی user کی home directory، SSH keys، cloud credentials اور .env دستیاب ہوتے ہیں۔ Web page میں موجود وہ text جسے bot پڑھتا ہے، آپ کے server پر command بن سکتا ہے۔ Server پر Desktop mode استعمال کرنے سے bot کے پاس آپ کے credentials آ سکتے ہیں۔ اسے ایسی machine پر استعمال کریں جس کے سامنے آپ خود بیٹھتے ہوں، یا بالکل استعمال نہ کریں۔ Providers تبدیل کرنے سے اس web page path کے گرد container بن جاتا ہے، مگر path بند نہیں ہوتا۔ Search side سے اسی injection surface کو cover کرنے کے لیے bot کو اس کا اپنا SearXNG search backend دیں۔

docker bots اور آپ کے host کے درمیان حقیقی boundary فراہم کرتا ہے، لیکن bots کے درمیان کمزور boundary فراہم کرتا ہے۔ By default، bots ایک Team Computer share کرتے ہیں۔ Computer runtime doc کے مطابق Team bots OS user، workspace، browser profiles، shell اور X11 access share کرتے ہیں۔ Per-bot folders کام کو منظم کرتے ہیں، مگر security boundaries نہیں ہیں۔ اس لیے کوئی بھی Team bot کسی دوسرے Team bot کی files پڑھ سکتا ہے۔ جس bot کو اپنی الگ boundaries درکار ہوں، اسے Private Computer پر چلائیں۔ Docker provider اسے اپنے network پر الگ sibling container کے طور پر چلاتا ہے۔ تاہم، ان containers کو بنانے والا supervisor /var/run/docker.sock mount کرتا ہے۔ self-host doc واضح طور پر کہتا ہے کہ اس socket تک access، Docker host پر control کے برابر ہے۔ اس لیے supervisor کو private رکھیں۔ .env.example، SANDBOX_SUPERVISOR_TOKEN کو dedicated credential سمجھتا ہے جو BETTER_AUTH_SECRET سے الگ ہے۔ Local development کے علاوہ Docker sandboxes کے لیے یہ credential درکار ہوتا ہے، اور GitHub پر ایسا placeholder ship ہوتا ہے جسے ہر شخص پڑھ سکتا ہے۔ اسے اپنی الگ random value دیں۔ یہاں دستیاب مضبوط ترین separation کے لیے e2b استعمال کریں، یا Rakazo کے لیے ایسی machine مختص کریں جس پر کوئی اور چیز نہ ہو۔ یہی وجہ coding agents کو disposable VM میں چلانے کے پیچھے بھی ہے: agent کے غلط کام کرنے سے بچنے کا سب سے سستا طریقہ یہ ہے کہ اس کی machine کی کوئی قدر نہ ہو۔

ماڈل API keys کہاں رکھی جاتی ہیں؟

Rakazo کی اختیاری model-credit billing اس وقت تک فعال نہیں ہوتی جب تک دونوں Stripe secrets set نہ ہوں۔ key آپ فراہم کرتے ہیں۔ .env.example، PI_DEFAULT_PROVIDER=openrouter کو set کرتا ہے، اس لیے OPENROUTER_API_KEY معمول کی جگہ ہے، اور provider keys بھی اسی setting کے ذریعے کام کرتی ہیں۔

key کو .env میں رکھیں اور کسی ایسی file میں نہ رکھیں جسے آپ commit کریں۔ repository میں موجود دونوں compose commands --env-file .env پاس کرتی ہیں، اس لیے values containers تک پہنچ جاتی ہیں اور کبھی بھی اس YAML میں نہیں لکھی جاتیں جسے git track کرتا ہے۔ آپ OPENROUTER_API_KEY کو خالی بھی چھوڑ سکتے ہیں اور signup کے بعد app میں model connect کر سکتے ہیں۔ یہ ایک اور وجہ ہے کہ ENCRYPTION_KEY میں shipped placeholder کے بجائے حقیقی random value ہونی چاہیے۔

provider پر bot کے استعمال سے پہلے key کے لیے spending limit مقرر کریں۔ جو bot loop میں چلا جائے، وہ خرچ بھی کرتا ہے۔ Rakazo MAX_TOOL_CALLS_PER_TURN بھی فراہم کرتا ہے: ایک positive integer set کریں تاکہ tool-call budget سے تجاوز کرنے والی turn کو soft-stop کیا جا سکے، جبکہ final assistant message پھر بھی تیار ہو۔ اسے unset یا empty چھوڑنے، یا 0 set کرنے سے یہ unlimited رہتا ہے۔ یہ tool calls شمار کرتا ہے، رقم نہیں، اس لیے یہ provider کی spending limit کا متبادل نہیں ہے۔ اس key کے لیے الگ نام رکھیں تاکہ آپ اسے اکیلے revoke کر سکیں۔ اگر آپ یہ setup اپنے بجائے کسی team کے لیے کر رہے ہیں تو OneCLI کا سب کے agents کے سامنے ایک gateway اسی مسئلے کا مختلف حل ہے، کیونکہ اس میں provider keys ہر شخص کے لیے الگ رکھنے کے بجائے ایک جگہ رکھی جاتی ہیں۔

ڈیولپمنٹ موڈ سے ایسی ترتیب تک جو مسلسل چلتی رہ سکے

repository میں production Compose file شامل ہے۔ یہ Postgres، API، worker، web app اور TLS (transport layer security) certificates خودکار طور پر حاصل کرنے والے Caddy کو چلاتی ہے۔ اس میں صرف Caddy ہی ports publish کرتا ہے۔ بطور ڈیفالٹ یہ bot computers کے لیے E2B استعمال کرتی ہے۔ اختیاری overlay، infra/compose/docker-compose.prod.docker.yml، اسی stack پر مقامی Docker computers چلاتی ہے۔ دستاویز خبردار کرتی ہے کہ اس سے شامل ہونے والا supervisor host پر root کے مساوی اختیار رکھتا ہے۔

sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

key-only deploy account بنائیں اور script چلانے سے پہلے تصدیق کریں کہ آپ اس سے login کر سکتے ہیں۔ harden-host.sh SSH password اور root login کو غیر فعال کرتا ہے، SSH پر rate limit لگاتا ہے، UFW (uncomplicated firewall) کے ذریعے SSH، HTTP اور HTTPS کی اجازتیں شامل کرتا ہے، جبکہ موجودہ private-network rules برقرار رکھتا ہے، اور fail2ban، unattended security updates، AppArmor اور audit rules فعال کرتا ہے۔ یہ SSH_CONNECTION کے بغیر چلنے سے انکار کرتا ہے۔ اسی لیے command اسے sudo کے ذریعے فراہم کرتی ہے۔ یہ firewall کی تبدیلی واپس کر دیتا ہے، جب تک آپ تین منٹ کے اندر نئی SSH session سے اس کی تصدیق نہ کریں۔ اسے چلانے سے پہلے پڑھیں، کیونکہ یہ آپ کے login کے طریقے کو تبدیل کرتا ہے اور SSH کو reload کرتا ہے۔ نئی SSH login کامیاب ہونے تک اپنے provider کا console کھلا رکھیں۔

Production .env کو development والی configuration سے زیادہ چیزیں درکار ہیں۔ self-host دستاویز secrets کے ساتھ یہ minimum درج کرتی ہے۔

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

پہلی up سے پہلے server کی طرف A record point کریں۔ Caddy RAKAZO_HOST میں موجود نام کے لیے certificate طلب کرتا ہے۔ یہ نام اسی box پر resolve ہونا چاہیے، اور HTTP validation کے لیے port 80 یا TLS-ALPN validation کے لیے port 443 بیرونی طور پر قابل رسائی ہونا چاہیے۔ دونوں challenges بطور ڈیفالٹ فعال ہیں۔ اس لیے صرف port 80 بند کرنے سے port 443 کے ذریعے certificate issuance نہیں رکتی۔

شروع ہی سے SIGNUP_ALLOWLIST کو اپنے address پر set رکھیں۔ .env.example، SIGNUPS_ENABLED=true کو ship کرتا ہے، اور دونوں settings ہر API start پر environment سے پڑھی جاتی ہیں۔ اس لیے public name پر موجود ایسا instance جس میں signups فعال ہوں اور allowlist نہ ہو، ہر اس شخص کی registrations قبول کرتا ہے جو اسے تلاش کر لے۔ ہر start پر non-empty allowlist نافذ ہوتی ہے اور stored list کی جگہ لے لیتی ہے۔ Allowlisted signup کے لیے mailbox verification درکار ہے، اور first account بھی اس میں شامل ہوتا ہے۔ اس لیے register کرنے سے پہلے email delivery setup کریں۔ Email کے بغیر دستاویز کا طریقہ یہ ہے کہ SIGNUPS_ENABLED=false کے ساتھ start کریں اور اس کے دیے گئے server-side bootstrap command سے اپنا account بنائیں۔ اس سے عام verified account بنتا ہے جسے server privileges حاصل نہیں ہوتے۔ پہلے allowlist لگائیں۔ بعد میں ضرورت ہو تو اسے نرم کر دیں۔ اگر آپ پہلے ہی اسی box پر کئی services چلا رہے ہیں اور ہر app کے لیے الگ allowlist رکھنے کے بجائے لوگوں کی ایک ہی فہرست رکھنا چاہتے ہیں تو ان کے سامنے Authentik instance رکھنا یہ فیصلہ proxy کی سطح پر منتقل کر دیتا ہے۔ تاہم یہ Rakazo کے اپنے Better Auth accounts کے سامنے بیٹھتا ہے، انہیں replace نہیں کرتا۔

repository میں موجود docs/self-host.md کو production settings کا authoritative ماخذ سمجھیں، کیونکہ یہ code کے ساتھ تبدیل ہوتا رہتا ہے اور یہ guide تبدیل نہیں ہوتی۔ چونکہ Compose کام انجام دے رہا ہے، اس لیے عام اصول لاگو ہوتے ہیں۔ VPS کے لیے Docker Compose کی بنیادی باتیں یہ واضح کرتی ہیں کہ جب کوئی stack کئی ماہ تک بغیر مداخلت کے چلتا رہے تو --env-file اور named volumes زیادہ اہم کیوں ہو جاتے ہیں۔

بیک اپس

اس setup میں Postgres اور data/ ڈائریکٹری instance کا data رکھتی ہے۔ Recovery کے لیے ENCRYPTION_KEY اور configured content master keys بھی درکار ہوتی ہیں، اس لیے ان کی copies سرور سے باہر رکھیں۔

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh، Postgres کا dump بناتا ہے اور data/ کو archive کرتا ہے۔ restore.sh development Compose stack پر کام کرتا ہے، اس کے لیے empty database استعمال کریں اور application services کو stopped رکھیں۔ یہ production backup files کو read نہیں کرتا۔ کسی اہم machine کے لیے infra/compose/backup-prod.sh کو /usr/local/sbin/rakazo-backup کے طور پر install کریں، ساتھ میں repository کا فراہم کردہ timer بھی استعمال کریں۔ یہ verified dump اور app-data archive کو /var/backups/rakazo میں لکھتا ہے۔ By default یہ زیادہ سے زیادہ تین verified snapshots رکھتا ہے، جسے RAKAZO_BACKUP_KEEP متعین کرتا ہے۔ یہ RAKAZO_BACKUP_MAX_GB سے مقرر کردہ 50 GiB cap کے اندر رہتا ہے، اور ہر run سے پہلے partial snapshots اور اضافی history صاف کر دیتا ہے، اس لیے rotation خودکار طور پر ہوتی رہتی ہے۔ یہ ہر backup کو age کے ذریعے /etc/rakazo/backup.env میں درج public recipients کے لیے encrypt بھی کر سکتا ہے، تاکہ سرور ایسے backups لکھے جنہیں وہ خود read نہ کر سکے۔ یہ key pair اپنے زیرِ انتظام کسی machine پر generate کریں اور private key سرور سے باہر رکھیں۔ Recipients نہ ہوں تو backup plaintext رہتا ہے اور log میں warning لکھی جاتی ہے، لیکن پہلے encrypted backup کے بعد recipients کے بغیر run ناکام ہو جاتا ہے، جب تک آپ RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 کے ذریعے plaintext کی واضح اجازت نہ دیں۔ Database والی اسی disk پر رکھا ہوا backup backup نہیں ہوتا، اس لیے اسے machine سے باہر copy کریں۔ پھر ضرورت پڑنے سے پہلے اسے spare server پر ایک بار restore کر کے دیکھیں۔

یہ کیوں ناکام ہوتا ہے، اور آپ کو کیا نظر آئے گا

pnpm db:migrate database تک نہیں پہنچ سکتا۔ Migration رپورٹ کرتی ہے کہ یہ 127.0.0.1:5433 پر database server تک نہیں پہنچ سکتی۔ یا تو Postgres container چل نہیں رہا، یا چل رہا ہے لیکن ابھی ready نہیں ہوا، یا اسے docker-compose.postgres-host.yml overlay کے بغیر start کیا گیا ہے، جو 5433 کو host پر publish کرتا ہے۔ docker compose --env-file .env -f infra/compose/docker-compose.yml ps چلائیں اور دیکھیں کہ postgres service کی حالت healthy ہے، کیونکہ compose file میں اس کے لیے health check موجود ہے جو ہر تین سیکنڈ بعد چلتا ہے۔ اگر container مسلسل restart loop میں ہے تو اس کے logs پڑھیں: pinned Compose stack پرانے Postgres 16 volume کو Postgres 18 میں migrate کیے بغیر start ہونے سے انکار کرتا ہے۔ docker compose ... down -v اسے صاف کر دیتا ہے، اور ساتھ ہی data بھی حذف ہو جاتا ہے۔

Port پہلے سے استعمال میں ہے۔ Postgres کو شروع کرتے وقت bind: address already in use کے ساتھ failure اس وقت ہوتا ہے جب کوئی دوسری چیز 5433 پر قبضہ کیے ہوئے ہو۔ عموماً یہ کوئی پرانا Rakazo stack ہوتا ہے جسے آپ stop کرنا بھول گئے ہوں۔ sudo ss -lntp | grep 5433 process کا نام بتاتا ہے۔ Overlay host port کو POSTGRES_HOST_PORT سے پڑھتا ہے، اس لیے آپ اسے تبدیل کر سکتے ہیں، بشرطیکہ DATABASE_URL اور DATABASE_MIGRATION_URL بھی اسی کے ساتھ تبدیل کیے جائیں۔

Bot کو کبھی computer نہیں ملتا۔ SANDBOX_PROVIDER=docker کے ساتھ، اور rakazo/computer:local image کے بغیر، start کرنے کے لیے کچھ موجود نہیں ہوتا۔ docker image ls rakazo/computer ایک ہی سطر میں اس کی وضاحت کرتا ہے، اور pnpm sandbox:build اسے درست کرتا ہے۔ اگر supervisor Docker socket تک نہیں پہنچ سکتا تو وہ containers بھی create نہیں کر سکتا، اور message path بتاتا ہے: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock۔

طویل command درمیان میں بند ہو جاتی ہے۔ .env.example، SANDBOX_COMMAND_TIMEOUT_MS=300000 مقرر کرتا ہے، اس لیے bot کے computer کے اندر موجود کوئی ایک command پانچ منٹ بعد روک دی جاتی ہے۔ سست builds کے لیے اس حد کو بڑھائیں؛ یہ فرض نہ کریں کہ sandbox crash ہو گیا ہے۔

pnpm install الجھے ہوئے طریقے سے ناکام ہوتا ہے۔ کسی اور چیز سے پہلے node -v چیک کریں۔ Workspace میں ^22.22.2 || ^24.0.0 || >=26.0.0 درج ہے، اس لیے 23.x، 25.x اور 22.22.2 سے پہلے کا کوئی بھی 22.x ورژن اس حد سے باہر ہے۔ Pinned .npmrc، engine-strict=true مقرر کرتا ہے، اس لیے pnpm install application dependency code چلنے سے پہلے unsupported Node version کو engine/version error کے ساتھ مسترد کر دیتا ہے۔

Sign-in مقامی طور پر کام کرتا ہے لیکن domain کے ذریعے نہیں۔ BETTER_AUTH_URL، WEB_ORIGIN اور API_URL تینوں میں address bar کے public origin کی وہی قدر ہونی چاہیے، جس میں scheme بھی شامل ہو۔ ان میں سے کسی ایک میں موجود پرانا http://127.0.0.1:5173 عموماً اس session کی وجہ ہوتا ہے جو برقرار نہیں رہتا۔

pin کیے گئے checkout کو اپ ڈیٹ کرنا

آپ کے checkout سے بنائے گئے production Compose stack کے لیے self-host دستاویز میں upgrade کا طریقہ مختصر ہے: نیا source pull کریں، پھر API، worker اور web app کو rebuild اور restart کریں۔ Migrations اس وقت چلتی ہیں جب API start ہوتی ہے، کیونکہ serve کرنے سے پہلے اس کا start command migrations apply کرتا ہے۔

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

پہلے backup لیں۔ Migrations آگے کی طرف چلتی ہیں، اور beta میں واپسی کا ایسا راستہ نہیں ہوتا جس پر بھروسا کیا جا سکے۔ اگر آپ کا checkout 30 August 2026 سے پرانا ہے، جس میں v0.1.0-beta commit بھی شامل ہے، تو upgrade سے پہلے دستاویز میں 20260830200000_space_scope_names_and_user_credentials migration کے بارے میں دی گئی ہدایت پڑھیں۔ یہ coordinated cutover ہے، اس لیے پہلے پرانی API اور worker روکیں، پھر دستاویز میں دیا گیا Space privacy-boundary check چلائیں۔ اگر آپ ایسے checkout سے upgrade کر رہے ہیں جو الگ app login سے پہلے کا ہے، تو rebuild سے پہلے .env میں POSTGRES_APP_PASSWORD set کریں؛ production compose file اس کے بغیر start ہونے سے انکار کرتی ہے۔ Source-checkout اور production Compose files دونوں Postgres 18 چلاتی ہیں۔ موجودہ Postgres 16 installation کو نئے layout پر start ہونے سے پہلے دستاویز میں دیا گیا infra/compose/upgrade-postgres.sh procedure درکار ہے۔ اپنے pinned SHA اور نئے SHA کے درمیان موجود commits کو apply کرنے سے پہلے پڑھیں، کیونکہ اتنے نئے project میں environment variables کے نام بغیر اعلان کے بدلے جا سکتے ہیں، اور missing variable کی علامت یہ ہوتی ہے کہ service start ہونے کے فوراً بعد exit ہو جاتی ہے۔ اگر آپ ابھی یہ فیصلہ کر رہے ہیں کہ Rakazo چلانا مناسب بھی ہے یا نہیں، تو self-hosted AI agents کا جائزہ بتاتا ہے کہ اس category میں اور کیا شامل ہے اور ہر چیز کو فعال رکھنے کی کتنی لاگت آتی ہے۔

FAQ

کیا میں Rakazo کو 1 GB VPS پر چلا سکتا ہوں؟

نہیں۔ Postgres، API، worker، sandbox supervisor اور web app سب ایک ہی وقت میں چلتے ہیں۔ SANDBOX_PROVIDER=docker کے ساتھ bots کا computer ایک ایسا container بھی شامل کرتا ہے جس میں graphical desktop ہوتا ہے۔ ہر active bot کے لیے الگ X display اور Chrome process چلتا ہے۔ یہ سب ایک default ceiling کے اندر ہوتا ہے، جس میں 2 GB memory اور دو CPUs شامل ہیں۔ Self-host doc at v0.3.5 host size کی کوئی وضاحت نہیں کرتا۔ Control plane کے لیے 4 GB کو کم از کم حد سمجھیں، اور جب desktops آپ کی machine پر چلیں تو اس سے زیادہ memory رکھیں۔

کیا desktop sandbox provider سرور پر محفوظ ہے؟

نہیں۔ Self-host doc کے مطابق desktop commands کو براہ راست API اور worker host پر چلاتا ہے۔ اس لیے bot اس process کو چلانے والے user کے طور پر کام کرتا ہے، اور اس user کی files اور credentials تک رسائی رکھتا ہے۔ v0.3.5 پر API اور worker development اور test mode کے باہر اسے مسترد کرتے ہیں، لیکن pnpm dev چلانے والا server development mode میں ہوتا ہے اور اسے قبول کرتا ہے۔ اسے کسی public یا shared server پر فعال نہ کریں۔ docker استعمال کریں، تاکہ جب bot کو workspace کے دوسرے bots کے ساتھ files share نہیں کرنی ہوں تو اسے Private Computer دیا جا سکے؛ یا جب ایک سے زیادہ افراد sign in کریں تو e2b استعمال کریں۔

مجھے Rakazo کا کون سا ورژن install کرنا چاہیے؟

9 November 2026 تک تازہ ترین release v0.8.0 ہے، جو 4 November 2026 کو شائع ہوا اور Latest کے نشان کے ساتھ ہے۔ اس گائیڈ پر عمل کرنے کے لیے v0.3.5 pinned commit، یعنی f31e3c0699f086d663637c4107858c238a086fb3، کو checkout کریں؛ main کو track نہ کریں اور نہ ہی August v0.1.0-beta prerelease استعمال کریں۔ Branch آپ کے نیچے تبدیل ہو جاتی ہے اور tag کو کسی دوسرے commit کی طرف دوبارہ مقرر کیا جا سکتا ہے، اس لیے ان میں سے کوئی بھی ایسی tree کی شناخت نہیں کرتا جس پر آپ واپس آ سکیں۔ Commit کو record کریں، کیونکہ rollback صرف اسی وقت ممکن ہے جب آپ کو معلوم ہو کہ کون سا commit کام کر رہا تھا۔

میں اپنی OpenRouter API key کہاں رکھوں؟

.env میں OPENROUTER_API_KEY کے طور پر رکھیں، اور اسے کبھی بھی ایسی compose file میں شامل نہ کریں جسے آپ commit کرتے ہیں۔ Repository میں موجود دونوں compose commands --env-file .env پاس کرتی ہیں، اس لیے value tracked YAML میں لکھے بغیر containers تک پہنچ جاتی ہے۔ آپ اسے خالی بھی چھوڑ سکتے ہیں اور signup کے بعد app میں model connect کر سکتے ہیں۔ Provider پر key کے لیے spending limit مقرر کریں، کیونکہ loop میں پھنسا ہوا bot model کو اس وقت تک call کرتا رہتا ہے جب تک کوئی چیز اسے نہ روکے۔

کیا مجھے domain name اور TLS درکار ہیں؟

پہلی آزمائش سے آگے کسی بھی استعمال کے لیے، ہاں۔ Production compose file Caddy چلاتی ہے اور certificates خودکار طور پر حاصل کرتی ہے۔ RAKAZO_HOST کو public hostname پر، اور BETTER_AUTH_URL، WEB_ORIGIN اور API_URL کو اسی public HTTPS origin پر set کریں۔ ابتدائی جائزے کے لیے domain کو چھوڑ سکتے ہیں: pnpm dev چلائیں اور port 5173 کو publish کرنے کے بجائے SSH کے ذریعے forward کریں۔

کیا یہ مضمون مفید تھا؟