آموزش نصب و راه اندازی OpenHands روی VPS با Docker

OpenHands چیست و اولین ریسکی که باید درک کنید

OpenHands که پیش‌تر با نام OpenDevin شناخته می‌شد، یک عامل (agent) خودمختار مهندسی نرم‌افزار است. شما یک وظیفه را با زبان ساده به آن محول می‌کنید و این ابزار برای انجام آن برنامه‌ریزی می‌کند، کد می‌نویسد، دستورات را اجرا می‌کند، خروجی را می‌خواند و تا زمان تکمیل وظیفه، این چرخه را تکرار می‌کند. شما این ابزار را روی سرور شخصی خود با استفاده از Docker اجرا کرده و آن را به یک مدل زبانی متصل می‌کنید. روی یک VPS، این ابزار به یک عامل برنامه‌نویسی تبدیل می‌شود که حتی در زمان عدم حضور شما نیز کار می‌کند.

یک واقعیت باید کل پیکربندی شما را تحت تأثیر قرار دهد. OpenHands فقط کد پیشنهاد نمی‌دهد، بلکه آن را اجرا می‌کند؛ برای این کار، کانتینر کنترل‌کننده آن، سوکت Docker میزبان را در مسیر /var/run/docker.sock مونت (mount) می‌کند تا بتواند برای هر وظیفه، کانتینرهای sandbox جداگانه ایجاد کند. هر چیزی که بتواند با سوکت Docker ارتباط برقرار کند، قادر است کانتینر جدیدی را شروع کند که کل فایل‌سیستم میزبان شما را مونت می‌کند؛ این یعنی دسترسی به سوکت، عملاً به معنای دسترسی root روی ماشین است. بنابراین، با سرور OpenHands مانند سروری رفتار کنید که کدهای غیرقابل‌اعتماد را اجرا می‌کند، زیرا دقیقاً همین کار را انجام می‌دهد. تمام انتخاب‌های امنیتی که در ادامه می‌آید، بر اساس همین واقعیت است.

آنچه نیاز دارید

شما به یک VPS با سیستم‌عامل Ubuntu 24.04، نسخه به‌روز Docker Engine، حداقل 4 GB رم و یک API key برای یک مدل زبانی (OpenAI، Anthropic یا Google) یا یک مدل محلی که توسط Ollama روی همان VPS ارائه می‌شود، نیاز دارید. OpenHands از ده‌ها مدل backend پشتیبانی می‌کند، بنابراین انتخاب با شماست. اگر قبلاً هرگز containerها را راه‌اندازی نکرده‌اید، اصول Docker روی VPS مباحثی را که این راهنما فرض گرفته است، پوشش می‌دهد.

نصب با Docker

OpenHands در قالب دو ایمیج عرضه می‌شود: ایمیج اپلیکیشن که شما اجرا می‌کنید، و ایمیج agent-server که برای اجرای sandbox هر تسک توسط اپلیکیشن فراخوانی می‌شود. آن را به شکل زیر اجرا کنید و تگ‌های فعلی را از مستندات پروژه جایگزین نمایید:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

دو نکته شما را از یک ساعت سردرگمی نجات می‌دهد. ایمیج اپلیکیشن و ایمیج agent-server عمداً شماره نسخه‌های متفاوتی دارند، بنابراین سعی نکنید آن‌ها را یکسان کنید: از تگ agent-server که در مستندات با نسخه اپلیکیشن شما جفت شده است استفاده کنید. همچنین به -p 127.0.0.1:3000:3000 به جای -p 3000:3000 دقت کنید. همین یک تغییر، تفاوت بین یک رابط کاربری وب که فقط خودتان به آن دسترسی دارید و رابطی که کل اینترنت به آن دسترسی دارد است؛ موضوعی که بخش بعدی به آن می‌پردازد.

رابط کاربری وب را از دسترس اینترنت عمومی خارج کنید

OpenHands رابط کاربری خود را روی پورت 3000 ارائه می‌دهد. این رابط کاربری عاملی را کنترل می‌کند که کد اجرا می‌کند، بنابراین انتشار آن در اینترنت به هر کسی که آن را پیدا کند، یک مسیر از راه دور به فرآیندی می‌دهد که دستورات را اجرا می‌کند. آن را به loopback متصل کنید، همان‌طور که در دستور اجرای بالا انجام شد، و از طریق یک SSH tunnel از لپ‌تاپ خود به آن دسترسی پیدا کنید:

ssh -L 3000:127.0.0.1:3000 you@your-vps

سپس http://127.0.0.1:3000 را در دستگاه خود باز کنید. ترافیک از طریق نشست SSH فعلی شما منتقل می‌شود و هیچ چیز جدیدی روی اینترنت عمومی گوش نمی‌دهد. همه عامل‌ها اصلاً نیازی به پورت ندارند: نشست‌های Claude Code روی همان VPS از طریق ترمینال با یکدیگر پیام رد و بدل می‌کنند، بنابراین تنها چیزی که همیشه در معرض دید قرار می‌دهید، خود SSH است. عادت استفاده از loopback و tunnel برای هر داشبورد عاملی که میزبانی می‌کنید، ارزشمند است؛ دسترسی به رابط کاربری اسکن open-kritt از طریق یک tunnel نیز به همین روش کار می‌کند، فقط روی پورت 5173. برای یک تنظیم دائمی‌تر، آن را پشت یک VPN قرار دهید. در هر صورت، یک فایروال با سیاست default-deny جلوی سرور قرار دهید تا چیزی به‌طور تصادفی در معرض دید قرار نگیرد، و به یاد داشته باشید که فایروالی که فقط IPv4 را پوشش می‌دهد، همان پورت را روی IPv6 باز می‌گذارد که این همان شکاف فایروال IPv6 است که بسیاری از افراد را دچار مشکل می‌کند.

ایزوله‌سازی کلید مدل و اعتبارنامه‌های مخزن

OpenHands برای مدل خود به یک API key نیاز دارد و اغلب برای clone کردن و push به مخازن شما، به یک token احتیاج پیدا می‌کند. هر دوی این موارد می‌توانند هزینه ایجاد کنند و به نام شما عمل کنند، بنابراین با آن‌ها مانند رمز عبور رفتار کنید. آن‌ها را در یک فایل محیطی (environment file) نگه دارید که فقط حساب کاربری مجاز بتواند آن را بخواند. هرگز آن‌ها را در دستور اجرا قرار ندهید، زیرا در تاریخچه shell و لیست پردازش‌ها ثبت می‌شوند؛ همچنین هرگز آن‌ها را در فایلی داخل یک مخزن git قرار ندهید. اگر نسخه‌های اصلی را در یک password manager خودمیزبان (self-hosted) نگهداری می‌کنید، آن سرور را نیز مقاوم‌سازی کنید؛ زیرا نقاط ضعف یک vault بیشتر از خودِ موارد رمزنگاری‌شده، شامل token مدیریت و فایل پشتیبان آن است، همان‌طور که در مقاوم‌سازی Vaultwarden بررسی شده است.

اجرای آن روی سیستمی که قابل دور انداختن باشد

از آنجا که controller باید به Docker socket دسترسی داشته باشد، نمی‌توان OpenHands را به‌طور کامل از میزبان خود ایزوله کرد. راهکار صادقانه برای کاهش ریسک، جداسازی از طریق مکان‌یابی است: OpenHands را روی یک VPS اختصاصی اجرا کنید که هیچ دادهٔ مهم دیگری روی آن ندارید؛ نه روی سروری که دیتابیس یا وب‌سایت شما را میزبانی می‌کند. پیش از شروع، یک snapshot بگیرید و به‌جای اعتماد به سیستمی که یک هفته کد تولیدشده توسط agent را اجرا کرده است، آن را از روی همان snapshot بازیابی کنید. یک VPS ارزان، یک‌بارمصرف و تک‌منظوره، بهترین محیط برای این کار است. مکان‌یابی تنها اهرمی است که OpenHands در اینجا در اختیار شما می‌گذارد؛ بنابراین اگر ترجیح می‌دهید کنترل کنید که agent پیش از توقف و پرسش، تا چه حد مجاز به انجام عملیات است، حالت‌های دسترسی Claude Code نشان می‌دهند که این اهرم دوم در سروری که تحت نظارت دائمی نیست، چگونه عمل می‌کند.

ایمن‌سازی محیط پیرامون

باقی موارد، رعایت بهداشت استاندارد سرور است و در اینجا اهمیت آن بیش از موارد معمول است، زیرا بار کاری (workload) ریسک بالاتری نسبت به حالت عادی دارد. به‌جای کار با کاربر root، یک کاربر مدیریتی بدون امتیاز (unprivileged) ایجاد کنید؛ برای این کار از راهنمای اجرای سرویس‌ها با کاربر بدون امتیاز پیروی کنید. احراز هویت SSH را فقط به استفاده از کلید (key-only) محدود کنید. سپس چک‌لیست زیر را اجرا کرده و آن را در جایی نگه دارید که دوباره به آن دسترسی داشته باشید.

برای درک اجزای متحرک به‌جای صرفاً اجرای آن‌ها، به ساخت ایجنت هوش مصنوعی شخصی روی VPS مراجعه کنید؛ برای پلتفرمی با کدنویسی کمتر، میزبانی شخصی Dify نقطه شروع ملایم‌تری است.

FAQ

آیا اجرای OpenHands روی سرور امن است؟

با رعایت احتیاط می‌تواند امن باشد، اما نسبت به یک برنامه وب معمولی ریسک بیشتری دارد؛ زیرا این ابزار کد می‌نویسد و اجرا می‌کند و کنترلر آن به Docker socket میزبان دسترسی دارد که عملاً به معنای دسترسی root روی ماشین است. آن را روی یک VPS اختصاصی و یک‌بارمصرف که حاوی هیچ داده ارزشمند دیگری نیست اجرا کنید، رابط کاربری وب آن را از طریق SSH tunnel یا VPN روی loopback نگه دارید، کلیدهای آن را ایزوله کنید و امنیت سیستم‌عامل را سخت‌گیرانه تنظیم کنید. آن را در کنار سرویس‌های مهم خود اجرا نکنید.

چرا OpenHands به Docker socket نیاز دارد؟

OpenHands هر وظیفه را در یک container سندباکس تازه اجرا می‌کند و برای ایجاد این containerها، از طریق mount کردن /var/run/docker.sock در کنترلر خود، از Docker daemon میزبان درخواست می‌کند. این کار به container کنترلر، دسترسی کامل به Docker روی میزبان می‌دهد که بسیار قدرتمند و پرخطر است؛ بنابراین میزبان باید به عنوان سیستمی در نظر گرفته شود که کد غیرقابل‌اعتماد اجرا می‌کند.

آیا OpenHands می‌تواند به جای API پولی از مدل محلی استفاده کند؟

بله. OpenHands از مدل‌های محلی که توسط Ollama یا vLLM ارائه می‌شوند پشتیبانی می‌کند، بنابراین می‌توانید آن را به‌طور کامل به صورت self-hosted اجرا کنید بدون اینکه هزینه‌ای به ازای هر توکن بپردازید یا داده‌ای از سرور شما خارج شود. شما به ماشینی با حافظه کافی برای یک مدل کدنویسی توانمند نیاز دارید که همان بحث ابعاد‌سنجی مطرح شده در راهنمای Ollama است.

آیا باید OpenHands را روی سرور اصلی خود اجرا کنم؟

خیر. از آنجایی که این ابزار کدهای نوشته‌شده توسط عامل (agent) را اجرا می‌کند و به Docker socket دسترسی دارد، آن را روی یک VPS جداگانه و تک‌منظوره که آمادگی بازسازی آن را دارید، نگه دارید. قرار دادن آن در کنار پایگاه داده، وب‌سایت یا سایر سرویس‌هایتان به این معناست که یک اشتباه توسط عامل یا وجود یک باگ در آن، می‌تواند به بخش‌هایی دسترسی پیدا کند که هرگز نباید به آن‌ها نفوذ می‌کرد.