Herdr: runtime cho agent viết code, điều khiển từ điện thoại

# Herdr: runtime cho agent viết code, điều khiển từ điện thoại Nguồn: https://modernengineer.dev/vi/library/herdr-complete-guide > **Tóm tắt nhanh:** Herdr giữ agent viết code chạy trong một server nền trên máy của bạn, còn terminal, laptop khác hay điện thoại chỉ là cửa sổ gắn vào. Đóng terminal hay rớt SSH, agent vẫn chạy tiếp. Thanh bên cho biết agent nào đang chờ bạn. Muốn điều khiển từ điện thoại, bạn SSH vào máy đó qua Tailscale rồi gõ `herdr`. Chạy một hai agent viết code trong vài tab terminal thì ổn. Tới lúc có ba bốn agent ở nhiều dự án, bạn bắt đầu phải lật từng tab để tìm agent đang xin quyền. Đóng nhầm cửa sổ là mất luôn phiên làm việc. Herdr giải quyết đúng chỗ đó: tiến trình sống trên server, còn bạn chỉ "nhìn vào" qua client. Lệnh, cấu hình và mức hỗ trợ từng hệ điều hành trong bài mình viết theo tài liệu chính thức của Herdr lúc rà soát tháng 10/2026. Herdr ra bản mới khá nhanh, nên khi một lệnh không chạy, bạn xem tài liệu chính thức trước. Đây là phần 1 của series Herdr. Mình bắt đầu từ lý do nên tách nơi agent chạy khỏi nơi bạn nhìn, rồi đi qua cơ chế phía sau, phần cài đặt, bộ cấu hình mình gợi ý, đường SSH qua Tailscale để điều khiển từ điện thoại, cuối cùng là những chỗ cách bố trí này còn hở. [Phần 2](https://modernengineer.dev/vi/library/herdr-multi-agent-workflows) dùng nền đó để cho agent điều phối agent. ## Tách nơi agent chạy khỏi nơi bạn nhìn Hai câu hỏi đáng đặt ra: khi bạn gập máy, rớt mạng hay cầm điện thoại ra ngoài, agent có còn chạy không? Bạn có biết ngay agent nào đang cần mình không? Theo [herdr.dev](https://herdr.dev/) và [hướng dẫn dành cho agent](https://herdr.dev/agent-guide.md) chính thức, Herdr trả lời bằng một server chạy nền giữ các tiến trình terminal thật, cùng tinh thần với tmux, cộng một client giao diện terminal (TUI, viết bằng Rust) để attach và detach. Pane vẫn chạy khi bạn đóng terminal hoặc ngắt SSH. Herdr nhận ra tiến trình agent trong pane và hiện trạng thái của nó trên thanh bên. Herdr có CLI và socket API (Application Programming Interface) cục bộ để script hoặc agent khác điều khiển. Bạn cũng dùng chuột được hoàn toàn: bấm vào pane, tab, workspace, kéo đường chia, mở menu chuột phải. Nghĩa là bạn không bắt buộc học phím tắt. Tài khoản X chính thức [@herdrdev](https://x.com/herdrdev/status/2072023156139708480) tóm ý tưởng này trong một câu (đại ý: Herdr cố ý không làm thành một ứng dụng; nó là runtime cho agent viết code): > "herdr isn't an app. that's by design. it's a runtime for your coding agents." Hình dung cụ thể: trên Mac Mini ở nhà, bạn chạy `herdr`, bật Claude Code trong một pane và giao việc. Bạn đóng cửa sổ terminal rồi ra ngoài ăn trưa. Trên điện thoại, bạn SSH vào Mac Mini, gõ `herdr` và thấy đúng pane đó, agent vẫn đang chạy dở lượt làm việc. Điều kiện là máy đó vẫn thức và còn mạng: MacBook gập nắp sẽ ngủ, kéo agent dừng theo. Vì vậy cũng cần nói rõ Herdr không làm gì: - Nó không phải IDE hay trình soạn thảo, không thay VS Code hay Cursor. - Nó không phải SaaS (Software as a Service) chạy agent trên đám mây. Máy tính toán mặc định là máy của bạn, hoặc máy bạn thuê. - Điện thoại không chạy agent, nó chỉ là cửa sổ client. - Herdr không thay model hay provider. Claude Code, Codex, Pi, OpenCode, Hermes vẫn là các agent CLI riêng. - Nó khác tmux ở chỗ có thêm trạng thái agent, phần tích hợp, socket API và plugin. Đặt cạnh các công cụ hay được nhắc cùng: | Công cụ | Vai trò | Hợp khi | | --- | --- | --- | | tmux, zellij | Giữ phiên shell | Bạn chỉ cần phiên shell, không cần trạng thái agent | | cmux | Terminal nhiều agent chạy trực tiếp trên macOS | Bạn thích giao diện đồ hoạ | | Termius, moshi | Ứng dụng SSH trên điện thoại | Làm cửa sổ nhìn vào Herdr | | Tailscale | Mạng riêng nối các thiết bị | Điện thoại cần nối về máy ở nhà hoặc VPS mà không mở SSH ra internet | | Docker, Vercel Sandbox | Thu hẹp phạm vi agent chạm tới máy chủ | Bạn muốn cô lập agent; mức an toàn còn tuỳ thư mục mount và quyền bạn cấp | ## Server giữ pane, client chỉ là cửa sổ Trước khi cài, bạn nên nắm cách các tầng xếp lên nhau. Phần này giúp bạn khỏi bất ngờ khi agent "mất" sau một lần tắt server.  *Client chỉ vẽ giao diện. Tiến trình sống ở tầng pane, do server giữ.* Server sở hữu pane và trạng thái tiến trình. Client chỉ vẽ giao diện và nhận phím, chuột. Bạn detach bằng `ctrl+b` rồi `q` (phím tiền tố mặc định). Ngồi tại máy, client nói chuyện với server qua Unix socket. Từ xa có hai cách: - `herdr --remote <host>`: client chạy trên máy bạn và nối tới server qua SSH. Vì client chạy tại chỗ nên Herdr chuyển được ảnh trong bộ nhớ tạm của máy bạn sang máy xa. - `ssh host` rồi `herdr`: mọi thứ chạy trên máy xa giống tmux, hợp với điện thoại. Công việc được tổ chức theo bốn cấp: - **Session** là một server nền tách biệt. Hầu hết mọi người chỉ cần session mặc định. - **Workspace** là vùng chứa theo dự án, repo hoặc một lần điều tra. Mỗi dự án đang làm nên có một workspace. - **Tab** là một bố cục trong workspace, ví dụ `agents`, `logs`, `server`, `review`. - **Pane** là terminal thật, chia sang phải hoặc xuống dưới. Pane là đơn vị ổn định để điều khiển qua CLI. Session đặt tên (`herdr session attach work`) tách hẳn nhau: pane, socket và trạng thái riêng, chỉ dùng chung file config. Đây là tách ở mức trạng thái Herdr, không phải quyền filesystem hay secrets; cần cô lập dữ liệu giữa khách hàng thì dùng user hoặc máy riêng. Còn lại cứ ưu tiên workspace. Herdr nhận ra agent từ ba nguồn: tiến trình đang chạy chính trong pane, screen manifest (bộ luật đọc phần đáy màn hình của từng agent) và phần tích hợp tuỳ chọn. Khi phần tích hợp có báo trạng thái, Herdr dùng báo cáo đó thay cho việc đọc màn hình. Kết quả là năm trạng thái: | Trạng thái | Nghĩa khi vận hành | | --- | --- | | `working` | Agent đang chạy một lượt | | `blocked` | Agent cần thông tin, phê duyệt hoặc một quyết định: **cần bạn** | | `done` | Agent xong nhưng bạn chưa xem | | `idle` | Agent xong hoặc đang chờ, đã được xem | | `unknown` | Herdr không phân loại chắc được; chạy `herdr agent explain` hoặc cài phần tích hợp | Xem một pane `done` trên client sẽ chuyển nó sang `idle` (mỗi client theo dõi riêng phần đã xem). Vì vậy script chờ agent nên chấp nhận **cả `done` lẫn `idle`** sau khi đã thấy `working`. Tài liệu Herdr cũng coi cả hai là sẵn sàng nhận việc mới. Thứ quan trọng nhất cần nhớ là cái gì còn lại sau mỗi kiểu ngắt: | Tình huống | Tiến trình còn chạy? | Cuộc hội thoại của agent | | --- | --- | --- | | Detach rồi attach lại | Có | Còn, vì tiến trình chưa từng dừng | | Khởi động lại server, hoặc `herdr server stop` rồi chạy lại | Không, bố cục được dựng lại với shell mới | Chỉ còn khi phần tích hợp hỗ trợ khôi phục phiên | | `herdr update --handoff` (thử nghiệm) | Cố gắng giữ, không đảm bảo | Còn nếu chuyển giao thành công | Hai mục liên quan nằm trong config: ```toml [session] resume_agents_on_restore = true # default [experimental] pane_history = false # default false; history có thể chứa secrets ``` `pane_history` lưu nội dung màn hình pane để hiện lại sau khi khởi động lại. Tài liệu để mặc định tắt vì đầu ra có thể chứa token, prompt hay secrets. Chỉ bật khi bạn chấp nhận coi thư mục config như lịch sử terminal. Khi agent chạy bên trong một pane, Herdr đặt sẵn `HERDR_ENV=1` cùng `HERDR_PANE_ID`, `HERDR_TAB_ID` và `HERDR_WORKSPACE_ID`. Skill `herdr` (chính thức) và `herdr-agent` (cộng đồng) dựa vào các biến này để agent không thao tác nhầm pane. Phần 2 sẽ dùng chúng nhiều. ## Cài và chạy agent đầu tiên Trên Linux và macOS, script chính thức là đường ngắn nhất: ```bash curl -fsSL https://herdr.dev/install.sh | sh herdr --version ``` Bạn cũng có thể dùng `brew install herdr` hoặc `mise use -g herdr`. Nix và cách tải file chạy thủ công nằm ở [trang cài đặt](https://herdr.dev/docs/install/). Trên Windows (PowerShell): ```powershell powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" ``` Theo tài liệu lúc rà soát, Herdr chạy trực tiếp trên Windows đã dùng được, nhưng vẫn có giới hạn riêng (ví dụ không gắn thẳng terminal vào agent được). Xem [trang hỗ trợ Windows](https://herdr.dev/docs/windows-beta/) trước khi dựa vào nó. Cài bằng script thì cập nhật bằng `herdr update`. Cài bằng Homebrew, mise hay Nix thì cập nhật bằng chính trình quản lý gói đó. Nếu shell báo không tìm thấy `herdr`, mở terminal mới hoặc kiểm tra thư mục cài đặt đã nằm trong `PATH` chưa. Herdr không cài agent hộ bạn. Trước bước tiếp theo, bạn cần ít nhất một agent CLI đã cài và đăng nhập trên chính máy chạy Herdr, ví dụ Claude Code theo [hướng dẫn bắt đầu nhanh chính thức](https://code.claude.com/docs/en/quickstart). Thay `my-project` bằng thư mục dự án có thật của bạn: ```bash cd $HOME/code/my-project herdr ``` Lần đầu, Herdr tạo session mặc định kèm một workspace và hiện màn hình giới thiệu. Trong pane, chạy agent bạn đã cài (`claude`, `codex`, `pi`, `opencode` hoặc agent khác Herdr hỗ trợ), thanh bên sẽ hiện trạng thái của nó. Sau đó thử vòng quan trọng nhất: detach bằng `ctrl+b` rồi `q` (hoặc đóng terminal), chạy lại `herdr` và thấy agent vẫn ở đó. `herdr server stop` chỉ dùng khi bạn cố ý tắt mọi pane. Phím tắt là tuỳ chọn. Phím tiền tố mặc định là `ctrl+b`, giống tmux: bấm `ctrl+b`, thả ra, rồi bấm phím hành động. Vài phím nên biết: - `c` mở tab mới. - `v` và `minus` chia pane. - `h/j/k/l` chuyển pane. - `w` chuyển workspace, `z` phóng to pane, `q` detach. - `prefix+?` mở bảng mọi phím đang có hiệu lực. Tiếp theo, cài phần tích hợp cho agent bạn thật sự dùng: ```bash herdr integration install claude herdr integration install codex herdr integration status ``` Danh sách còn có `pi`, `hermes`, `opencode`. Phần tích hợp làm việc khác nhau tuỳ agent. Với Claude Code, nó thêm khả năng khôi phục đúng cuộc hội thoại sau khi server khởi động lại, còn trạng thái vẫn đọc từ màn hình. Với Pi hay OpenCode, phần tích hợp còn báo trạng thái trực tiếp cho Herdr. Bảng đầy đủ ở [trang Agents](https://herdr.dev/docs/agents/). Nếu muốn agent tự dẫn bạn qua các bước này, tài liệu Herdr gợi ý dán prompt sau vào agent bạn đang dùng: ```text Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step. ``` ## Bộ cấu hình mình gợi ý Herdr chạy được mà không cần file config. Chỉ khi muốn đổi phím, bộ màu, thanh bên hay thông báo, bạn mới tạo file khởi điểm rồi sửa. Sau khi sửa, nạp lại cho server đang chạy mà không mất pane: ```bash herdr --default-config > $HOME/.config/herdr/config.toml # sửa xong: herdr server reload-config ``` File nằm ở `$HOME/.config/herdr/config.toml` trên Linux và macOS, `%APPDATA%\herdr\config.toml` trên Windows. `herdr --help` cho biết đường dẫn thực tế, biến `HERDR_CONFIG_PATH` đổi được đường dẫn đó. Gặp giá trị không hợp lệ, Herdr dùng giá trị mặc định an toàn và cảnh báo lúc khởi động chứ không sập. Phần lớn cài đặt giao diện có hiệu lực ngay sau khi nạp lại. Một số cài đặt chỉ đọc lúc khởi động thì vẫn cần khởi động lại server. Đây là bộ khung mình gợi ý cho dùng hằng ngày. `onboarding = false` là mục cấp gốc, nên đặt ở đầu file, trước mọi bảng `[...]`. Nếu file của bạn đã có các bảng này (ví dụ sinh từ `--default-config`), hãy sửa giá trị trong bảng có sẵn thay vì dán thêm bảng trùng tên: ```toml onboarding = false [terminal] # default_shell = "zsh" # chỉ bỏ comment khi shell này đã cài; tên file thực thi hoặc path new_cwd = "follow" # follow | home | current | path (vd. "~/Projects") [keys] prefix = "ctrl+b" [theme] name = "catppuccin" # mặc định; ví dụ khác: tokyo-night, gruvbox, terminal [ui.toast] delivery = "herdr" # herdr | terminal | system | off (mặc định: off) [session] resume_agents_on_restore = true ``` `new_cwd = "follow"` cho pane, tab, workspace mới lấy thư mục theo pane hoặc workspace nguồn; không có nguồn thì dùng `$HOME`. Tham số `--cwd` truyền qua CLI hay socket API vẫn được ưu tiên hơn cài đặt này. Thông báo mặc định tắt. Ngồi tại máy thì chọn `delivery = "herdr"`. Qua SSH thì chọn `"terminal"`, vì kiểu này nhờ terminal bên ngoài hiện thông báo. Nó chỉ hiện khi terminal đó hỗ trợ và đang giữ kết nối, không phải thông báo đẩy tới điện thoại. Khi phím tắt bạn tự chỉnh lệch so với bản Herdr mới, `herdr config reset-keys` sao lưu `config.toml`, xoá phần `[keys]` và `[[keys.command]]`. Sau khi khởi động lại hoặc nạp lại, Herdr dùng bộ phím mặc định mới. Bộ màu, thông báo và thanh bên không bị đụng. Khối `[[keys.command]]` là chỗ gắn một phím với một lệnh, ví dụ mở lazygit trong cửa sổ nổi, với điều kiện chương trình đó đã cài. Thanh bên là chỗ trả lời câu "agent nào đang cần mình". Ở dạng mở rộng trên màn hình lớn, thanh bên vẽ mỗi mảng con trong `rows` thành một dòng. Bố cục mặc định hiện có thêm token `machine` cho trường hợp bạn nối nhiều máy: ```toml [ui.sidebar.agents] row_gap = 0 rows = [ ["state_icon", "machine", "workspace", "tab"], ["agent"], ] ```  *Thanh bên gom trạng thái mọi agent vào một cột, pane đang được chọn nằm bên phải.* Với một máy duy nhất, token `machine` tự ẩn, nên mỗi agent hiện hai dòng: workspace kèm tab ở dòng trên, tên agent ở dòng dưới. Bạn có thể: - Thêm `state_text` để hiện chữ `working` hay `blocked`. - Đặt bố cục riêng cho từng agent bằng `rows_by_agent` (nó thay thế `rows`, không gộp thêm). - Hiện metadata tự đặt qua token `$name`, do script báo lên bằng `herdr pane report-metadata`. Danh sách token và luật trình bày ở [phần bố cục dòng của thanh bên](https://herdr.dev/docs/configuration/#sidebar-row-layouts). ## Điều khiển từ điện thoại qua Tailscale Tài liệu Herdr nói rõ: không cần ứng dụng di động hay trang quản lý trên trình duyệt, chỉ cần một ứng dụng SSH nối tới máy đang chạy agent. Theo hướng đó, máy ở nhà hoặc VPS vừa giữ code, git, secrets, đăng nhập agent CLI, vừa chạy Herdr server cùng các tiến trình agent. Tailscale nối mọi thiết bị thành mạng riêng, còn điện thoại chỉ là cửa sổ nhìn vào.  *Điện thoại chỉ giữ cửa sổ. Code, khoá và agent đều ở máy chủ.* ### Trên máy chủ Trên máy chủ (Mac hoặc Linux), cài Herdr, cài và đăng nhập agent CLI, cài phần tích hợp như phần trên. Sau đó: 1. Cài [Tailscale](https://tailscale.com/) và đăng nhập cùng tài khoản bạn sẽ dùng trên điện thoại. 2. Kiểm tra MagicDNS đang bật trong trang quản trị, để gọi máy bằng tên như `dev-box` thay vì IP. `tailscale status` và `tailscale ip -4` cho biết máy đã vào tailnet (mạng Tailscale của bạn) chưa. 3. Bật SSH server: trên macOS là System Settings, General, Sharing, Remote Login. Trên Linux là cài và bật `sshd`. Bài này dùng OpenSSH qua mạng Tailscale: SSH server bình thường của máy, xác thực bằng khoá SSH, chỉ đi trong tailnet. Tailscale SSH là lựa chọn khác: Tailscale chiếm cổng 22 trên IP tailnet và xác thực bằng tài khoản Tailscale thay cho khoá SSH. Phía máy chủ của cách này chỉ chạy trên Linux hoặc bản `tailscaled` mã nguồn mở trên macOS. Nếu chọn cách đó, làm theo [tài liệu Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh) và bỏ qua phần khoá SSH bên dưới. Rồi dựng session luôn chạy ngay trên máy chủ: `cd` vào dự án, chạy `herdr`, bật agent, chia pane, giao việc dài rồi detach. `herdr status` và `herdr agent list` xác nhận server vẫn sống sau khi detach. Muốn server tự chạy khi đăng nhập thì dùng launchd (macOS) hoặc dịch vụ systemd cho tài khoản của bạn (Linux). Cách đơn giản hơn là detach và để server sống theo phiên đăng nhập. ### Khoá SSH Làm theo đúng thứ tự này để không tự khoá mình ở ngoài: 1. Tạo cặp khoá trên thiết bị sẽ kết nối (ứng dụng SSH trên điện thoại thường có nút tạo khoá). Khoá riêng ở lại thiết bị đó, chỉ khoá công khai được mang sang máy chủ. 2. Thêm khoá công khai vào `~/.ssh/authorized_keys` của đúng tài khoản trên máy chủ. Chạy `whoami` trên máy chủ để biết tên tài khoản cần nhập vào ứng dụng. 3. Mở một phiên SSH mới bằng khoá và xác nhận vào được. Lần đầu kết nối, ứng dụng sẽ hỏi bạn có tin khoá nhận diện của máy chủ không. 4. Chỉ sau khi đăng nhập bằng khoá thành công mới tắt đăng nhập bằng mật khẩu. Đừng mở cổng 22 ra internet, chỉ cho vào qua giao diện mạng Tailscale. Fail2ban và tắt đăng nhập root là gia cố thêm, tuỳ chính sách của bạn. ### Trên điện thoại Cài Tailscale (iOS hoặc Android) và đăng nhập cùng tài khoản, máy ở nhà sẽ hiện trong danh sách. Cài ứng dụng SSH: trên iOS là [moshi](https://getmoshi.app/) (tài liệu Herdr nhắc tên) hoặc Termius, trên Android là Termux kèm `ssh` hoặc Termius. Thêm máy bằng tên MagicDNS hoặc IP Tailscale, tên tài khoản trên máy chủ và khoá riêng đã tạo, rồi: ```bash ssh you@dev-box herdr ``` Giao diện của Herdr tự co giãn trên màn hình hẹp: bạn xem được agent, chuyển workspace và kiểm tra pane ngay trong SSH. Từ một laptop khác trong tailnet, cách `--remote` hợp hơn, vì giao diện chạy tại chỗ và dán được ảnh từ bộ nhớ tạm: ```bash herdr --remote dev-box herdr --remote dev-box --session agents ``` Theo tài liệu lúc rà soát, `herdr --remote` chạy được từ client Linux, macOS và Windows tới máy chủ Linux, macOS hoặc Windows. Muốn giữ nhiều máy SSH trong cùng một cửa sổ Herdr, xem [trang nối nhiều máy](https://herdr.dev/docs/connecting-machines/). Trên màn hình nhỏ, đặt tên rõ cho agent và pane (`reviewer`, `impl`, `tests`), dùng thanh bên và menu chuyển (`prefix+g`) thay vì giữ nhiều pane chia dày. Chỉ cần một pane thì gắn thẳng vào agent đó bằng `herdr agent attach <target>` (chỉ có trên Linux và macOS). Agent bạn tự chạy trong pane chưa có tên, nên `<target>` là pane ID lấy từ `herdr agent list`. Muốn gọi bằng tên, đặt tên trước bằng `herdr agent rename <pane_id> reviewer` rồi `herdr agent attach reviewer`. Tên pane và tên agent là hai thứ khác nhau. ## Những chỗ cách bố trí này còn hở Soát lại cách bố trí ở trên với cơ chế vừa kể, có mấy chỗ bạn nên biết trước khi dựa vào nó. | Chỗ hở | Chuyện gì xảy ra | Nên làm | | --- | --- | --- | | Herdr không giữ máy thức | Máy ngủ thì agent dừng và điện thoại không SSH tới được. Gập nắp MacBook là máy ngủ; `caffeinate` mặc định chỉ chặn ngủ khi không ai dùng, không giữ máy chạy khi gập nắp. | Dùng Mac Mini hoặc máy bàn luôn cắm điện, chặn chế độ ngủ trong Settings hoặc bằng `caffeinate`. Đi lại nhiều thì dùng VPS luôn bật. | | Điện thoại không nhận thông báo đẩy | Thông báo kiểu `terminal` chỉ tới khi ứng dụng SSH đang mở và terminal hỗ trợ. | Mở lại ứng dụng để xem agent nào `blocked` hoặc `done`. | | Khởi động lại server không giữ tiến trình | `herdr server stop` hay khởi động lại dựng lại bố cục với shell mới; hội thoại chỉ quay lại khi phần tích hợp hỗ trợ khôi phục. | Việc đang chạy thì detach (`prefix+q`), đừng tắt server. | | Container chưa phải lý do để bỏ hỏi quyền | Theo [tài liệu bảo mật Docker](https://docs.docker.com/engine/security/), container vẫn sửa được thư mục mount từ máy chủ, và ai điều khiển được Docker daemon cũng có quyền rất lớn trên máy. | Xét thư mục mount, secrets và Docker socket trước khi bật chế độ bỏ qua hỏi quyền. Đừng tự động bấm Enter khi agent `blocked`, vì đó thường là câu hỏi tin cậy thư mục hoặc đăng nhập. | | Mọi thứ phải chạy trực tiếp trong pane | tmux lồng trong pane khiến Herdr chỉ thấy tiến trình `tmux`, nên thanh bên và lệnh chờ báo sai. `HERDR_AGENT=...` đặt toàn hệ thống làm mọi tiến trình kế thừa bị coi là agent đó. Gõ `herdr` trần khi có `HERDR_ENV=1` bị chặn theo mặc định. | Chạy agent thẳng trong pane, chỉ đặt `HERDR_AGENT` cho đúng tiến trình cần. | | Windows vẫn khác | Theo tài liệu lúc rà soát, Herdr trên Windows dùng được nhưng còn giới hạn riêng. | Đừng mong nó giống hệt Linux và macOS. | Nếu bạn mở rộng sang máy GPU, một cách ghép mình thấy hợp lý là Tailscale lo mạng, ứng dụng SSH làm cửa sổ, Herdr giữ session, Docker chạy agent để thu hẹp phạm vi nó chạm tới, với các lưu ý về container ở trên. ## Nếu bạn gặp lỗi Hầu hết lỗi đều quy về một câu: Herdr có thấy đúng tiến trình bạn nghĩ nó đang thấy không. Bắt đầu bằng `herdr status` (thêm `server` hoặc `client` để xem riêng từng phía) và `herdr agent list`. | Triệu chứng | Kiểm tra và cách sửa | | --- | --- | | Agent không hiện trên thanh bên hoặc ở trạng thái `unknown` | Chạy agent trực tiếp trong pane, cài phần tích hợp, rồi xem Herdr phân loại thế nào bằng `herdr agent explain <target> --json` (`<target>` là pane ID từ `agent list`, hoặc tên agent). `herdr integration status --outdated-only` cho biết phần tích hợp nào cần cập nhật. | | Phím tắt không phản hồi | Hệ điều hành hoặc terminal bên ngoài thường đã nuốt tổ hợp phím: xem [trang bàn phím](https://herdr.dev/docs/keyboard/) hoặc đổi phím tiền tố. | | Kết nối từ xa lỗi | Thử `ssh host` trần trước và kiểm tra MagicDNS. Với `herdr --remote` từ laptop và khoá có mật khẩu bảo vệ, chạy `ssh-add` trên laptop đó. | | Script chờ agent bị timeout | Chấp nhận cả `idle` lẫn `done`, và kiểm tra trạng thái `blocked`. | Khi cần đào sâu, chạy `HERDR_LOG=herdr=debug herdr` và đọc `herdr.log`, `herdr-client.log`, `herdr-server.log` trong `$HOME/.config/herdr/` (trên Windows là `%APPDATA%\herdr\`). ## Điều cần mang theo Herdr tách nơi agent sống (server trên máy của bạn) khỏi nơi bạn nhìn (client trên terminal, laptop khác hay điện thoại). Detach không giết agent. Tiến trình chỉ dừng khi bạn đóng pane, tắt hoặc khởi động lại server, hay máy tắt; máy ngủ thì agent dừng theo. Nếu mới bắt đầu, mình gợi ý đi theo thứ tự: 1. Cài Herdr. 2. Chạy một agent trong pane. 3. Cài phần tích hợp cho agent đó. 4. Thử detach rồi attach lại. 5. Sau cùng mới dựng Tailscale và SSH cho điện thoại. Series Herdr gồm hai phần: - Phần 1 (bài này, ai cũng đọc được): Herdr là gì, cài đặt, cấu hình và điều khiển từ điện thoại. - Phần 2 (dành cho Subscriber): [Herdr phần 2: cho agent điều phối nhiều agent song song](https://modernengineer.dev/vi/library/herdr-multi-agent-workflows). Khi đã quen với một máy và vài agent, phần này chỉ cách cho agent tự chia pane, giao việc, chờ nhau và đọc kết quả, cùng các workflow mẫu. Nguồn chính: [herdr.dev](https://herdr.dev/), [tài liệu Herdr](https://herdr.dev/docs/), [trang cấu hình](https://herdr.dev/docs/configuration/) và [bảng tham chiếu cấu hình](https://herdr.dev/docs/config-reference/), [trạng thái phiên và khôi phục](https://herdr.dev/docs/session-state/), [hướng dẫn dành cho agent](https://herdr.dev/agent-guide.md), [GitHub herdrdev/herdr](https://github.com/herdrdev/herdr).

[session]
resume_agents_on_restore = true   # default

[experimental]
pane_history = false              # default false; history có thể chứa secrets

curl -fsSL https://herdr.dev/install.sh | sh
herdr --version

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

cd $HOME/code/my-project
herdr

herdr integration install claude
herdr integration install codex
herdr integration status

Help me understand and set up Herdr.
Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.

herdr --default-config > $HOME/.config/herdr/config.toml
# sửa xong:
herdr server reload-config

onboarding = false

[terminal]
# default_shell = "zsh" # chỉ bỏ comment khi shell này đã cài; tên file thực thi hoặc path
new_cwd = "follow"      # follow | home | current | path (vd. "~/Projects")

[keys]
prefix = "ctrl+b"

[theme]
name = "catppuccin"   # mặc định; ví dụ khác: tokyo-night, gruvbox, terminal

[ui.toast]
delivery = "herdr"    # herdr | terminal | system | off (mặc định: off)

[session]
resume_agents_on_restore = true

[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "machine", "workspace", "tab"],
  ["agent"],
]

ssh you@dev-box
herdr

herdr --remote dev-box
herdr --remote dev-box --session agents

Đọc bài "Herdr: runtime cho agent viết code, điều khiển từ điện thoại" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "herdr-complete-guide". Nếu chưa nối MCP hoặc bị từ chối quyền, đọc thẳng trang https://modernengineer.dev/vi/library/herdr-complete-guide.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.

claude mcp add --transport http modernengineer \
  https://api.modernengineer.dev/mcp \
  --header "Authorization: Bearer <API key>"