راهنمای کامل Self-host کردن Rakazo روی VPS
آموزش نصب Rakazo با استفاده از Docker Compose، Node 22 و pnpm. بررسی دقیق تنظیمات Postgres، مدیریت کلیدها و انتخاب سندباکس مناسب برای اجرای بهینه ربات روی سرور.
آنچه Rakazo در حالت self-hosting واقعاً اجرا میکند
Self-hosting Rakazo به معنای اجرای پنج مورد روی یک سرور Linux است: PostgreSQL، یک پردازش Graphile Worker، رابط API، برنامه وب و یک container سندباکس که به عنوان کامپیوتر رباتها عمل میکند. Rakazo یک جایگزین متنباز برای Grok Bot است که توسط elie222 تحت مجوز Apache 2.0 منتشر شده است. هر ربات گفتگوها، حافظه، روتینها و تاریخچه اختصاصی خود را دارد، از یک Team Computer مشترک با سایر رباتهای فضای کاری استفاده میکند (مگر اینکه یک Private Computer اختصاصی به آن داده شود) و میتواند همتایان یا subagentهای کوتاهمدت ایجاد کند. اگر کلماتی مانند حافظه، subagent و فراخوانی ابزار در این جمله برای شما ناآشنا هستند، یک مسیر مرحلهبندیشده برای درک نحوه عملکرد واقعی عاملها ارزش صرف یک بعدازظهر وقت را دارد، زیرا اکثر تنظیمات زیر تنها زمانی معنا پیدا میکنند که بتوانید تصور کنید یک ربات هنگام بیدار شدن چه کاری انجام میدهد.
بخش آخر دلیل این است که چرا این سرویس باید روی یک VPS (سرور مجازی خصوصی) اجرا شود و نه روی یک دسکتاپ. رباتی که حافظه را نگه میدارد و کارهای زمانبندیشده را اجرا میکند، باید در زمانی که شما خواب هستید نیز در دسترس باشد. لپتاپی که به حالت تعلیق (suspend) میرود، صف کارها را از دست میدهد.
Rakazo تا اکتبر 2026 همچنان خود را در مرحله بتا توصیف میکند، اگرچه اکنون نسخههای با شمارهگذاری پایدار منتشر میکند؛ بنابراین با این مورد به عنوان یک پیکربندی کاری برخورد کنید، نه یک محصول نهایی. پشته فنی کاملاً TypeScript است: React 19 و Vite برای برنامه وب، Hono برای API، Postgres به همراه Prisma، Better Auth برای حسابهای کاربری و Graphile Worker برای کارهای پسزمینه. Graphile Worker صف خود را درون Postgres ذخیره میکند، بنابراین نیازی به Redis یا هیچ ذخیرهساز داده دومی برای اجرا نیست. .env.example تنظیمات WAKEUP_DRIVER=graphile را تعیین میکند، که به این معنی است که بیدار شدن یک ربات، یک job مبتنی بر Postgres است. اگر Postgres را متوقف کنید، تمام فعالیتهای زمانبندیشده ربات نیز با آن متوقف میشوند. اگر ترجیح میدهید به جای اجرای محصول شخص دیگر، یک عامل را از قطعات مختلف اسمبل کنید، ساخت عامل شخصی از اجزا مسیر دیگر پیش روی شماست.
چرا پلن 1 GB برای این کار کافی نیست
تعداد پردازشها را بشمارید. Postgres یکی است. API یک پردازش Node است. Worker دومی است. برنامه وب سومی است. ناظر sandbox چهارمی است. سپس نوبت به کامپیوتر رباتها میرسد: بهصورت پیشفرض یک کانتینر Team Computer مشترک که شامل یک دسکتاپ گرافیکی لینوکس است، با یک X display و پردازش Chrome جداگانه برای هر رباتی که فعال است.
مستندات self-host این پروژه دیگر اندازه میزبان را اعلام نمیکنند. مستندات موجود در v0.3.5 که در تاریخ 27 October 2026 بررسی شدهاند، فقط نیازمندیهای نرمافزاری را فهرست کردهاند. آنچه ارائه شده، سقف منابع برای هر کامپیوتر است: با sandboxهای Docker، مقدار RAKAZO_COMPUTER_MEMORY بهصورت پیشفرض 2g و RAKAZO_COMPUTER_CPUS برابر با 2 است. این سقف برای هر کامپیوتر اعمال میشود، نه برای هر ربات. هر فضای کاری بهصورت پیشفرض یک Team Computer دریافت میکند و تمام رباتهای فعال Team، دسکتاپ و مرورگر خود را درون آن اجرا میکنند، بنابراین همه آنها این 2 GB رم و دو هسته پردازشی را به اشتراک میگذارند. فقط رباتی که به یک Private Computer منتقل شود، کانتینر و سقف منابع اختصاصی خود را دریافت میکند. اگر SANDBOX_PROVIDER=docker را تنظیم کنید، آن دسکتاپها به روی VPS شما و در کنار control plane منتقل میشوند، بنابراین 4 GB حداقل مقدار مورد نیاز است، نه هدف نهایی. اگر قصد دارید بیش از یک ربات را فعال نگه دارید، با 8 GB شروع کنید، RAKAZO_COMPUTER_MEMORY را افزایش دهید تا کامپیوتر مشترک بتواند واقعاً از آن حافظه استفاده کند، و در حین کار رباتها، مقدار واقعی مصرف را با docker stats اندازهگیری کنید. مرورگر داخل sandbox عامل اصلی تغییر میزان مصرف حافظه است، بنابراین مشخصات فنی به تنهایی پاسخگو نیستند. برای جلوگیری از اجرای همزمان تعداد زیادی مرورگر در یک سرور کوچک، یک مقدار مثبت برای SANDBOX_TEAM_SCREEN_LIMIT تنظیم کنید که تعداد دسکتاپهای فعال روی یک Docker Team Computer را محدود میکند. مقدار پیشفرض 0 در نسخه ارسالی، محدودیتی اعمال نمیکند. اگر محدودیت حافظه کلی دارید، RAKAZO_COMPUTER_MEMORY مقادیر کوچکتری مانند 1536m را نیز میپذیرد. برای روش کلی تعیین اندازه سرور جهت کار با agentها، میزان RAM و CPU مورد نیاز واقعی برای یک agent VPS اندازهگیریها را با جزئیات بررسی میکند.
یک تنظیم از بدتر شدن وضعیت جلوگیری میکند. .env.example با مقدار SANDBOX_IDLE_MS=600000 عرضه میشود و کامنت آن میگوید که کامپیوترها پس از آن تعداد میلیثانیه عدم فعالیت، pause یا متوقف میشوند. ده دقیقه عدم فعالیت باعث حذف کامپیوتر میشود. حداقل مقدار پذیرفتهشده 30000 است و 0 خواب ناشی از عدم فعالیت را غیرفعال میکند. همان کامنت مقدار 0 را برای self-hostهای Docker پیشنهاد میدهد، جایی که یک کامپیوتر غیرفعال هزینهای ندارد، بنابراین برنامهها و نشستهای طولانیمدت فعال میمانند. این موضوع برای هزینه صادق است، نه حافظه. روی یک VPS کوچک، تایمر را روشن بگذارید، زیرا بدون آن، هر کامپیوتری که تا به حال راهاندازی کردهاید و هر مرورگری که درون آن است، به اجرا ادامه میدهد.
دیسک نیز اهمیت دارد. ایمیج sandbox، ماژولهای Node و volume مربوط به Postgres همگی از یک دیسک مشترک استفاده میکنند، بنابراین 40 GB نقطه شروع معقولی است.
نسخه را پیش از کلون کردن ثابت کنید
پروژه Rakazo بهسرعت در حال تغییر است و main یک نسخه رسمی (release) محسوب نمیشود. تا تاریخ 9 نوامبر 2026، نسخه v0.8.0 که در 4 نوامبر 2026 منتشر شده، بهعنوان نسخه Latest علامتگذاری شده است. این راهنما بر روی نسخه v0.3.5 که در 25 اکتبر 2026 منتشر شده، ثابت (pin) باقی میماند.
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)، خودِ کامیت را ثابت کنید. یک شاخه در git pull بعدی تغییر میکند و یک برچسب، برچسبی متحرک است که نگهدارنده پروژه میتواند آن را تغییر دهد؛ بنابراین هیچکدام درختی که بتوانید به آن بازگردید را مشخص نمیکنند. شناسه کامیت نمیتواند تغییر کند. شناسه خود را در کنار سایر مشخصات سرور یادداشت کنید، زیرا وقتی یک ارتقا باعث خرابی میشود، راهکار ارزان، استفاده از git checkout <old commit> و بازسازی مجدد است، که این کار تنها در صورتی ممکن است که بدانید کدام کامیت بهدرستی کار میکرده است. فایل README ثابتشده، Rakazo را بتا مینامد، بنابراین ثابت کردن دقیق این نسخه ارزش تلاش اندک آن را دارد. پروژهای با سابقه طولانی در انتشار نسخههای رسمی میتواند روی یک برچسب منتشرشده ثابت بماند، که این همان کاری است که یک استک کوچکتر self-hosted مانند openGym انجام میدهد.
پیشنیازها: Node 22، pnpm 9 و Docker
node -v
pnpm -v
docker --versionpackage.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 --activateDocker Engine به همراه پلاگین compose سایر موارد را پوشش میدهد. مستندات self-host برای زیرمسیرهای volume در bot home، نیازمند 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ای را اجرا کند که فایلسیستم میزبان را mount میکند.
پیکربندی .env و سپس راهاندازی Postgres
cp .env.example .env
chmod 600 .envپیش از شروع هر کاری، باید چندین مقدار تغییر کنند. .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 را خالی میگذارد. تمام این جاینگهدارها در مخزن منتشر شدهاند، بنابراین اگر در استقرار (deploy) یکی از آنها باقی بماند، سیستم با یک رمز عبور عمومی اجرا میشود که هر کسی قادر به خواندن آن است. برای هر کدام یک مقدار تصادفی اختصاص دهید. ENCRYPTION_KEY باید شامل 64 کاراکتر هگزادسیمال تصادفی باشد که دقیقاً همان چیزی است که openssl rand -hex 32 چاپ میکند. سایر رمزها به 32 کاراکتر یا بیشتر نیاز دارند، بنابراین دستور base64 را برای هر کدام یک بار اجرا کنید. برای دو رمز عبور Postgres که در مستندات self-host ذکر شده، به مقادیر URL-safe نیاز دارید؛ دستور آخر این مقادیر را در اختیار شما میگذارد، پس آن را نیز برای هر مورد یک بار اجرا کنید. پایگاه داده دارای دو ورود است. DATABASE_URL به عنوان postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo، یعنی ورود اختصاصی برنامه که فاقد دسترسی superuser است و تحت row-level security قرار دارد، و DATABASE_MIGRATION_URL به عنوان postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo، یعنی مالک (owner) که migrationها را اجرا میکند، عرضه میشوند. هر رمز عبور را در URL مربوط به خود قرار دهید. pnpm db:migrate ورود rakazo_app را با رمز عبوری که تعیین کردهاید، ایجاد میکند.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24سپس پایگاه داده را بهصورت مستقل بالا بیاورید و migrationها را اجرا کنید.
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:buildpnpm sandbox:build ایمیج کامپیوتر ربات را که در package.json به عنوان docker build -t rakazo/computer:local infra/sandboxes/computer تعریف شده، میسازد. این یک ایمیج گرافیکی است، بنابراین اولین build حجم زیادی را دانلود میکند و زمانبر است. با استفاده از docker image ls rakazo/computer تأیید کنید که ایمیج با موفقیت ایجاد شده است؛ این دستور باید یک ردیف خروجی داشته باشد.
فایل compose پایه، هیچ پورتی را برای Postgres منتشر نمیکند. overlay مربوط به docker-compose.postgres-host.yml در آن دستور، پورت را به صورت 127.0.0.1:5433 منتشر میکند که فقط روی loopback در دسترس است، بنابراین ابزارهای سمت میزبان مانند pnpm db:migrate و pnpm dev میتوانند به آن متصل شوند. آن را به همین شکل رها کنید. Compose بدون وجود POSTGRES_PASSWORD در .env از اجرای Postgres خودداری میکند، اما باز گذاشتن پورت Postgres روی اینترنت، دعوتنامهای برای حملات حدس رمز عبور است. فایل compose تولیدی (production)، همان متغیر را میخواند و هیچ پورتی را برای پایگاه داده منتشر نمیکند.
اولین اجرا
pnpm devاین دستور چهار مورد را راهاندازی میکند: API روی پورت 3100، Graphile Worker، اپلیکیشن وب Vite روی 5173 و ناظر sandbox روی 7091 بهصورت پیشفرض. اگر این پورتها اشغال باشند، pnpm dev یک بلوک آزاد دیگر انتخاب کرده و URLها را چاپ میکند. در پورتهای پیشفرض، اپلیکیشن در http://127.0.0.1:5173 در دسترس است و باید صفحه ورود را مشاهده کنید.
در یک VPS شما پشت آن دستگاه نیستید و نباید پورت 5173 را برای دسترسی عمومی منتشر کنید. بهجای آن، پورتها را از طریق SSH (secure shell) از دستگاه خودتان فوروارد کنید.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverدر مورد تفاوت روشهای اجرای این برنامه دقت کنید. pnpm dev برنامه Vite را روی میزبان (host) اجرا میکند که بهصورت محلی bind شده است. سرویس web در فایل compose توسعه، پورت 127.0.0.1:5173:5173 و سرویس api آن پورت 127.0.0.1:3100:3100 را منتشر میکنند که هر دو فقط loopback هستند، بنابراین همان تونل برای آن کار میکند. در فایل تولید (production)، اپلیکیشن وب هیچ پورت میزبانی را منتشر نمیکند و فقط پورت 5173 را روی شبکههای داخلی خود در دسترس کانتینرها قرار میدهد و تنها Caddy پورتهای 80 و 443 را منتشر میکند؛ بنابراین برای هر چیزی که میخواهید بهصورت دائم اجرا شود، از فایل تولید و reverse proxy آن استفاده کنید.
کدام ارائهدهنده sandbox روی سرور امن است؟
این تنها تنظیمی است که باید بهدرستی انجام شود. SANDBOX_PROVIDER در .env بهصورت پیشفرض docker است و checkout پینشده نیز علاوه بر ارائهدهندگان ذکرشده در مستندات self-host، از Railway پشتیبانی میکند.
dockerگزینه پیشفرض است. کامپیوترهای ربات بهعنوان کانتینر روی ماشین شما اجرا میشوند، از ایمیجpnpm sandbox:buildساخته شده و تحت یک supervisor اجرا میگردند. رباتهای یک workspace بهصورت پیشفرض از یک Team Computer مشترک استفاده میکنند و ربات تنها در صورت استفاده از Private Computer، کانتینر اختصاصی خود را دریافت میکند. نیازی به اکانت E2B نیست.e2bکامپیوترهای ربات را روی E2B اجرا میکند و بهE2B_API_KEYنیاز دارد. درv0.3.5، زمانی که کلید ارائه شود، factory آن را در محیط production میپذیرد و هیچ محدودیتی از نوعNODE_ENVوجود ندارد. مستندات self-host آن را برای محیطهای production عمومی یا چندکاربره مناسب میداند، زیرا کامپیوترهای ربات را از هاستی که API و دیتابیس شما روی آن اجرا میشود، دور نگه میدارد.daytona،createosوboatارائهدهندگان راه دور دیگری هستند که هر کدام به کلید اختصاصی خود نیاز دارند:DAYTONA_API_KEY،CREATEOS_SANDBOX_API_KEYیاBOAT_API_KEY.railwayکامپیوترها را روی Railway اجرا میکند و بهRAILWAY_API_TOKENو یکRAILWAY_ENVIRONMENT_IDکه بهطور صریح در API و worker انتخاب شده باشد، نیاز دارد. برای sandboxها از یک پروژه یا محیط اختصاصی در Railway استفاده کنید.desktopدستورات ربات را مستقیماً روی هاست API و worker اجرا میکند. همانطور که در مستندات آمده، درv0.3.5، سرویس API و worker آن را نمیپذیرند مگر اینکهNODE_ENVبرابر باdevelopmentیاtestباشد، اما.env.exampleباNODE_ENV=developmentعرضه میشود، بنابراین سروری کهpnpm devرا اجرا میکند همچنان آن را میپذیرد. آن را روی سرویسهای عمومی یا اشتراکی فعال نکنید.fakeیک شبیهساز صرفاً برای تأیید است و یک محیط runtime محسوب نمیشود.noneمحصول را بدون هیچ کامپیوتر هاستی اجرا میکند.
این موضوع را جدی بگیرید. در حالت desktop هیچ مرز ایزولاسیونی وجود ندارد، بنابراین ربات دستورات shell را بهعنوان کاربری که پروسه API را اجرا میکند، با همان دایرکتوری home، همان کلیدهای SSH، همان اعتبارنامههای ابری و همان .env آن کاربر اجرا میکند. متنی که ربات در یک صفحه وب میخواند، به دستوری روی سرور شما تبدیل میشود. استفاده از حالت desktop روی سرور باعث میشود ربات به اعتبارنامههای شما دسترسی پیدا کند. از آن فقط روی ماشینی استفاده کنید که پشت آن نشستهاید، یا اصلاً استفاده نکنید. تغییر ارائهدهنده، بهجای بستن مسیر صفحه وب، فقط یک کانتینر دور آن ایجاد میکند و دادن یک backend جستجوی SearXNG اختصاصی به ربات نیز همان سطح تزریق را از سمت جستجو پوشش میدهد.
docker یک مرز واقعی بین رباتها و هاست شماست، اما مرز ضعیفی بین خود رباتها ایجاد میکند. بهصورت پیشفرض، آنها از یک Team Computer مشترک استفاده میکنند و مستندات runtime کامپیوتر میگوید که رباتهای Team از کاربر OS، فضای کاری، پروفایلهای مرورگر و دسترسی shell و X11 مشترک استفاده میکنند و پوشههای اختصاصی هر ربات فقط برای سازماندهی کار هستند و مرز امنیتی محسوب نمیشوند. بنابراین هر ربات Team میتواند فایلهای ربات دیگر را بخواند. رباتی که به دیوارههای امنیتی اختصاصی نیاز دارد باید روی Private Computer قرار گیرد که ارائهدهنده docker آن را بهعنوان یک کانتینر خواهر (sibling) جداگانه در شبکه اختصاصی خودش اجرا میکند. با این حال، supervisor که آن کانتینرها را میسازد، /var/run/docker.sock را mount میکند و مستندات self-host بهصراحت میگوید: دسترسی به آن socket معادل کنترل کامل هاست Docker است. بنابراین supervisor را خصوصی نگه دارید. .env.example مقدار SANDBOX_SUPERVISOR_TOKEN را بهعنوان یک اعتبارنامه اختصاصی، متمایز از BETTER_AUTH_SECRET که sandboxهای Docker خارج از محیط توسعه محلی به آن نیاز دارند، در نظر میگیرد و با یک placeholder عرضه میشود که هر کسی در GitHub میتواند آن را بخواند. برای آن یک مقدار تصادفی اختصاصی تعیین کنید. برای قویترین جداسازی ممکن در اینجا، از e2b استفاده کنید یا به Rakazo ماشینی بدهید که هیچ چیز دیگری روی آن نباشد. این همان استدلالی است که پشت اجرای عاملهای کدنویسی در یک VM یکبارمصرف وجود دارد: ارزانترین راه برای بقا در برابر عملکرد اشتباه یک عامل، این است که ماشین آن هیچ ارزش خاصی نداشته باشد.
کلیدهای API مدل کجا قرار میگیرند؟
سیستم پرداخت اعتباری اختیاری Rakazo تا زمانی که هر دو secret مربوط به Stripe تنظیم نشوند، غیرفعال میماند. شما باید کلید خود را ارائه دهید. .env.example مقدار PI_DEFAULT_PROVIDER=openrouter را تنظیم میکند، بنابراین OPENROUTER_API_KEY مکان معمول برای این کار است و کلیدهای ارائهدهنده (provider) نیز از طریق همین تنظیمات کار میکنند.
کلید را در .env نگه دارید و آن را در هیچ فایلی که commit میکنید قرار ندهید. هر دو دستور compose در مخزن، مقدار --env-file .env را ارسال میکنند، بنابراین مقادیر بدون اینکه هرگز در فایل YAML که توسط git ردیابی میشود نوشته شوند، به containerها میرسند. همچنین میتوانید OPENROUTER_API_KEY را خالی بگذارید و پس از ثبتنام، یک مدل را در برنامه متصل کنید؛ این یکی دیگر از دلایلی است که ENCRYPTION_KEY باید یک مقدار تصادفی واقعی داشته باشد و نه مقدار پیشفرض ارائهشده.
پیش از اینکه ربات از کلید استفاده کند، یک سقف هزینه (spending limit) در پنل ارائهدهنده برای آن تعیین کنید. رباتی که در حلقه (loop) بیفتد، رباتی است که هزینه ایجاد میکند. Rakazo همچنین MAX_TOOL_CALLS_PER_TURN را ارائه میدهد: یک عدد صحیح مثبت تعیین کنید تا نوبتی که از بودجه فراخوانی ابزار (tool-call) خود فراتر میرود، متوقف شود، در حالی که همچنان پیام نهایی دستیار تولید میشود. اگر این مقدار تنظیم نشود، خالی باشد یا 0 باشد، محدودیت نخواهد داشت. این گزینه تعداد فراخوانی ابزارها را میشمارد، نه پول را، بنابراین جایگزین سقف هزینه ارائهدهنده نمیشود. برای این کلید یک نام اختصاصی انتخاب کنید تا بتوانید آن را بهتنهایی ابطال کنید. اگر این سیستم را برای یک تیم تنظیم میکنید و نه برای خودتان، درگاه واحد OneCLI در مقابل عامل همه پاسخ متفاوتی برای همان مسئله است، زیرا کلیدهای ارائهدهنده را بهجای هر نفر یک کلید، در یک مکان متمرکز نگه میدارد.
انتقال از حالت توسعه به محیط عملیاتی
این مخزن شامل یک فایل compose برای محیط عملیاتی است که Postgres، API، worker، برنامه وب و Caddy را برای دریافت خودکار گواهیهای TLS (امنیت لایه انتقال) اجرا میکند. Caddy تنها سرویسی است که پورتها را در این فایل منتشر میکند. تنظیمات پیشفرض آن برای کامپیوترهای ربات، E2B است. یک overlay اختیاری به نام infra/compose/docker-compose.prod.docker.yml، کامپیوترهای Docker محلی را روی همان استک اجرا میکند؛ مستندات هشدار میدهند که supervisor اضافه شده توسط این overlay، دسترسی معادل 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پیش از اجرای اسکریپت، یک حساب کاربری deploy فقط با کلید ایجاد کنید و از امکان ورود با آن مطمئن شوید. harden-host.sh ورود با رمز عبور SSH و ورود کاربر root را غیرفعال میکند، نرخ درخواستهای SSH را محدود میسازد، دسترسیهای SSH، HTTP و HTTPS را از طریق UFW (فایروال ساده) اعمال میکند (در حالی که قوانین شبکه خصوصی موجود را حفظ میکند) و fail2ban، بهروزرسانیهای امنیتی خودکار، AppArmor و قوانین audit را فعال مینماید. این اسکریپت بدون SSH_CONNECTION اجرا نمیشود، به همین دلیل دستور آن را از طریق sudo ارسال میکند. همچنین اگر تغییرات فایروال را در یک نشست SSH جدید ظرف سه دقیقه تأیید نکنید، تغییرات را به حالت قبل بازمیگرداند. پیش از اجرا، اسکریپت را مطالعه کنید زیرا نحوه ورود شما را تغییر داده و SSH را reload میکند. تا زمانی که ورود موفقیتآمیز با یک نشست SSH جدید انجام نشده، کنسول ارائهدهنده سرور خود را باز نگه دارید.
فایل .env عملیاتی به تنظیمات بیشتری نسبت به نسخه توسعه نیاز دارد. مستندات self-host حداقلهای مورد نیاز به همراه secretها را فهرست کردهاند.
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، یک رکورد A به سمت سرور تنظیم کنید. Caddy برای نام موجود در RAKAZO_HOST درخواست گواهی میدهد؛ این نام باید به همین سرور اشاره کند و پورت 80 برای اعتبارسنجی HTTP یا پورت 443 برای اعتبارسنجی TLS-ALPN باید از خارج در دسترس باشند. هر دو چالش بهصورت پیشفرض فعال هستند، بنابراین بستن پورت 80 بهتنهایی مانع صدور گواهی از طریق پورت 443 نمیشود.
از همان ابتدا SIGNUP_ALLOWLIST را روی آدرس خود تنظیم کنید. .env.example شامل SIGNUPS_ENABLED=true است و هر دو تنظیم در هر بار شروع API از محیط خوانده میشوند؛ بنابراین اگر یک نمونه روی یک دامنه عمومی با قابلیت ثبتنام فعال و بدون allowlist اجرا شود، ثبتنام هر کسی که آن را پیدا کند پذیرفته میشود. یک allowlist غیرخالی در هر بار شروع اعمال شده و جایگزین لیست ذخیرهشده قبلی میشود. ثبتنام با استفاده از allowlist نیازمند تأیید ایمیل است (شامل اولین حساب کاربری)، بنابراین پیش از ثبتنام، ارسال ایمیل را تنظیم کنید. بدون ایمیل، مسیر پیشنهادی مستندات این است که با SIGNUPS_ENABLED=false شروع کنید و حساب خود را با دستور bootstrap سمت سرور که ارائه میدهد بسازید؛ این کار یک حساب کاربری عادی و تأییدشده بدون دسترسیهای سروری ایجاد میکند. ابتدا allowlist را تنظیم کنید و در صورت نیاز بعداً آن را آزادتر کنید. اگر در حال حاضر چندین سرویس روی یک سرور دارید و ترجیح میدهید بهجای یک allowlist برای هر برنامه، یک لیست واحد از کاربران داشته باشید، قرار دادن یک نمونه Authentik در مقابل آنها این تصمیم را به پروکسی منتقل میکند، هرچند این کار در مقابل حسابهای Better Auth خود Rakazo قرار میگیرد و جایگزین آنها نمیشود.
docs/self-host.md موجود در مخزن را مرجع تنظیمات عملیاتی بدانید، زیرا با تغییر کد تغییر میکند و این راهنما بهروز نمیماند. از آنجایی که Compose وظایف را انجام میدهد، قوانین عادی اعمال میشوند و اصول اولیه Docker Compose برای VPS توضیح میدهد که چرا --env-file و volumeهای نامگذاریشده زمانی که یک استک را برای ماهها به حال خود رها میکنید، اهمیت بیشتری پیدا میکنند.
پشتیبانگیری
در این پیکربندی، Postgres و دایرکتوری data/ دادههای نمونه را نگهداری میکنند؛ بازیابی اطلاعات همچنین به ENCRYPTION_KEY و هرگونه کلید اصلی محتوای پیکربندیشده نیاز دارد، بنابراین نسخههایی از آنها را خارج از سرور نگهداری کنید.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh از Postgres دامپ میگیرد و data/ را آرشیو میکند. restore.sh روی استک توسعه Compose کار میکند، به یک دیتابیس خالی متصل میشود و در حالی که سرویسهای برنامه متوقف هستند اجرا میشود؛ این ابزار فایلهای پشتیبان تولیدی را نمیخواند. برای ماشینی که به آن وابستگی دارید، infra/compose/backup-prod.sh را به عنوان /usr/local/sbin/rakazo-backup و با استفاده از تایمری که در مخزن ارائه شده است، نصب کنید. این ابزار یک دامپ تأییدشده و یک آرشیو از دادههای برنامه را در /var/backups/rakazo مینویسد، بهصورت پیشفرض تا سه اسنپشات تأییدشده را که توسط RAKAZO_BACKUP_KEEP تعیین شده است نگه میدارد، محدودیت 50 GiB را که توسط RAKAZO_BACKUP_MAX_GB تنظیم شده است رعایت میکند، و پیش از هر اجرا اسنپشاتهای ناقص و تاریخچههای اضافی را پاکسازی میکند تا چرخش (rotation) بدون دخالت شما انجام شود. همچنین این ابزار میتواند هر پشتیبان را با استفاده از age برای گیرندگان عمومی که در /etc/rakazo/backup.env لیست کردهاید رمزنگاری کند، بهطوری که سرور پشتیبانهایی بنویسد که خودش قادر به خواندن آنها نیست. آن جفتکلید را روی ماشینی که کنترل میکنید تولید کنید و کلید خصوصی را خارج از سرور نگه دارید. بدون وجود گیرنده، پشتیبان بهصورت متن ساده (plaintext) باقی میماند و یک هشدار در لاگ ثبت میشود، اما پس از اولین پشتیبان رمزنگاریشده، اجرا بدون گیرنده با خطا مواجه میشود مگر اینکه صراحتاً اجازه استفاده از متن ساده را با RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 صادر کنید. پشتیبانی که روی همان دیسک دیتابیس قرار دارد، پشتیبان محسوب نمیشود؛ بنابراین آن را به خارج از سرور منتقل کنید. سپس پیش از آنکه به آن نیاز پیدا کنید، یک بار آن را روی یک سرور یدکی بازیابی کنید.
چرا این خطا رخ میدهد و چه چیزی مشاهده خواهید کرد
pnpm db:migrate نمیتواند به پایگاه داده متصل شود. عملیات مهاجرت گزارش میدهد که قادر به برقراری ارتباط با سرور پایگاه داده در 127.0.0.1:5433 نیست. یا کانتینر Postgres بالا نیست، یا بالا آمده اما هنوز آماده نیست، و یا بدون overlay مربوط به docker-compose.postgres-host.yml اجرا شده است؛ همان چیزی که پورت 5433 را روی میزبان منتشر میکند. دستور docker compose --env-file .env -f infra/compose/docker-compose.yml ps را اجرا کنید و بررسی کنید که آیا سرویس postgres وضعیت healthy را گزارش میدهد یا خیر، زیرا فایل compose دارای یک health check است که هر سه ثانیه اجرا میشود. اگر کانتینر در یک حلقه بازراهاندازی (restart loop) گیر کرده است، لاگهای آن را بخوانید: استک Compose پینشده تا زمانی که به Postgres 18 مهاجرت نکند، روی volume قدیمی Postgres 16 اجرا نمیشود. دستور docker compose ... down -v آن را پاکسازی میکند و دادهها را نیز همراه با آن حذف مینماید.
پورت قبلاً اشغال شده است. بالا آوردن Postgres با خطای bind: address already in use شکست میخورد، زمانی که چیز دیگری پورت 5433 را اشغال کرده باشد؛ که معمولاً یک استک Rakazo قدیمی است که فراموش کردهاید متوقف کنید. دستور sudo ss -lntp | grep 5433 نام فرآیند اشغالکننده را مشخص میکند. این overlay پورت میزبان را از POSTGRES_HOST_PORT میخواند، بنابراین میتوانید آن را تغییر دهید، به شرطی که DATABASE_URL و DATABASE_MIGRATION_URL نیز همراه با آن تغییر کنند.
یک بات به کامپیوتر دسترسی پیدا نمیکند. با وجود SANDBOX_PROVIDER=docker و نبود ایمیج rakazo/computer:local، چیزی برای اجرا وجود ندارد. دستور docker image ls rakazo/computer در یک خط به این موضوع پاسخ میدهد و pnpm sandbox:build آن را اصلاح میکند. اگر supervisor نتواند به Docker socket دسترسی پیدا کند، نمیتواند کانتینرها را ایجاد کند و پیام خطا مسیر را مشخص میکند: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
یک دستور طولانی در میانه راه متوقف میشود. مقدار .env.example تنظیمکننده SANDBOX_COMMAND_TIMEOUT_MS=300000 است، بنابراین یک دستور واحد در داخل کامپیوتر بات پس از پنج دقیقه قطع میشود. برای بیلدهای کند، این مقدار را افزایش دهید و فرض نکنید که sandbox کرش کرده است.
pnpm install به روشهای گیجکنندهای دچار مشکل میشود. پیش از هر چیز، node -v را بررسی کنید. فضای کاری (workspace) مقدار ^22.22.2 || ^24.0.0 || >=26.0.0 را اعلام میکند، بنابراین نسخههای 23.x، 25.x و هر نسخه 22.x پیش از 22.22.2 خارج از این محدوده هستند. مقدار پینشده .npmrc تنظیمکننده engine-strict=true است، بنابراین pnpm install یک نسخه Node پشتیبانینشده را با خطای engine/version پیش از اجرای کد وابستگیهای برنامه رد میکند.
ورود به سیستم در حالت محلی کار میکند اما از طریق دامنه خیر. مقادیر BETTER_AUTH_URL، WEB_ORIGIN و API_URL همگی باید دارای همان مبدأ عمومی (public origin) باشند که در نوار آدرس وارد میشود، که شامل طرح (scheme) نیز هست. وجود یک http://127.0.0.1:5173 قدیمی در یکی از آنها، علت معمولِ نشستهایی (session) است که هرگز پایدار نمیمانند.
بهروزرسانی یک checkout پینشده
مسیر ارتقا در مستندات self-host برای یک stack تولیدی Compose که از checkout شما ساخته شده، کوتاه است: سورس جدید را pull کنید، سپس API، worker و برنامه وب را rebuild و restart کنید. عملیات migration هنگام شروع به کار API اجرا میشود، زیرا دستور شروع آن، پیش از ارائه سرویس، migrationها را اعمال میکند.
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ابتدا نسخه پشتیبان تهیه کنید. Migrationها فقط رو به جلو حرکت میکنند و نسخه بتا هیچ مسیر بازگشتی قابلاتکایی به شما نمیدهد. اگر checkout شما قدیمیتر از 30 August 2026 است (که شامل commit v0.1.0-beta میشود)، پیش از ارتقا، یادداشت مستندات درباره migration 20260830200000_space_scope_names_and_user_credentials را مطالعه کنید. این یک تغییر هماهنگشده است، بنابراین ابتدا API و worker قدیمی را متوقف کنید و بررسی مرز حریم خصوصی Space که در مستندات آمده است را اجرا کنید. هنگام ارتقا از checkoutهایی که پیش از قابلیت ورود جداگانه برنامه (separate app login) هستند، پیش از rebuild، مقدار POSTGRES_APP_PASSWORD را در .env تنظیم کنید؛ فایل compose تولیدی بدون آن اجرا نمیشود. فایلهای source-checkout و production Compose همچنین از Postgres 18 استفاده میکنند: نصب فعلی Postgres 16 پیش از شروع کار روی ساختار جدید، به دستورالعمل infra/compose/upgrade-postgres.sh در مستندات نیاز دارد. پیش از اعمال commitها، commitهای بین SHA پینشده خود و SHA جدید را مطالعه کنید، زیرا پروژهای به این جوانی، متغیرهای محیطی را بدون اطلاعرسانی تغییر نام میدهد و یک متغیر گمشده به صورت سرویسی ظاهر میشود که شروع شده و بلافاصله خارج میشود. اگر هنوز در حال تصمیمگیری هستید که آیا Rakazo گزینه مناسبی برای اجرا است یا خیر، بررسی اجمالی ایجنتهای هوش مصنوعی self-hosted پوشش میدهد که چه گزینههای دیگری در این دستهبندی وجود دارند و هزینه نگهداری هر کدام چقدر است.
FAQ
آیا میتوانم Rakazo را روی یک VPS با 1 گیگابایت رم اجرا کنم؟
خیر. Postgres، API، worker، ناظر sandbox و اپلیکیشن وب همگی همزمان اجرا میشوند و با SANDBOX_PROVIDER=docker، کامپیوتر رباتها یک کانتینر شامل یک دسکتاپ گرافیکی اضافه میکند که برای هر ربات فعال، یک نمایشگر X و پردازش Chrome جداگانه دارد؛ همه اینها در سقف پیشفرض 2 گیگابایت حافظه و دو CPU قرار دارند. مستندات self-host در v0.3.5 هیچ اندازه میزبانی را پیشنهاد نمیکند. 4 گیگابایت رم را حداقلِ لازم برای control plane در نظر بگیرید و زمانی که دسکتاپها روی دستگاه خودتان اجرا میشوند، به سراغ مقادیر بالاتر بروید.
آیا ارائهدهنده sandbox دسکتاپ روی سرور امن است؟
خیر. مستندات self-host میگوید desktop دستورات را مستقیماً روی میزبان API و worker اجرا میکند، بنابراین ربات بهعنوان کاربری که آن پردازش را اجرا میکند عمل کرده و به فایلها و اعتبارنامههای آن کاربر دسترسی دارد. در v0.3.5، API و worker این کار را خارج از حالت توسعه و تست رد میکنند، اما سروری که pnpm dev را اجرا میکند در حالت توسعه است و آن را میپذیرد. آن را از هر سرور عمومی یا اشتراکی دور نگه دارید. از docker استفاده کنید که به ربات یک کامپیوتر خصوصی میدهد تا فایلها را با سایر رباتهای فضای کاری به اشتراک نگذارد، یا از e2b زمانی که بیش از یک نفر وارد سیستم میشود استفاده کنید.
کدام نسخه از Rakazo را باید نصب کنم؟
تا تاریخ 9 نوامبر 2026، جدیدترین نسخه v0.8.0 است که در 4 نوامبر 2026 منتشر شده و بهعنوان Latest علامتگذاری شده است. برای دنبال کردن این راهنما، بهجای دنبال کردن main یا نسخه پیشانتشار آگوست v0.1.0-beta، کامیت ثابتشده v0.3.5 یعنی f31e3c0699f086d663637c4107858c238a086fb3 را بررسی کنید. یک شاخه تغییر میکند و یک برچسب میتواند تغییر داده شود، بنابراین هیچکدام درختی که بتوانید به آن بازگردید را مشخص نمیکنند. کامیت را ثبت کنید، زیرا بازگشت به نسخه قبلی تنها زمانی ممکن است که بدانید کدام نسخه بهدرستی کار میکرده است.
کلید API مربوط به OpenRouter را کجا قرار دهم؟
در .env بهعنوان OPENROUTER_API_KEY، و هرگز آن را در فایل compose که commit میکنید قرار ندهید. هر دو دستور compose در مخزن، --env-file .env را پاس میدهند، بنابراین مقدار بدون اینکه در YAML ردیابیشده نوشته شود، به کانتینرها میرسد. همچنین میتوانید آن را خالی بگذارید و پس از ثبتنام، یک مدل را در اپلیکیشن متصل کنید. یک سقف هزینه برای کلید در پنل ارائهدهنده تنظیم کنید، زیرا یک ربات در حلقه (loop) تا زمانی که چیزی آن را متوقف نکند، به فراخوانی مدل ادامه میدهد.
آیا به نام دامنه و TLS نیاز دارم؟
برای هر چیزی فراتر از یک تست اولیه، بله. فایل compose تولید، Caddy را اجرا کرده و بهطور خودکار گواهیها را دریافت میکند؛ RAKAZO_HOST را روی نام میزبان عمومی تنظیم کنید و BETTER_AUTH_URL، WEB_ORIGIN و API_URL را روی همان مبدأ HTTPS عمومی قرار دهید. برای بررسی اولیه میتوانید از دامنه صرفنظر کنید: pnpm dev را اجرا کرده و بهجای انتشار پورت 5173، آن را از طریق SSH فوروارد کنید.