telepty — control plane cho phiên AI agent phân tán trên nhiều máy

telepty là một control plane phiên agent gọn nhẹ, cho phép gửi chỉ thị từ xa và đọc màn hình của các phiên terminal AI CLI (claude, codex, gemini, v.v.) đang chạy trên nhiều máy — phần suy luận và công việc vẫn do từng agent thực hiện như cũ (data plane), còn telepty chỉ đảm nhiệm lớp gọi địa chỉ các phiên đó và bảo đảm việc chuyển giao (daemon nền dựa trên PTY + session bridge). Mỗi phiên được gán địa chỉ theo tên, xác nhận đến cả việc chỉ thị đã thực sự được tiếp nhận, và hỗ trợ macOS·Linux·Windows. Việc truyền giữa các máy không tự xây dựng mà đặt trên Tailscale(WireGuard) đã được kiểm chứng — thay vì tự triển khai trao đổi khóa·NAT traversal·mã hóa và làm tăng bề mặt tấn công, chúng tôi chọn ủy thác cho một lớp đã được kiểm chứng qua nhiều năm vận hành thực tế. Đây là mã nguồn mở theo giấy phép MIT.

npm i -g @dmsdc-ai/aigentry-telepty && telepty daemon start  
  
# Bọc nguyên CLI đang dùng thành một phiên có tên (mỗi máy làm một lần)  
telepty allow --id orchestrator claude    # phiên claude trên máy này → "orchestrator"  
  
telepty inject "backend@100.x.y.z" "Bắt đầu refactor middleware xác thực nhé"   # chỉ thị cho phiên từ xa  
telepty read-screen "backend@100.x.y.z"                               # kiểm tra tiến độ  
telepty broadcast "Hoàn tất công việc và báo cáo trạng thái nhé"                      # thông báo cho toàn bộ phiên

Bối cảnh

Việc phát triển với nhiều phiên AI CLI chạy trên nhiều máy đã trở nên phổ biến. Phần thực thi có thể mở rộng song song theo số lượng phiên, nhưng việc chuyển giao giữa các phiên — truyền chỉ thị, kiểm tra tiến độ, thu hồi kết quả — vẫn do con người tự chuyển qua lại giữa các terminal. Điểm xuất phát của công cụ này cũng chính là nút thắt đó: khi chạy đồng thời ba phiên AI CLI trên ba máy, giai đoạn “chuyển giao” chỉ thị và kết quả bị nghẽn ở con người trước cả phần thực thi.

Trước đây: chuyển focus qua lại giữa 3 terminal → copy-paste chỉ thị → lặp lại việc kiểm tra tiến độ cho từng phiên
telepty: từ một terminal, inject chỉ thị theo địa chỉ tên@host và lấy lại màn hình

Các công cụ hiện có không lấp được lớp này. tmux/SSH là công cụ để “gắn vào” phiên, nên việc gửi và xác nhận vẫn là thủ công; còn các framework agent lại yêu cầu viết lại các phiên và workflow hiện có theo cách của chúng. telepty nhắm đến lớp mỏng nằm giữa hai bên — giữ nguyên các phiên đang chạy, chỉ hạ tầng hóa phần chuyển giao.

Thiết kế

Chỉ định phiên bằng tên — gọi mọi phiên dưới dạng <tên-phiên>@<host>. Không cần quan tâm đích nằm trên máy nào hay hệ điều hành nào.
Phân biệt “đã gửi” và “đã nhận” — nếu phiên nhận đang bận, thông điệp được giữ trong hàng đợi (mailbox), và thời điểm thực sự được tiếp nhận được xác nhận dựa trên trạng thái render của terminal. Không cần gửi xong rồi con người phải kiểm tra lại.
Khởi động lại daemon vẫn giữ phiên — tiến trình nắm phiên (bridge) và daemon định tuyến (daemon) được tách riêng, nên nâng cấp daemon không làm gián đoạn công việc đang chạy.
Ủy thác truyền tải cho lớp đã kiểm chứng — không tạo giao thức P2P riêng. Nếu có Tailscale, daemon tự động phát hiện IP tailnet và kết nối trực tiếp trên đó: 0 mở cổng, 0 quản lý chứng chỉ, 0 quy tắc firewall. Môi trường không có tailnet thì kết nối bằng SSH tunnel (telepty connect user@host) — theo cách nào thì mã hóa và danh tính cũng do các công cụ đã được kiểm chứng đảm nhiệm, còn telepty chỉ làm việc địa chỉ hóa phiên và chuyển giao phía trên.

Lệnh gồm sáu lệnh inject / read-screen / attach / send-key / broadcast / list; CLI cũng chính là API nên có thể kết hợp ngay trong shell script. Và công cụ này không chỉ dành cho con người — gói có kèm 9 skill cho Claude Code·Codex·Gemini CLI (cài bằng installer tích hợp), để chính agent dùng telepty làm công cụ: tra cứu phiên, gửi chỉ thị cho agent trên máy khác, đọc màn hình về. Phần relay trong demo bên dưới chính là cảnh đó — không phải con người, mà từng LLM trực tiếp chạy telepty inject.

Chỉ số tham chiếu ban đầu (đo trên build 0.6.11 — bản phát hành hiện tại 0.7.1 · bao gồm overhead round-trip mạng và khởi tạo PTY)

Với gated inject tới phiên busy, từ xếp hàng→xác nhận tiếp nhận: Linux khoảng 487ms · Windows khoảng 1,2s — chúng tôi đang tích lũy thêm phép đo; điều quan trọng hơn con số là tiêu chí tiếp nhận không phải HTTP accept, mà là ACK đã tới phía nhận.
Đã xác nhận chuyển giao cross-machine trên 3 OS macOS·Linux·Windows theo cùng một tiêu chí.

Bảo mật

Daemon chỉ bind vào localhost(127.0.0.1) và IP dành riêng cho tailnet — không phơi 0.0.0.0, nên bên ngoài tailnet dù port scan cũng không thể tiếp cận. Chỉ tin cậy các peer trong tailnet, và quyền ghi vào PTY không vượt quá phạm vi người dùng sở hữu phiên. Từ 0.7.1, các request đến từ trình duyệt bị từ chối rõ ràng — đã chặn đường để trang web người dùng truy cập tiếp cận phiên qua control API hoặc WebSocket trên localhost (không có origin mặc định được cho phép).

Hạn chế

Đây là bản beta. Vẫn còn các edge case về rendering theo từng CLI, và Windows vẫn được gắn nhãn beta. Vì không giả lập terminal, read-screen trả về phần cuối của output stream chứ không phải lưới ô ký tự — với TUI repaint thường xuyên, bạn có thể thấy cùng một frame lặp lại. Các mục đã biết được tổng hợp trong phần Limitations của README.

Liên kết

GitHub: https://github.com/dmsdc-ai/aigentry-telepty
Demo README: cảnh 3 LLM(Grok·Codex·Claude) trên 3 máy(macOS·Linux·Windows) trực tiếp chạy telepty inject để relay cho nhau — mỗi màn hình là bản capture live của CLI TUI gốc bằng attach. Cùng lệnh đó cũng hoạt động nguyên như vậy giữa các phiên trên cùng một máy (có kèm demo relay cùng máy).
npm: @dmsdc-ai/aigentry-telepty (MIT, 0.7.1)

Tôi muốn nghe giải pháp lớp chuyển giao của những ai đang vận hành nhiều phiên AI CLI. Nếu bạn gửi phản hồi, tôi sẽ phản ánh vào dự án.