HarnessRouter

Tổng quan

HarnessRouter là lớp hạ tầng hợp nhất nhiều “agent harness” như Claude Code, Codex, Hermes và OpenCode sau một API tương thích OpenAI Responses. Thay vì tự viết logic khởi chạy, tiếp tục hội thoại, stream, nhận file và hủy tác vụ cho từng CLI, đội sản phẩm gọi một giao diện rồi chọn harness qua metadata. Community Edition đóng gói Console, Gateway và Runner trong một container Docker, lưu session, file, secret và workspace trên volume của người dùng.[3]

Tại commit được kiểm tra, catalog có 20 base và Runner có đường thực thi tương ứng cho cả 20, từ Codex, Claude Code, Hermes đến OpenHands, Agent Zero và System One.[4][6] Đây không chỉ là danh mục marketing, nhưng phạm vi lớn khiến việc kiểm soát phiên bản và khác biệt hành vi giữa CLI trở thành bài toán vận hành chính.

Tính năng chính

Một request có thể mở task, tiếp tục bằng previous_response_id, nhận tiến độ qua Server-Sent Events, đính kèm file bằng upload hoặc file_id, lấy output và gửi cancel. Khi SSE rớt, công việc vẫn chạy; client có thể đọc response và turn đã lưu. Workspace giữ cả file lẫn state hội thoại của CLI để follow-up resume sau khi tiến trình được tái tạo.[4]

Mỗi session chạy dưới UID và workspace riêng. “Write-wall” cấp hệ điều hành này chặn agent đọc file của session khác, nhưng vẫn là nhiều process trong cùng container, không phải máy ảo riêng từng task. Agent có shell và network thật; Claude Code bỏ permission prompt, còn Codex dùng full access trong runtime.[6][7]

Catalog phân biệt tool restriction “hard” và loại chỉ là instruction. Claude Code, Pi, OpenCode cùng nhiều adapter có thể loại tool hoặc chặn lúc execute; Codex, Hermes, DeepSeek Harness, Qwen, Gemini và Cline chủ yếu nhận hướng dẫn không dùng tool. Vì vậy, tắt “Shell” trong UI không phải lúc nào cũng tạo security boundary.

Cài đặt và vận hành

Cách cài chính là Docker: publish port trên loopback, gắn /data, rồi đợi container tải CLI ở lần chạy đầu.[3] Thiết kế này tránh phân phối lại phần mềm có điều khoản riêng, nhưng first boot nặng và phụ thuộc mạng. Phần lớn backend được pin; OpenCode mặc định lấy latest, Qwen và Pi không pin, nên volume mới có thể nhận byte khác dù image HarnessRouter không đổi.[7]

Cần harden trước khi dùng thật. Console mặc định là harnessrouter/harnessrouter. Lệnh Docker trong README bind 127.0.0.1, nhưng Compose dùng 3000:3000, có thể mở trên mọi interface.[3][9] Không nên dùng Compose nguyên trạng trên host public; hãy đổi password, bind loopback hoặc đặt reverse proxy TLS/auth.

Credential cũng cần chú ý. Key từ biến môi trường được ưu tiên và không ghi xuống volume. Key lưu qua UI được mã hóa AES-256-GCM nếu có HR_SECRET_KEY, nhưng provider connection không bắt buộc khóa này; thiếu nó, secret store có thể ghi plaintext mode 0600. Riêng database credential bị từ chối nếu chưa cấu hình mã hóa.[4][5] Redaction bảo vệ output và trace, không ngăn agent gửi secret ra ngoài, nên token phải ngắn hạn, đúng scope và có thể thu hồi.

Điểm mạnh

Điểm mạnh lớn nhất là chiều sâu tích hợp. Session, trace, file, cancellation và lỗi có schema chung; Runner chuẩn hóa event của từng CLI. Upload mặc định giới hạn 25 MiB, output có giới hạn số lượng/kích thước, cancellation kill process group và descendants thay vì chỉ tiến trình cha.[4][6] Repository còn có UHP specification, schema máy đọc được và conformance suite, giúp giao diện chung có tiêu chuẩn kiểm thử.[17]

CI đúng commit xanh sáu job cho Gateway, Runner, Console, conformance, website spec và badge. Release pipeline build rồi smoke-test image native trên amd64 lẫn arm64 trước khi ghép manifest.[13][14] Kiểm tra độc lập ghi nhận 1.808 assertion pass ở các suite thành công, cùng production build Console và package build UHP. Đây là chứng cứ unit/mock và build, chưa xác nhận mọi provider/model ngoài đời.

Hạn chế

Bề mặt đặc quyền rộng là chủ đích, không phải chi tiết phụ. UID riêng bảo vệ chéo session nhưng không chặn Internet, không thay thế sandbox VM và không làm credential vô hại. Gateway cũng có thể ghi cancelled khi call kill Runner thất bại; hệ thống đích vẫn nên hỗ trợ idempotency và đối soát side effect.

Lease của hai turn cùng session mặc định chỉ quan sát, không chặn overlap; lỗi control-store fail-open. Client nên serialize turn hoặc operator bật enforce. Dự án mới từ ngày 9/8/2026 nhưng đã có 178 GitHub Release object: nhịp phát hành cao cho thấy hoạt động mạnh, đồng thời buộc đội vận hành pin tag/digest và thử staging trước khi nâng cấp.

Phù hợp khi nào

HarnessRouter hợp với đội xây sản phẩm cần thử hoặc chuyển đổi giữa nhiều coding/knowledge agent mà không muốn duy trì 20 integration riêng. Nó cũng hữu ích cho lab nội bộ muốn self-host session, file và trace. Nếu yêu cầu isolation cứng theo tenant, zero-egress, credential broker bắt buộc hoặc public deployment “cắm là chạy”, Community Edition cần thêm hardening đáng kể. Đây là control plane mạnh cho agent có quyền hành động, không phải hộp cát tự động biến mọi CLI thành an toàn.