SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

نصب و راه‌اندازی self-hosted HarnessRouter

آموزش deploy دقیق HarnessRouter با Docker برای اجرای Codex، Claude Code و Hermes پشت یک API؛ شامل bind روی loopback، تغییر login اولیه و دسترسی TLS.

HarnessRouter چه چیزهایی را حذف می‌کند

شما HarnessRouter Community Edition را به‌صورت self-host می‌کنید تا یک API را جلوی چند agent harness روی سروری که مالک آن هستید قرار دهید. agent harness همان برنامهٔ خط فرمانی است که یک مدل را در یک حلقه هدایت می‌کند: session را نگه می‌دارد، فایل‌ها را ویرایش می‌کند، فرمان‌ها را اجرا می‌کند و پیشرفت کار را برای هر چیزی که درخواست را ارسال کرده است، به‌صورت جریانی می‌فرستد. Codex، Claude Code و Hermes همگی همین کار را انجام می‌دهند و هرکدام روش نصب، قالب credential و برداشت خاص خود را از session دارند. HarnessRouter همهٔ آن‌ها را داخل یک container اجرا می‌کند و یک HTTP endpoint، یک login و یک secret store واحد را در مقابل آن‌ها قرار می‌دهد.

ایده همین است و باید هزینهٔ آن را صریح بیان کرد. شما یک container، یک login، یک volume و یک مسیر upgrade به سرور خود اضافه می‌کنید تا چند جزء متحرک به یک جزء تبدیل شوند. اگر امروز دقیقاً از یک harness استفاده می‌کنید، نصب مستقیم همان harness از این setup بهتر است. این trade-off در بخش پایانی همین مطلب بررسی می‌شود؛ بنابراین پیش از deploy کردن، آن بخش را بخوانید.

تمام مطالب زیر در برابر image tag 0.5.5 بررسی شده‌اند؛ این image در 19 August 2026 دریافت شده است. پروژه تقریباً هر روز tagهای جدید منتشر می‌کند؛ بنابراین به‌جای اعتماد به این صفحه در یک ماه آینده، tagی را که واقعاً اجرا می‌کنید بررسی کنید. در 8 November 2026 این صفحه در برابر documentation و source فعلی پروژه دوباره بررسی شد. در آن زمان، latest به 0.38.5 اشاره می‌کرد و در مواردی که releaseهای فعلی رفتار متفاوتی دارند، این تفاوت ذکر شده است. فرمان‌ها از repository پروژه در github.com/HarnessRouter/harnessrouter گرفته شده‌اند. این فرمان‌ها در README در 0.5.5 قرار داشتند؛ جزئیات setup اکنون در docs/self-hosting-guide.md در همان repository قرار دارد.

پروتکل Unified Harness Protocol واقعاً چیست

HarnessRouter پروتکل Unified Harness Protocol (UHP) را پیاده‌سازی می‌کند؛ این پروتکل در unifiedharnessprotocol.org منتشر شده است. UHP نحوه شروع یک task توسط یک product روی یک harness، پیگیری task هنگام اجرا، مدیریت sessionها و fileها و گزارش failure را مشخص می‌کند. این specification بر اساس تاریخ versionبندی می‌شود. نسخه‌ای که در 19 August 2026 فعال بود، تاریخ 2026-08-11 را داشت. از 8 November 2026، این سایت 2026-10-19 را به‌عنوان نسخه فعلی نمایش می‌دهد و همچنان آن را یک draft standard می‌نامد که «برای ساختن روی آن به‌اندازه کافی stable است و به‌گونه‌ای versionبندی شده که بتواند با ایمنی تغییر کند».

عبارت «open standard» را در اینجا با دقت بخوانید. همان شرکت specification، reference implementation و conformance suite را می‌نویسد؛ همین suite تعیین می‌کند چه کسی conformance دارد. همچنین قواعد governance پروژه می‌گویند هیچ تغییری وارد نمی‌شود، مگر آن‌که هر سه مورد هم‌زمان تغییر کنند. در 9 November 2026، صفحه اصلی protocol این suite را شامل 110 runnable check معرفی می‌کند، درحالی‌که صفحه conformance تعداد 101 را می‌گوید و reference run ثبت‌شده در self-hosting guide، با تاریخ 4 September 2026، تعداد 64 check موفق را نشان می‌دهد؛ بنابراین تعدادهای منتشرشده با یکدیگر سازگار نیستند. changelog پروژه، تاریخ 4 November 2026 را برای شش branching check اضافی ثبت کرده است. این وضعیت برای protocolی با چنین قدمت کمی عادی است و licence از نوع Apache-2.0 به این معناست که می‌توانید هر بخش آن را fork کنید. همچنین یعنی UHP هنوز یک standard چندفروشنده‌ای نیست. با آن مانند یک protocol نوظهور رفتار کنید: مفید است، در حال تغییر است و کدی که خودتان می‌نویسید باید بتواند بدون بازنویسی، استفاده از آن را متوقف کند.

پیش‌نیازها

به Docker و حدود 4 GB فضای خالی دیسک نیاز دارید. همچنین باید یک API key از model provider داشته باشید که پیش‌تر هزینهٔ آن را پرداخت کرده‌اید. حجم image pull حدود 700 MB است و فضای باقی‌مانده برای agent CLIها و workspaceهایی مصرف می‌شود که آن‌ها ایجاد می‌کنند. در image هیچ model یا trial keyای همراه نیست؛ بنابراین تا زمانی که یک provider را متصل نکنید، taskها fail می‌شوند. خود HarnessRouter تحت مجوز Apache-2.0 منتشر می‌شود. agent CLIها همچنان تابع licenseها و terms خود هستند و license مخزن جایگزین آن‌ها نمی‌شود؛ این CLIها در اولین start دریافت می‌شوند و در image قرار ندارند.

راه‌اندازی self-hosted HarnessRouter با یک docker run

docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

سپس بالا آمدن container را monitor کنید. اولین راه‌اندازی کند است و لاگ‌ها علت آن را مشخص می‌کنند.

docker logs -f harnessrouter

هنگام اجرا، خط‌هایی مشابه موارد زیر می‌بینید:

installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…

منتظر ready on :3000 بمانید. راهنمای فعلی زمان را از لحظه‌ای اندازه‌گیری می‌کند که docker run prompt شما را برمی‌گرداند، نه از آن خط؛ اگر http://localhost:3000 بلافاصله پس از خط آماده‌شدن پاسخ نداد، چند ثانیه بعد دوباره تلاش کنید. CLIهای نصب‌شده روی volume ذخیره می‌شوند؛ بنابراین راه‌اندازی‌های بعدی معمولاً بسیار سریع‌تر هستند. بااین‌حال، backendای که بعداً اضافه می‌کنید یا backendای که نصب آن قبلاً ناموفق بوده است، همچنان می‌تواند فرایند نصب را دوباره فعال کند.

از این دانلود دو نکته نتیجه می‌شود و هر دو در یک VPS اهمیت دارند. نخست، اولین boot به دسترسی خروجی شبکه نیاز دارد. image مستقل نیست؛ بنابراین سیستمی که پشت فیلتر egress قرار دارد یا هیچ route خروجی ندارد، نمی‌تواند CLIهای agent را دریافت کند. هر دو 0.5.5 و releaseهای فعلی، نصب‌های ناموفق را non-fatal در نظر می‌گیرند و نام آن‌ها را در لاگ می‌آورند؛ بنابراین بررسی کنید خط backends available: کدام backendها را فهرست نکرده است. دوم، شما نرم‌افزار شخص ثالث را بر اساس شرایط شخص ثالث نصب می‌کنید. Claude Code تحت شرایط Anthropic ارائه می‌شود و شرایط Hermes را upstream آن تعیین می‌کند؛ بنابراین پیش از استفاده تجاری، هر دو مورد را بررسی کنید.

-v harnessrouter:/data یک Docker volume نام‌گذاری‌شده ایجاد می‌کند. تمام داده‌های پایدار در /data قرار دارند: databaseهای SQLite، فایل‌های ذخیره‌شده، secret store و workspaceهای agent. با حذف این volume، instance را به‌طور کامل حذف می‌کنید؛ از جمله provider keyها و تمام transcriptها. زمانی از آن backup بگیرید که container متوقف باشد؛ زیرا کپی‌کردن database مربوط به SQLite هنگام write شدن ممکن است فایلی ایجاد کند که باز نشود. همین رویکرد توقف و سپس کپی‌کردن برای هر container دارای state روی سرور نیز لازم است؛ هرچند جزئیات به سرویس بستگی دارد، زیرا PhotoPrism و Immich هرکدام به commandهای backup مخصوص خود نیاز دارند.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
  tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouter

variant مربوط به compose و خطی که باید تغییر دهید

repository یک compose file ارائه می‌کند. این file اکنون "127.0.0.1:3000:3000" را منتشر می‌کند و host port را به loopback متصل می‌کند. file مربوط به 0.5.5، مقدار "3000:3000" را منتشر می‌کرد؛ اگر از file قدیمی روی یک public server استفاده می‌کنید، این خط را تغییر دهید.

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:0.5.5
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

volumes:
  harnessrouter-data:

یک تفاوت با upstream فعلی وجود دارد: به‌جای latest از یک version tag ثابت استفاده شده است. ثابت‌کردن version اهمیت دارد، زیرا releaseها با سرعت تغییر می‌کنند: هنگام بررسی در 8 November 2026، Docker Hub هر دو 0.38.4 و 0.38.5 را نشان می‌داد که در روز گذشته push شده بودند. runtime مربوط به agent که بدون اطلاع شما تغییر کند، به‌سختی debug می‌شود. به‌جای کپی‌کردن 0.5.5 از این صفحه، release فعلی را ثابت کنید؛ در 9 November 2026 این مقدار 0.40.0 بود. سپس environment file را کپی کنید، permissionهای آن را محدود کنید و سرویس را start کنید.

cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f

.env کلید provider شما را به‌صورت plain text نگه می‌دارد؛ بنابراین mode 600 حداقل لازم است. اگر subcommand مربوط به docker compose برایتان ناآشناست، برگه تقلب commandهای Docker Compose verbهای روزمره را پوشش می‌دهد.

چرا پورت روی 127.0.0.1 منتشر می‌شود، نه روی 0.0.0.0

-p 3000:3000 به‌طور پیش‌فرض پورت را روی همه رابط‌های شبکه‌ای میزبان منتشر می‌کند. -p 127.0.0.1:3000:3000 پورت میزبان را روی loopback منتشر می‌کند. نسخه‌های Docker قدیمی‌تر از 28.0.0 به میزبان‌های موجود در همان بخش L2 اجازه می‌دهند به پورت‌های منتشرشده روی localhost دسترسی پیدا کنند؛ همچنین فعال‌سازی صریح direct routing می‌تواند پورت container را با وجود نگاشت میزبان به loopback در معرض دسترسی قرار دهد. container به‌طور پیش‌فرض در داخل روی پورت 3000 گوش می‌دهد و این مقدار از طریق PORT قابل تنظیم است؛ بنابراین برای جلوگیری از تداخل پورت میزبان، عدد سمت چپ را تغییر دهید. نتیجه را بررسی کنید:

docker port harnessrouter
sudo ss -ltnp | grep 3000

نمایش ss توسط 127.0.0.1:3000 صحیح است. 0.0.0.0:3000 یعنی کنسول روی همه رابط‌های IPv4 در حال گوش‌دادن است؛ دسترسی از اینترنت عمومی همچنان به مسیریابی و filtering بستگی دارد. این وضعیت در اینجا از بیشتر برنامه‌های self-hosted خطرناک‌تر است، زیرا کنسول harness ایجاد می‌کند، همه transcriptها را می‌خواند، agentها را اجرا می‌کند و به آن agentها shell و یک filesystem واقعی در workspaceشان می‌دهد. همچنین کلید provider را که متصل کرده‌اید در اختیار دارد. هر فردی که به یک کنسول بدون حفاظت دسترسی پیدا کند، می‌تواند کار شما را بخواند، command اجرا کند و از کلید شما هزینه ایجاد کند.

یک قانون deny در ufw شما را از این وضعیت نجات نمی‌دهد. Docker ترافیک container منتشرشده را پیش از chainهایی که ufw مدیریت می‌کند، از طریق ruleهای خودش منحرف می‌کند؛ بنابراین نمایش یک پورت به‌صورت denied در sudo ufw status ثابت نمی‌کند که پورت منتشرشده مسدود است. آزمون را از یک ماشین دیگر انجام دهید، نه از VPS؛ در غیر این صورت چیزی را آزمایش نمی‌کنید. این همان نکته‌ای است که در اجرای dsh بدون رابط روی پورت 3080 مطرح شد: سرویس را به loopback bind کنید و سپس آگاهانه روش دسترسی به آن را تعیین کنید.

پیش از هر کار دیگری، ورود پیش‌فرض را تغییر دهید

در http://localhost:3000 با نام کاربری harnessrouter و گذرواژه اولیه‌ای که instance شما تولید کرده است، وارد شوید. آن را با دستور زیر بخوانید:

docker exec harnessrouter cat /data/selfhost-initial-password

گذرواژه مشترک harnessrouter در 0.5.5 معتبر بود؛ installationهای فعلی این مقدار پیش‌فرض منتشرشده را نمی‌پذیرند.

این مقدار را از صفحه Profile تغییر دهید یا برای یک deploy اسکریپت‌شده، هنگام start تنظیم کنید. HR_AUTH_USER و HR_AUTH_PASSWORD اعتبارنامه‌های اولیه را تعیین می‌کنند؛ اعتبارنامه‌هایی که از Profile ذخیره شده‌اند، اولویت دارند.

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER='you' \
  -e HR_AUTH_PASSWORD='the-password-you-chose' \
  harnessrouter/harnessrouter

برای ورود محلی به Console، ایمیل بازیابی وجود ندارد. اگر گذرواژه را از دست دادید، فایل auth را از volume حذف و سرویس را restart کنید. سپس با HR_AUTH_USER و HR_AUTH_PASSWORD تنظیم‌شده وارد شوید؛ اگر مقدار سفارشی تعیین نکرده‌اید، از گذرواژه اولیه تولیدشده استفاده کنید.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouter

HR_AUTH_DISABLED=1 دروازه ورود را کاملاً حذف می‌کند. راهنمای self-hosting این کار را «فقط برای ماشینی منطقی می‌داند که هیچ فرد دیگری نتواند به آن دسترسی داشته باشد». یک VPS با آدرس IP عمومی چنین ماشینی نیست؛ بنابراین این دروازه را فعال نگه دارید، مگر آن‌که این سرویس را روی یک laptop اجرا کنید.

نسخه خود را بررسی کنید، چون نسخه‌های قدیمی هیچ دروازه‌ای ندارند

این بخش را باید جدی بگیرید. نسخه‌های 0.1.x و 0.2.0 اصلاً هیچ سازوکار احراز هویتی نداشتند: هر کسی که می‌توانست به پورت 3000 دسترسی پیدا کند، از قبل وارد کنسول بود. 0.3.0 نخستین نسخه‌ای بود که ورود به سیستم را ارائه کرد. این صفحه در آخرین ثبت خود، در تاریخ 12 October 2026، این برچسب‌های قدیمی را منتشرشده و قابل دریافت اعلام کرده بود؛ در دسترس بودن فعلی آن‌ها در 8 November 2026 تأیید نشد.

در 19 August 2026، جدیدترین برچسب منتشرشده 0.5.5 بود که تاریخ آن 18 August 2026 ثبت شده بود. در 8 November 2026، latest به 0.38.5 اشاره می‌کرد. آنچه را در اختیار دارید بررسی کنید و سپس آن را با فهرست برچسب‌ها در Docker Hub مقایسه کنید:

docker image ls harnessrouter/harnessrouter

هر نسخه‌ای پایین‌تر از 0.3.0 باید همین حالا جایگزین شود، نه این‌که برای آن برنامه‌ریزی شود. نسخه‌های قدیمی که هنوز از گذرواژه پیش‌فرض مشترک استفاده می‌کنند نیز باید این گذرواژه را تغییر دهند؛ نصب‌های فعلی یک گذرواژه اولیه تولید می‌کنند و از شما می‌خواهند گذرواژه خودتان را انتخاب کنید. شماره نسخه‌های این صفحه را به‌عنوان نسخه‌های فعلی در نظر نگیرید. این شماره‌ها در تاریخ‌های ذکرشده درست بودند و این پروژه با سرعت زیادی نسخه‌های جدید منتشر می‌کند.

اتصال یک provider

تا زمانی که یک model provider متصل نشود، هیچ‌چیز اجرا نمی‌شود. از منوی account، گزینه Bring your own key را انتخاب و یک provider اضافه کنید، یا آن را در environment به docker run بدهید. مقدار آن JSON است؛ بنابراین آن را در shell داخل quote قرار دهید:

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'

.env.example برای هر خانواده provider یک connection variable نام‌گذاری می‌کند: HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC برای claude-code backend، HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI برای codex backend، HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE برای gemini backend و HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM برای هر OpenAI-compatible endpoint؛ aggregator یا inference server خودتان باید در همین بخش قرار گیرد. متغیرهای متناظر HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE، HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX و HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES مشخص می‌کنند هر backend به‌صورت پیش‌فرض از کدام connection استفاده کند و برای هر backend نیز یک policy variable وجود دارد. HR_SECRET_KEY موضوع جداگانه‌ای است. releaseهای فعلی credentialهای ذخیره‌شده را با استفاده از آن رمزنگاری می‌کنند و اگر مقداری برای آن ارائه نکنید، یک key در /data/secret-key ایجاد می‌کنند. همین key را در restart و upgradeها حفظ کنید. برای جدا نگه‌داشتن آن از data موجود در یک instance فعلی، HR_SECRET_KEY را برابر مقدار موجود در آن file قرار دهید و file را حذف کنید.

HR_BACKENDS مشخص می‌کند کدام backendها install و load شوند؛ نمونه آن در HR_BACKENDS=claude,codex,hermes آمده است. اگر این متغیر را unset بگذارید، releaseهای فعلی فهرست پیش‌فرض بسیار طولانی‌تری شامل 30 backend را install می‌کنند؛ این فهرست از claude، codex و hermes تا opencode، gemini، goose و موارد دیگر ادامه دارد. بنابراین کوتاه‌کردن آن، فضای دیسک و زمان first-start را کاهش می‌دهد. self-hosting guide فعلی می‌گوید اگر از backendی استفاده نمی‌کنید، «آن را از HR_BACKENDS حذف کنید» و نمونه کمینه خود guide نیز HR_BACKENDS=opencode است که Hermes را کاملاً حذف می‌کند. اگر نصب یک backend با failure مواجه شود، این failure fatal نیست: backendهای دیگر همچنان کار می‌کنند و task روی backendی که install نشده است با پیام «not installed» رد می‌شود؛ log مربوط به container نیز install ناموفق را مشخص می‌کند. README مربوط به 0.5.5 یک known issue داشت که در آن حذف hermes باعث می‌شد container بلافاصله با status 1 و بدون پیام خطا خارج شود، اما entrypoint همان tag اکنون این failure را برطرف کرده است؛ commentهای آن implementation قبلی را توضیح می‌دهند. اگر تنها harness موردنظر شما Hermes است، اجرای agent مربوط به Hermes روی VPS مستقل خودتان deployment کوچک‌تری است.

فراخوانی API بدون console

استفاده از console اختیاری است. هر دو مورد از همان API استفاده می‌کنند و این API از قراردادی به سبک Responses پیروی می‌کند. ابتدا وارد شوید تا یک session cookie دریافت کنید:

curl -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"your-password"}'

سپس یک task ارسال کنید و در metadata.harness_id نام harness و در بخش مدل، مدلی را مشخص کنید که provider متصل شما واقعاً ارائه می‌دهد:

curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
  -H 'content-type: application/json' \
  -d '{"input":"Reply with exactly this and nothing else: it works.",
       "metadata":{"harness_id":"codex"},
       "model":"gpt-5.4-mini",
       "stream":false}'

وجود یک شیء JSON شامل یک output block و تعداد tokenها نشان می‌دهد که harness اجرا شده است. اگر harness_id را از codex به claude-code تغییر دهید، همان request به harness دیگری ارسال می‌شود؛ همین امکان تغییر، دلیل اصلی وجود این software است. توجه کنید که id برابر با claude-code است، هرچند نام backend در HR_BACKENDS و متغیر policy در claude قرار دارد. اتصال سفارشی بالا روشی است که با آن یک harness را به endpoint سازگار با OpenAI که از قبل میزبانی می‌کنید متصل می‌کنید؛ مشابه یک harness مربوط به DeepSeek که روی VPS میزبانی می‌شود که به همین روش متصل شده است.

روند استفاده از session cookie همچنان برای debugging محلی پشتیبانی می‌شود. برای backend محصول، مستندات فعلی توصیه می‌کنند یک HarnessRouter API key در API Keys ایجاد کنید و آن را به‌جای نگه‌داری یک Console session، به‌صورت Bearer token ارسال کنید.

بدون انتشار پورت، از لپ‌تاپ به آن دسترسی پیدا کنید

دو روش وجود دارد و هیچ‌کدام از آن‌ها به بازکردن مستقیم یک پورت روی 0.0.0.0 نیاز ندارد.

تونل SSH کم‌هزینه‌ترین روش است و به نصب هیچ نرم‌افزاری روی سرور نیاز ندارد. این تونل یک پورت محلی روی سیستم شما را به loopback روی VPS هدایت می‌کند.

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

این فرایند را در حال اجرا نگه دارید و http://localhost:3000 را در مرورگر باز کنید. اگر SSH پیام bind: Address already in use را چاپ کرد، برنامه‌ای روی لپ‌تاپ شما از قبل پورت 3000 را در اختیار دارد. در این حالت، با -L 3100:127.0.0.1:3000 یک پورت محلی دیگر انتخاب کنید و پورت 3100 را در مرورگر باز کنید.

reverse proxy با TLS termination زمانی مناسب است که افراد دیگری نیز باید به سرویس دسترسی داشته باشند. proxy گواهی TLS (امنیت لایه انتقال) را نگه می‌دارد و درخواست‌ها را به loopback هدایت می‌کند. راهنمای self-hosting یک پیکربندی Caddy ارائه می‌دهد:

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1      # agent turns stream for minutes; never buffer them
    }
}

flush_interval -1 بافرکردن پاسخ‌های Caddy را صراحتاً غیرفعال می‌کند؛ Caddy بدون آن نیز پاسخ‌های text/event-stream را بلافاصله flush می‌کند. Agent توکن‌های stream را برای چند دقیقه تولید می‌کند. اگر proxy پاسخ را بافر کند، این توکن‌ها تا پایان turn نگه داشته می‌شوند. در نتیجه، console ثابت به نظر می‌رسد و سپس همه‌چیز را یک‌باره چاپ می‌کند. معادل این تنظیم در Nginx، proxy_buffering off; داخل بلوک location است. هرکدام را انتخاب می‌کنید، نام DNS را به proxy و container را به loopback متصل نگه دارید. مقایسه Nginx، Caddy و Traefik به‌عنوان reverse proxy بررسی می‌کند کدام گزینه برای سرور شما مناسب‌تر است.

آن را با کاربر اختصاصی اجرا کنید، نه با root

Docker daemon با root اجرا می‌شود و عضویت در گروه docker معادل دسترسی root است، زیرا عضو این گروه می‌تواند containerای را اجرا کند که فایل‌سیستم میزبان را mount می‌کند. بنابراین، «تیم را به گروه docker اضافه کنید» در واقع دسترسی root به سیستمی می‌دهد که کلید provider شما را نگه‌داری می‌کند.

نسخه ساده: یک service account بسازید که مالک compose file و .env باشد و این فایل‌ها را خارج از هر shared home directory نگه دارید.

sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter

برای رسیدن به این هدف، --user را به docker run یا user: را به compose file اضافه نکنید. راهنمای فعلی می‌گوید container باید با root شروع شود و از 0.8.2 به بعد، شروع‌شدن با هر روش دیگری را رد می‌کند؛ در لاگ نیز یک خط این موضوع را اعلام می‌کند.

نسخه ایمن‌تر، rootless Docker است که در آن خود daemon با همان کاربر بدون دسترسی ویژه اجرا می‌شود. این روش برای newuidmap و newgidmap به package uidmap نیاز دارد و باید دست‌کم 65536 subordinate UID در /etc/subuid و /etc/subgid برای کاربر وجود داشته باشد. uidmap در Ubuntu archive موجود است، اما docker-ce-rootless-extras وجود ندارد؛ این package از apt repository اختصاصی Docker در download.docker.com ارائه می‌شود و نصب Docker engine آن را اضافه می‌کند. اگر engine را از این repository نصب نکرده‌اید، grep -rl download.docker.com /etc/apt/sources.list.d/ چیزی چاپ نمی‌کند و نصب زیر package را پیدا نخواهد کرد.

sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now docker

loginctl enable-linger باعث می‌شود systemd instance کاربر پس از logout همچنان اجرا شود و هنگام boot نیز شروع شود. نتیجه را با docker info بررسی کنید؛ این دستور rootless را در بخش Security Options فهرست می‌کند. rootless mode بدون پیکربندی اضافی نمی‌تواند portهای کمتر از 1024 را bind کند؛ این موضوع در اینجا اهمیتی ندارد، زیرا port 3000 بالاتر از این مقدار است. راه‌اندازی خود account در ساخت کاربران با حداقل سطح دسترسی در VPS توضیح داده شده است.

چه چیزهایی باعث خرابی می‌شوند و چه چیزی خواهید دید

کانتینر یک ثانیه پس از شروع خارج می‌شود و لاگ‌ها خالی هستند. docker ps -a مقدار Exited (1) را نشان می‌دهد. یک entrypoint قبلی زمانی شکست می‌خورد که HR_BACKENDS، hermes را نداشت؛ اما 0.5.5 از قبل اصلاح لازم را دارد، هرچند README آن هنوز این issue را فهرست می‌کند. این خرابی را فقط بر اساس exit status تشخیص ندهید. در یک tag جدید، آخرین خط docker logs را بخوانید: از 0.8.2، کانتینری که با --user شروع شده باشد، با یک خط خارج می‌شود که می‌گوید باید به‌عنوان root شروع شود.

شروع اول هرگز تمام نمی‌شود. لاگ پس از یک خط installing متوقف می‌شود و ready on :3000 هرگز ظاهر نمی‌شود. بررسی کنید که سرور بتواند برای دریافت agent CLIها به شبکه دسترسی داشته باشد، زیرا این ابزارها داخل image قرار ندارند. هر دو مورد 0.5.5 و releaseهای فعلی، خطاهای install تکمیل‌شده را تحمل می‌کنند؛ installهای ناموفق را در لاگ نام می‌برند و آن‌ها را از خط backends available: حذف می‌کنند. route خروجی یا تنظیمات proxy را اصلاح کنید و سپس سرویس را restart کنید.

کنسول بارگذاری می‌شود، اما هر task شکست می‌خورد. هیچ providerی متصل نیست. داخل image هیچ model همراهی وجود ندارد و free tier نیز ارائه نمی‌شود؛ بنابراین یک instance تازه می‌تواند امکان ورود به سیستم را فراهم کند، اما هیچ کاری اجرا نخواهد شد.

کنسول در میانه پاسخ و پشت proxy متوقف می‌شود. خروجی هنگام پایان turn، یک‌جا نمایش داده می‌شود. این مشکل ناشی از response buffering است. در Caddy مقدار flush_interval -1 را تنظیم کنید یا در Nginx مقدار proxy_buffering off; را تنظیم کنید.

از laptop خود به آن دسترسی ندارید، درحالی‌که tunnel برقرار است. روی سرور docker port harnessrouter را اجرا کنید. اگر چیزی چاپ نشد، کانتینر هیچ پورتی را publish نمی‌کند؛ بنابراین port mapping و network mode آن را بررسی کنید.

آیا اجرای آن ارزش دارد؟

اگر واقعاً از بیش از یک harness استفاده می‌کنید و به‌جای سه endpoint و سه محل نگهداری credential، یک endpoint و یک محل نگهداری credential می‌خواهید، اجرای آن ارزش دارد. اگر محصولی را بر پایه آن می‌سازید و می‌خواهید harness یک مقدار پیکربندی باشد، نه چیزی که برای تغییرش به بازنویسی نیاز باشد، اجرای آن ارزش دارد. UHP همین قابلیت را فراهم می‌کند؛ البته با در نظر گرفتن نکته قبلی درباره جوان‌بودن protocol.

اگر از یک harness استفاده می‌کنید، اجرای آن ارزش ندارد. نصب همان CLI روی سرور اجزای کمتری دارد و هیچ loginای بین شما و آن قرار نمی‌گیرد. اگر هدف شما همکاری چند agent روی یک task است، نه قرار گرفتن یک API در برابر چند harness، این ابزار نیز ساختار مناسبی ندارد و ابزار دیگری برای این نیاز است: برای این الگو، یک harness چندعاملی مانند Omnigent را ببینید. در هر دو حالت، قواعد deployment تغییر نمی‌کنند. bind روی loopback، تغییر password، استفاده از یک release فعلی و pinned، و اجرای آن با user اختصاصی.

FAQ

آیا انتشار HarnessRouter روی پورت 3000 ایمن است؟

خیر. کنسول harness ایجاد می‌کند، همه transcriptها را می‌خواند، agentها را با دسترسی به shell و filesystem اجرا می‌کند و کلید provider متصل‌شده را نگه می‌دارد؛ بنابراین کنسولی که بدون محافظت منتشر شود، همه این موارد را در معرض دسترسی قرار می‌دهد. سرویس را با -p 127.0.0.1:3000:3000 روی loopback منتشر کنید و از طریق SSH tunnel یا reverse proxy دارای TLS termination به آن دسترسی پیدا کنید. یک قانون deny از نوع ufw به‌تنهایی کافی نیست: Docker ترافیک container منتشرشده را پیش از chainهایی که ufw مدیریت می‌کند، منحرف می‌کند. با sudo ss -ltnp | grep 3000 بررسی کنید؛ این دستور باید 127.0.0.1:3000 را چاپ کند. همچنین دسترسی را از یک ماشین دیگر آزمایش کنید. برای جلوگیری از exposure قدیمی localhost در همان L2، از Docker 28.0.0 یا نسخه‌های جدیدتر استفاده کنید و بررسی کنید که direct routing فعال نشده باشد.

کدام نسخه HarnessRouter دروازه ورود را اضافه کرد؟

0.3.0. نسخه‌های 0.1.x و 0.2.0 بدون هیچ احراز هویتی منتشر شدند؛ بنابراین هرکس آن‌ها را اجرا کند، به این امید متکی است که هیچ‌کس پورت را پیدا نکند. این صفحه آخرین بار در 12 October 2026 ثبت کرده است که این tagها منتشرشده و قابل pull بوده‌اند؛ availability فعلی آن‌ها در 8 November 2026 تأیید نشده است. در 19 August 2026، جدیدترین tag برابر با 0.5.5 و تاریخ آن 18 August 2026 بود؛ در 8 November 2026، latest به 0.38.5 اشاره می‌کرد. برای مشاهده نسخه موجود، docker image ls harnessrouter/harnessrouter را اجرا کنید. آن را با فهرست tagها در Docker Hub مقایسه کنید، نه با این صفحه، و password خودتان را انتخاب کنید. نصب‌های فعلی به‌جای پذیرش مقدار پیش‌فرض مشترک قدیمی، یک password اولیه تولید می‌کنند.

چرا container بلافاصله پس از تنظیم HR_BACKENDS خارج می‌شود؟

در یک release فعلی نباید چنین اتفاقی بیفتد. راهنمای self-hosting می‌گوید هر backendای را که استفاده نمی‌کنید حذف کنید و نصب ناموفق یک backend نباید fatal باشد. یک پیاده‌سازی قدیمی وقتی hermes حذف شده بود، با status 1 و بدون پیام خطا خارج می‌شد؛ اما source مربوط به 0.5.5 این خطا را برطرف کرده است، با وجود آن‌که README آن هنوز این مورد را فهرست می‌کند. در یک tag جدید، docker logs را بخوانید: از 0.8.2، containerای که با --user شروع شده باشد، با یک خط پیام خارج می‌شود که می‌گوید باید به‌صورت root شروع شود.

آیا HarnessRouter در اولین start به دسترسی اینترنت نیاز دارد؟

بله. CLIهای agent در اولین start دریافت می‌شوند و داخل image قرار ندارند؛ همچنین هرکدام همچنان مشمول license و terms مخصوص خود هستند. هم 0.5.5 و هم releaseهای فعلی، نصب‌های ناموفق را در log ثبت می‌کنند و اجازه می‌دهند backendهای دیگر start شوند. CLIهای نصب‌شده روی volume cache می‌شوند؛ بنابراین startهای بعدی معمولاً سریع‌تر هستند. بااین‌حال، ابزارهای backend و taskهایی که اجرا می‌کنید ممکن است همچنان به دسترسی شبکه نیاز داشته باشند و یک backend جدید یا backendی که قبلاً نصب آن ناموفق بوده است، می‌تواند نصب دیگری را آغاز کند.

password کنسول را گم کرده‌ام. چگونه دوباره وارد شوم؟

برای login محلی Console، reset email وجود ندارد. container را متوقف کنید، /data/selfhost-auth.json را از volume حذف کنید، سپس container را دوباره start کنید و با HR_AUTH_USER و HR_AUTH_PASSWORD پیکربندی‌شده وارد شوید؛ اگر password دلخواه خود را تعیین نکرده‌اید، از password اولیه تولیدشده استفاده کنید. سپس از صفحه Profile یک password جدید تعیین کنید. اگر نام container و volume هر دو harnessrouter باشند، این کار به‌ترتیب با docker stop harnessrouter، سپس docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json و بعد docker start harnessrouter انجام می‌شود. password تولیدشده را با docker exec harnessrouter cat /data/selfhost-initial-password بخوانید.

آیا این مقاله مفید بود؟