آموزش نصب و راهاندازی Agentlas OS روی VPS
نحوه نصب نسخه 1.2.0 سیستم Agentlas OS روی Linux VPS را بیاموزید. این راهنما شامل تنظیمات مسیر فایلها، اتصال به Ollama و بررسی دقیق هزینههای واقعی اجرای این هاب عامل است.
Agentlas OS چیست
Agentlas OS یک محیط اجرای عامل (agent runtime) متنباز است که عاملهای تخصصی را بهصورت بسته روی دیسک ذخیره کرده و برای هر وظیفه، یک ارکستراتور موقت ایجاد میکند. شما آن را با نصب در حساب کاربری خود روی یک Linux VPS بهصورت self-hosted اجرا میکنید. این سیستم یک سرویس نیست. هیچ daemon، پورت در حال گوش دادن، رابط کاربری وب یا image کانتینری در مخزن آن وجود ندارد.
جمله آخر، تعیینکننده تمام موارد دیگر در این صفحه است. اکثر سیستمهای چندعاملی، یک پردازش ناظر (supervisor) را اجرا میکنند که همیشه فعال است و عاملها را نگه میدارد. Agentlas این مدل را معکوس میکند: متخصصها فایلهایی در حالت سکون هستند و ارکستراتور تنها در زمان اجرای یک وظیفه وجود دارد. نتیجه عملی این است که یک هاب غیرفعال، فقط فضای دیسک شما را اشغال میکند، نه حافظه رم را.
این پروژه هسته متنباز خود را Hephaestus مینامد و این نامی است که در دستورات، مسیرها و متغیرهای محیطی مشاهده خواهید کرد. مخزن پروژه agentlas-ai/Agentlas-OS است، تحت مجوز Apache-2.0 منتشر شده و عمدتاً با زبان Python نوشته شده است.
صادقانه بگویم، این پروژه چقدر نوپا است
این مخزن در تاریخ 4 June 2026 ایجاد شده است. تا تاریخ 12 August 2026، عمر آن حدود ده هفته است و تقریباً 1,150 ستاره و 112 فورک دارد. برای پروژهای که قصد دارید کارهای واقعی خود را به آن بسپارید، این سن بسیار کم است.
تداوم در انتشار نسخهها (release cadence) از سن پروژه اهمیت بیشتری دارد. نسخه v1.1.103 در تاریخ 8 August 2026 و نسخه v1.2.0 در تاریخ 12 August 2026 منتشر شد. این یعنی بیش از صد نسخه تگشده در سری 1.1 که برخی از آنها توسط اتوماسیون در یک روز منتشر شدهاند. پروژهای که با این سرعت حرکت میکند، ممکن است رفتار خود را بین روزهای سهشنبه تا پنجشنبه تغییر دهد.
بنابراین، نسخه را ثابت (pin) کنید. نصبکننده برای این کار یک متغیر محیطی (environment variable) میخواند و کل راهنمای زیر از آن استفاده میکند. نصب بدون تعیین نسخه (unpinned) برای پروژهای که روزانه چندین بار منتشر میشود، باعث میشود هر چیزی که در آن ساعت روی main قرار دارد، برای شما نصب شود.
آنچه در VPS نیاز دارید
نیازمندیها اندک هستند زیرا هیچ فرآیندی در پسزمینه اجرا نمیشود.
- یک VPS لینوکسی. Ubuntu 24.04 یک گزینه پایه مناسب است. نصبکننده سیستمعامل را با
uname -sشناسایی کرده و شاخه غیر macOS را برای لینوکس انتخاب میکند، بنابراین سرورهای بدون رابط گرافیکی (headless) پشتیبانی میشوند. - ابزارهای
curl،tarوgitروی سیستم، به همراه یک مفسر Python فعال. - دسترسی خروجی HTTPS به
raw.githubusercontent.comوgithub.com. نصبکننده یک آرشیو release را دانلود کرده و SHA-256 آن را بررسی میکند، بنابراین سیستمی که دسترسی خروجی نداشته باشد قادر به نصب این برنامه نیست. - یک host harness، که همان عامل کدنویسی است که مستقیماً با مدل ارتباط برقرار میکند. Claude Code، Codex، opencode، goose و Hermes همگی آداپتورهای پشتیبانیشده هستند.
شما نیازی به دسترسی root ندارید. نصبکننده فقط در دایرکتوری home شما و مسیر ~/.local/bin مینویسد و در صورتی که مسیری قابل نوشتن نباشد، بهجای متوقف کردن عملیات، هشدار میدهد. اگر هنوز در حال انتخاب سرور هستید، اجرای یک عامل کدنویسی روی VPS تنظیمات پایه image و دسترسیهایی که این برنامه بر پایه آن اجرا میشود را پوشش میدهد.
نصب نسخه پینشده (Pinned Release)
فایل README بالادستی، یک دستور تکخطی را مستند کرده است که اسکریپتی را از main مستقیماً به bash پایپ میکند. ابتدا آن را دانلود کرده و مطالعه کنید. این اسکریپت در پیکربندی shell شما و در تمام harnessهای agent که پیدا میکند مینویسد، بنابراین صرف ده ثانیه زمان برای بررسی آن ارزشمند است.
curl -fsSL -o install-all-runtimes.sh \
https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.shHEPHAESTUS_REF همان پین (pin) است. در داخل اسکریپت، این خط به صورت version="${HEPHAESTUS_REF:-v1.2.0}" است؛ بنابراین اگر آن را تنظیمنشده رها کنید، امروز نسخه v1.2.0 را دریافت میکنید و هفته آینده ممکن است نسخه دیگری باشد. آن را بهطور صریح تنظیم کنید تا بازسازی (rebuild) شما در ماه اکتبر، دقیقاً همان چیزی را نصب کند که در ماه اوت تست کردهاید.
یک محدودیت صادقانه: URL اسکریپت در بالا، main را دنبال میکند، در حالی که HEPHAESTUS_REF محموله (payload) زمان اجرا را که اسکریپت دانلود میکند، پین میکند. این دو موضوع متفاوت هستند. برای پین کردن هر دو، اسکریپت را به جای main از روی تگ (tag) دریافت کنید؛ برای این کار main را در آن URL با v1.2.0 جایگزین کنید.
اجرای موفقیتآمیز، مسیرهایی را که در آنها نوشته است چاپ میکند، از جمله این دو خط:
Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)آن خط دوم همان چیزی است که افراد از آن غفلت میکنند. در یک سیستم تازه Ubuntu، دستور ~/.local/bin اغلب در PATH وجود ندارد، بنابراین هر دستور hep-* با خطای command not found مواجه میشود، حتی اگر نصب با موفقیت انجام شده باشد. آن را اصلاح کرده و تأیید کنید:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global statushep-global status گزارش میدهد که روتر سراسری چه چیزی را نصب کرده و چه harnessهایی را شناسایی کرده است. اگر این دستور اجرا شود، PATH شما صحیح است.
محل ذخیرهسازی وضعیت
همه چیز در قالب یک فایل در دایرکتوری home شما قرار دارد که پشتیبانگیری و مهاجرت را ساده میکند.
~/.agentlas/runtime/v1.2.0/شامل خود runtime است و~/.agentlas/runtime/current/به عنوان یک symlink به نسخه فعال عمل میکند. دو نسخه پینشده میتوانند در کنار هم قرار بگیرند.~/.local/bin/شامل wrapperهای shell است:hephaestus،hep-build،hep-network،hep-search،hep-storm،hep-cloudوhep-upload.~/.agentlas/networking/memory/شامل حافظه پایدار است:playbook-registry.json،playbook-candidates.jsonlوmemory-events.jsonl.~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqliteشامل تجربه هر agent است که بر اساس مالک محدود شده است.<project>/.agentlas/ontology-runtime.sqliteشامل وضعیت هر پروژه است، بنابراین به جای سرور، همراه با مخزن (repository) جابهجا میشود.~/.cache/agentlas/pythonشامل کش Python در Linux است. سیستمعامل macOS از مسیر متفاوتی استفاده میکند که همان شاخهای است که نصبکننده باunameانتخاب میکند.
مستندات حافظه بهصراحت بیان میکنند که اسرار، اعتبارنامههای خام و رونوشتهای کامل نباید در هیچ محدوده حافظهای قرار گیرند. مقادیر اعتبارنامهها در فایلهای محلی gitignored باقی میمانند و سوابق حافظه فقط نامها و مسیرها را ثبت میکنند. از ~/.agentlas و دایرکتوریهای پروژه .agentlas خود پشتیبان بگیرید تا بتوانید آن را روی یک VPS جدید بازسازی کنید.
مدلهای بکاندی که میتواند به آنها اشاره کند
در اینجا جزئیاتی وجود دارد که کل ساختار را بازتعریف میکند: Agentlas مستقیماً با API مدل تماس نمیگیرد، بلکه این کار توسط harness میزبان انجام میشود.
مستندات معماری، آداپتورهای زمان اجرا (runtime adapters) را توصیف میکنند که یک هسته را به هر harness ترجمه میکنند و بیان میدارند که زمان اجرای میزبان، مالک اعتبارنامههای مدل است. Agentlas دو سطح را ارائه میدهد که توسط harness دریافت میشوند: یک فایل AgentSkills و یک سرور MCP (پروتکل زمینه مدل) که از طریق stdio ارتباط برقرار میکند. بنابراین، پاسخ به این پرسش که «Agentlas از چه مدلهایی پشتیبانی میکند» در واقع این است که «harness شما از چه مدلهایی پشتیبانی میکند» و پاسخ، هر مدلی است که Claude Code، Codex، opencode، goose یا Hermes بتوانند به آن دسترسی داشته باشند.
ثبت سرور MCP در یک فایل پیکربندی TOML به سبک Codex به این صورت است:
[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]همین سرور در حین نصب بهطور خودکار در ~/.cursor/mcp.json، ~/.config/goose/config.yaml و سایر پیکربندیهای harness ثبت میشود. اگر قصد دارید چندین مورد از اینها را در یک سیستم واحد متصل کنید، اجرای سرورهای MCP روی یک VPS مدل stdio و پردازش را با جزئیات بیشتری بررسی میکند.
اشاره به یک endpoint محلی Ollama
از آنجا که harness مدیریت اتصال به مدل را بر عهده دارد، اشاره کردن Agentlas به مدلهای محلی به معنای تنظیم harness روی Ollama است. Ollama در نسخه 0.15 یک زیردستور launch دقیقاً برای همین منظور اضافه کرد که تا تاریخ 11 اوت 2026 در نسخه 0.32.9 نیز موجود است. این دستور، harness موجود را برای استفاده از مدلهای محلی پیکربندی میکند و نیازی به تنظیم متغیرهای محیطی (environment variables) ندارد:
ollama pull qwen3-coder:30b
ollama launch opencodeبسته به نوع harness که نصب کردهاید، به جای opencode از claude، codex یا droid استفاده کنید. سپس یک درخواست را از طریق runtime محلی هدایت کنید:
~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollamaدر صورت موفقیتآمیز بودن مسیر، یک پاسخ JSON شامل نام agent یا تیمی که انتخاب شده است به همراه یک receipt_id بازگردانده میشود. اگر پاسخ مفیدی دریافت نکردید، دلیل معمول آن طول context است. مستندات Agentlas برای نشستهای سنگین از نظر مسیریابی، مدلی با حداقل 64k context درخواست میکند و از qwen3-coder، gemma3 و deepseek-r1 به عنوان نمونه نام میبرد. راهنمای خود Ollama برای ابزارهای برنامهنویسی نیز همین حداقل 64k را توصیه میکند. تصمیمات مسیریابی، موجودی (inventory) agentها را در prompt حمل میکنند، بنابراین یک مدل با context 8k یا 32k باعث قطع شدن (truncate) موجودی شده و منجر به انتخاب نادرست میشود.
یک نکته مهم که در شعارهای تبلیغاتی گفته نمیشود: Ollama، Gemma و DeepSeek هیچ سیستم پلاگین یا دستور داخلی ندارند، بنابراین دستورات اسلش /agentlas در آنها وجود ندارد. در یک پیکربندی با مدل محلی، شما سیستم را از طریق سرور MCP و دستور hephaestus route کنترل میکنید. این یک کاهش واقعی در سطح دسترسی است و بهایی است که برای نگهداری وزنهای مدل روی سختافزار خود میپردازید.
هزینه رم برای مجموعهای از متخصصان غیرفعال چقدر است
هیچ. این پاسخ کامل است و شما میتوانید بهجای اعتماد کردن، آن را اثبات کنید.
متخصصان hub بهصورت آرتیفکتهای پکیج وارد میشوند، نه بهعنوان پردازشهای مجزا. هر متخصص شامل یک agent.md به همراه یک دایرکتوری .agentlas/ از فایلهای JSON است: routing-card.json برای تریگرها و قابلیتها، memory-map.json برای محدودیتهای نوشتن، و mode-map.json برای تعیین اینکه آیا بهصورت انفرادی اجرا میشود یا تیمی. شبکه Hephaestus بهعنوان یک زمانبند (scheduler) درونپردازشی بدون سرویس پسزمینه توصیف میشود. بین انجام وظایف، خودتان بررسی کنید:
pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlasدو دستور اول در یک سیستم غیرفعال هیچ خروجیای ندارند، زیرا هیچچیز در حافظه مقیم نیست. دستور سوم تنها هزینهای را نشان میدهد که یک hub پارکشده به شما تحمیل میکند، یعنی فضای دیسک؛ این مقدار با تعداد متخصصانی که نگهداری میکنید و مدل embedding همراه که runtime ارائه میدهد، افزایش مییابد.
بنابراین، پرسش درباره حافظه کاملاً به زمان burst مربوط است و burst شامل harness شما به همراه backend مدل است. اگر harness با یک API میزبانیشده در ارتباط باشد، هزینه مقیم بودن تنها یک پردازش با چند صد مگابایت حافظه است. اگر وزنهای مدل را خودتان میزبانی میکنید، وزنها همان هزینه اصلی هستند:
The data behind this chart
[
{
"label": "Hosted API model",
"weights_gb": 0
},
{
"label": "gemma3:4b",
"weights_gb": 3.3
},
{
"label": "gemma3:12b",
"weights_gb": 8.1
},
{
"label": "gemma3:27b",
"weights_gb": 17
},
{
"label": "qwen3-coder:30b",
"weights_gb": 19
}
]اینها اندازههای دانلود منتشرشده از کتابخانه مدل Ollama هستند، نه اندازهگیریهای حاصل از یک بنچمارک؛ و کش KV برای یک context با اندازه 64k به تمام ارقام بالا اضافه میشود. مدلی که مستندات Agentlas در ابتدا نام میبرد، یعنی qwen3-coder:30b، پیش از در نظر گرفتن context به 19 گیگابایت وزن نیاز دارد و حتی نسخه 27B مدل Gemma نیز 17 گیگابایت فضا میطلبد. در مقایسه با این اعداد، لایه Agentlas بهخودیخود در بودجه حافظه به چشم نمیآید.
مقایسه این روش با اجرای یک harness واحد
اجرای یک harness واحد روی یک API میزبانیشده باعث میشود VPS شما تنها یک پردازش را حمل کند. با افزودن Agentlas، همان یک پردازش به همراه فایلها اجرا میشود. ارکستراتور (orchestrator) یک برنامه با طول عمر زیاد و اضافی نیست؛ بلکه یک پرامپت بزرگتر است که از بستههای موجود روی دیسک جمعآوری شده و پس از اجرا حذف میشود.
هزینهای که در اینجا تغییر میکند، کانتکست (context) است، نه حافظه. ارکستراتوری که چندین کارت تخصصی و متادیتای مسیریابی آنها را فراخوانی میکند، در هر تسک نسبت به یک harness ساده، توکنهای بیشتری مصرف میکند. در یک API میزبانیشده، این به معنای هزینه مالی است تا اشغال RAM. در مدلهای محلی (local weights)، این هزینه به صورت زمان نمود پیدا میکند، زیرا پرامپت طولانیتر به معنای prefill طولانیتر روی CPU یا درگیری بیشتر GPU است.
به همین دلیل است که توصیههای مربوط به تعیین ابعاد (sizing) برای سروری مانند این، بر اساس تصمیمگیری برای مدل است و نه چارچوب عامل (agent framework). مقاله تعیین ابعاد RAM و CPU برای یک VPS عامل کدنویسی این موضوع را بهطور مفصل بررسی میکند و نتیجهگیری آن در اینجا نیز صادق است: پلن مناسب برای backend مورد نظر خود را انتخاب کنید و سپس چند گیگابایت فضای اضافی برای harness در نظر بگیرید. اگر برای مقایسه، طراحی ناظر همیشه روشن (always-on supervisor) را مد نظر دارید، harness چندعاملی Omnigent هماهنگکننده خود را در حافظه نگه میدارد که یک مبادله (trade-off) معکوس است و مستقیماً در میزان مصرف حافظه در حالت idle خود را نشان میدهد.
حالتهای شکست و رشتههایی که مشاهده خواهید کرد
hep-build: command not found بلافاصله پس از یک نصب تمیز. نصبکننده در ~/.local/bin نوشت، که در یک ایمیج پیشفرض Ubuntu روی PATH قرار ندارد. این موضوع در آخرین خط آن ذکر شده بود و خط از دید خارج شد. export نشاندادهشده در بالا را اضافه کنید.
تغییرات رفتار پس از بازسازی سرور. شما HEPHAESTUS_REF را تنظیم نکردید، بنابراین نصبکننده بهطور پیشفرض از هر تگی که در آن روز جاری بود استفاده کرد. آن را ثابت (Pin) کنید و نسخه ثابتشده را در کنار سایر شمارهنسخههای خود یادداشت کنید.
مسیریابی، متخصص اشتباهی را برای یک مدل محلی انتخاب میکند. پنجره کانتکست مدل برای فهرست عاملها (agent inventory) بسیار کوچک است. به مدلی با 64k یا بیشتر مهاجرت کنید و طول کانتکست Ollama را متناسب با آن تنظیم کنید، زیرا مقدار پیشفرض کمتر از آن چیزی است که ابزارهای برنامهنویسی نیاز دارند.
ollama launch شناسایی نمیشود. این زیردستور در نسخه Ollama v0.15 معرفی شد. بستههای قدیمیتر موجود در مخازن توزیعها قدیمیتر از این نسخه هستند، بنابراین یک نسخه بهروز از Ollama نصب کنید.
نصبکننده در harnessهایی مینویسد که انتظارش را نداشتید. اسکریپت هر harnessای را که پیدا کند شناسایی و پیکربندی میکند و در ~/.claude/، ~/.codex/، ~/.gemini/، ~/.cursor/ و موارد دیگر مینویسد. روی یک سرور build اشتراکی، پیش از اجرای اسکریپت آن را بخوانید و بدانید کدامیک از آن دایرکتوریها برای شما اهمیت دارند.
آیا باید همین حالا از آن استفاده کنید
پروژهای که تنها 10 هفته از عمر آن میگذرد و روزانه چندین بار انتشار خودکار (automated releases) دارد، گزینه مناسبی برای بارهای کاری عملیاتی (production workload) نیست. معماری این پروژه حقیقتاً جذاب است، مجوز آن Apache-2.0 است و طراحی مبتنی بر فایل آن به این معناست که حذف نصب تنها با پاک کردن دو دایرکتوری انجام میشود. این ویژگیها باعث میشود که تست کردن آن کمهزینه، اما تکیه بر آن پرهزینه باشد.
یک رویکرد منطقی در حال حاضر این است: نسخه v1.2.0 را ثابت (pin) کنید، آن را روی سروری اجرا کنید که امکان بازسازی آن را دارید، ~/.agentlas را در بکآپهای خود نگه دارید و پیش از تغییر نسخه، changelog را دوباره مطالعه کنید. برای بررسی جامعتر سایر گزینههای موجود در این حوزه و میزان بلوغ هر یک، بررسی جامع ایجنتهای هوش مصنوعی self-hosted نقطه شروع بهتری است و میزبانی یک ایجنت Hermes روی VPS یکی از بسترهایی را پوشش میدهد که Agentlas با آن سازگار است.
FAQ
آیا Agentlas OS به عنوان یک سرور روی VPS من اجرا میشود؟
خیر. هیچ دیمون (daemon)، پورت در حال گوش دادن (listening port) یا ایمیج کانتینری در مخزن وجود ندارد. نصبکننده یک محیط اجرا (runtime) در مسیر ~/.agentlas/runtime/ و بستهبندیهای دستور (command wrappers) را در ~/.local/bin مینویسد و Hephaestus Network یک زمانبند درونپردازشی (in-process scheduler) است، نه یک سرویس پسزمینه. میتوانید این موضوع را در یک سیستم بدون فعالیت بررسی کنید: دستور pgrep -af hephaestus هیچ خروجیای چاپ نمیکند و هیچ unit مربوط به systemd برای فعالسازی وجود ندارد. میزبانی شخصی (self-hosting) در اینجا به این معناست که کد و وضعیت روی دستگاه شما قرار دارند، نه اینکه سرویسی در حال گوش دادن باشد.
یک هاب از متخصصان غیرفعال چقدر رم مصرف میکند؟
هیچ، زیرا متخصصان غیرفعال، پردازش (process) نیستند. یک متخصص شامل یک فایل agent.md و یک دایرکتوری .agentlas/ است که حاوی routing-card.json، memory-map.json و متادیتای مشابه است، بنابراین یک هاب پارکشده فقط فضای دیسک اشغال میکند. آن را با du -sh ~/.agentlas اندازهگیری کنید. حافظه فقط در حین اجرای یک وظیفه مصرف میشود و آنچه آن را مصرف میکند، پردازش harness شما و مدل backend شماست، نه لایه Agentlas.
از چه مدلهایی میتوانم استفاده کنم و آیا میتوانم آن را به Ollama شخصی خود متصل کنم؟
Agentlas خودش با APIهای مدل تماس نمیگیرد. harness میزبان، مالک اعتبارنامهها و اتصال است، بنابراین مدلهای پشتیبانیشده همانهایی هستند که harness شما پشتیبانی میکند. برای وزنهای محلی (local weights)، دستور ollama launch opencode را اجرا کنید (با جایگزینی claude، codex یا droid) که harness را روی سرور Ollama شما بدون متغیرهای محیطی پیکربندی میکند. از مدلی با حداقل 64k کانتکست مانند qwen3-coder یا gemma3 استفاده کنید، زیرا پرامپتهای مسیریابی، موجودی عامل (agent inventory) را حمل میکنند و در پنجرههای کوچکتر به شدت ناقص میشوند.
کدام نسخه را باید نصب کنم و چرا پین کردن (pinning) در اینجا اهمیت دارد؟
نسخه v1.2.0 را که نسخه برچسبگذاریشده در تاریخ 12 August 2026 است، با تنظیم HEPHAESTUS_REF=v1.2.0 پیش از اجرای نصبکننده، نصب کنید. پیشفرض خود اسکریپت version="${HEPHAESTUS_REF:-v1.2.0}" است که هر آنچه را که نگهدارندگان در آینده برچسبگذاری کنند، دنبال میکند. پین کردن بیش از حد معمول اهمیت دارد، زیرا این پروژه بیش از صد نسخه در سری 1.1 خود منتشر کرده است (گاهی چندین نسخه در یک روز)، بنابراین یک بازسازی (rebuild) بدون پین کردن در هفتههای بعد، سیستمی که آزمایش کردهاید را به شما نخواهد داد.