Light Remote MCP
Light Remote là nền tảng remote computing có kiểm soát cho ChatGPT, Claude, Codex và các AI Agent tương thích MCP. Thay vì chỉ đưa cho AI một shell hoặc một ảnh chụp màn hình, Light Remote kết hợp Real Remote V2 (RM V2), terminal PTY/ConPTY, filesystem, Git, process, file transfer, container/OS administration và Fleet dưới cùng một lớp phân quyền theo tài khoản → thiết bị → Agent → session → Local Policy.
- Website: light-remote.thaiduy.digital
- MCP endpoint chính thức: https://light-remote.thaiduy.digital/mcp
- ChatGPT plugin: Cài hoặc mở Light Remote trong ChatGPT
- Source: n8n2erpnext/light-remote-mcp
Trạng thái bản build: Windows
0.10.1-dev.4là ứng viên kiểm thử nội bộ, không phải bản phát hành nhị phân công khai. Tính năng có trong source, đã qua CI, đã deploy nội bộ và đã được Owner nghiệm thu trên máy vật lý là những trạng thái khác nhau. Xem Trạng thái dự án.
Vì sao Light Remote khác công cụ remote thông thường?
- AI làm việc được trên giao diện đồ họa thật: RM V2 quan sát cửa sổ, đọc phần tử giao diện, theo dõi thay đổi và thực hiện thao tác chuột/bàn phím có giới hạn.
- Không cần SSH inbound cho từng thiết bị: Agent duy trì kênh kết nối outbound đã xác thực.
- Chọn máy bằng Short ID: Mỗi thiết bị có mã sáu ký tự ổn định, ràng buộc với device identity; AI không tự chọn nhầm máy Main hoặc nhảy sang máy khác.
- A/B do Agent khởi tạo: AI tìm thiết bị được phép xem, yêu cầu kết nối đến đúng Short ID và nhận mã B để chủ máy duyệt. Luồng hiện hành không yêu cầu chủ máy tạo/gửi A code.
- Local Wall quyết định quyền cuối: Phê duyệt kết nối không đồng nghĩa cho phép mọi lệnh. Local policy, quyền server và giới hạn tài nguyên vẫn được áp dụng.
- Công việc bền và kiểm toán được: Sessions, job IDs, output offsets, managed processes, terminal và activity trail cho phép tiếp tục công việc mà không tùy tiện chạy lại.
- Nhiều hệ điều hành, nhiều thiết bị: Windows, Linux, macOS với công cụ và giới hạn tính năng tùy hệ điều hành; Fleet không có fallback âm thầm.
Kiến trúc hệ thống
ChatGPT · Claude · Codex · MCP Clients
|
OAuth / HTTPS
|
Light Remote Plugin
Streamable HTTP /mcp
|
Private Unix socket
|
Light Remote Operator
identity · grants · sessions
/ \
PostgreSQL 17 Redis 8
durable records coordination
|
Signed outbound device channel
|
Exact enrolled device
/ | \
Windows Agent Linux Agent macOS Agent
\ | /
Local Wall
A/B · policy · activity
|
RM V2 · Files · PTY · Processes · SCP · Fleet
MCP server nhận công cụ qua POST /mcp và kết nối với Operator bằng Unix socket nội bộ; Operator giữ quyền điều phối, session và định danh thiết bị. Agent trên máy đích chỉ thực hiện trong quyền đã được cấp và trong chính sách Local Wall. Owner login (ví dụ scope desktop:read) không tự cấp Agent execution grant.
Đối chiếu source: MCP server, Operator client, Operator, Device Agent, Architecture, API Code Map.
Real Remote V2 (RM V2) — AI điều khiển máy tính thật
RM V2 không phải chỉ gửi screenshot rồi đoán tọa độ. Nó kết hợp quan sát hình ảnh, semantic UI và thao tác input hệ điều hành; Agent có thể ưu tiên phần tử giao diện có tên/ngữ nghĩa, chỉ dùng tọa độ khi cần.
1. Nhìn và quan sát trạng thái desktop
- Gắn vào desktop session, liệt kê các cửa sổ đang hiển thị, lấy frame giới hạn kích thước/chất lượng, đọc observation theo yêu cầu.
- Tạm rời hoặc kết nối lại observation session mà không đồng nghĩa khởi động lại Core Agent.
- Lấy một frame để đồng bộ ban đầu hoặc khi UI thay đổi quá lớn; không nhất thiết chụp toàn màn hình sau mỗi lệnh.
2. Hiểu giao diện qua Semantic UI
- Windows UI Automation (UIA): đọc cây phần tử UI có cấu trúc, tên, trạng thái, vị trí và sự kiện thay đổi theo khả năng provider.
- Browser CDP: kết nối đến một endpoint CDP loopback được cho phép rõ ràng để đọc metadata, accessibility tree và các thay đổi DOM/navigation. Provider CDP trong thiết kế này chỉ đọc; không tùy ý chạy JavaScript/evaluate hoặc tự khởi động browser.
- Các thao tác có cấu trúc:
invoke,click,focus,value,toggle,select,expand,collapse; dùng node ID từ quan sát phù hợp thay vì click mù.
3. Live observation — theo dõi thay đổi thay vì liên tục quét lại
- Mở một live semantic lane, đọc event delta/snapshot theo sequence từ bộ đệm của Hub; snapshot lại khi cần resync.
- Có thể chờ một điều kiện UI được chỉ định sau thao tác (ví dụ cửa sổ đích xuất hiện, tiêu đề hoặc phần tử đang focus khớp).
- Đóng lane khi xong để giải phóng hoạt động quan sát. Companion/robot trên Windows được thiết kế khởi động theo yêu cầu, không chạy vòng quét RM liên tục khi chưa sử dụng.
4. Thao tác chuột/bàn phím thật
- Di chuyển trỏ chuột, click trái/phải/giữa, click nhiều lần có giới hạn, cuộn và kéo-thả.
- Gõ Unicode, nhập văn bản vào ứng dụng đang focus, nhấn phím và các modifier được hỗ trợ.
- Các lệnh input được ràng buộc session, policy và điều kiện màn hình/foreground; Windows UIPI, UAC và secure desktop không bị bỏ qua.
- Không cần tạo script automation riêng cho mỗi chương trình: AI có thể quan sát, chọn phần tử và tương tác theo đúng quyền chủ máy đã cho.
Ví dụ: một AI Agent có thể mở phần mềm Windows, tìm cửa sổ cấu hình, chọn mục bằng semantic UI, nhập dữ liệu, quan sát thông báo kết quả, rồi ghi hoạt động vào session. Với phần mềm không có API hoặc CLI, RM V2 cung cấp đường thao tác trực tiếp trên GUI.
Giới hạn theo nền tảng: Windows có companion UIA/native input và các bài kiểm thử riêng; mã macOS có nhánh Real Remote native và kiểm thử nguồn; không suy diễn đầy đủ tính năng desktop trên mọi Linux/macOS chỉ vì tool xuất hiện trong MCP. Xem RM V2 source/design, Native Windows Robot và Feature Status.
Agent có thể làm những gì khác?
| Nhóm | Công cụ / tác vụ |
|---|---|
| Filesystem | List, stat, đọc/ghi/edit/copy/move/xóa trong allowlisted roots |
| Search | Tìm tên và nội dung file, giới hạn kết quả, phân trang |
| Developer & Git | Kiểm tra Git, sửa source, chạy build/test theo quyền |
| Exec | Chạy một lệnh bash/zsh/PowerShell/CMD có timeout và capability inference |
| Managed processes | Bắt đầu/dừng tiến trình, stdin/stdout theo offset |
| Terminal | PTY Linux/macOS, ConPTY Windows, nhập lệnh, resize, Ctrl-C/signal |
| SCP | Upload/download nhị phân, chunk và SHA-256 để kiểm tính toàn vẹn |
| Durable jobs | Theo dõi trạng thái và đọc kết quả tiếp qua nhiều MCP call |
| Infrastructure | Docker, LXD, Podman, Incus, Kubernetes, virtual machines, services, package tools… tùy quyền và khả năng máy |
| Main / Fleet | Quan sát và điều phối exact device, quyền riêng từng máy, session/lease |
| Optional modules | Long Memory, Codex Bridge, activity history theo cấu hình được bật |
Tool Helper hướng dẫn chọn structured files/search trước shell, process/job cho tác vụ dài và RM V2 khi phải tương tác với desktop.
Local Wall & Permissions — chủ máy quyết định
Trang Local Wall → Permissions hiện dùng các nhóm quyền có thể mở rộng, bật/tắt từng capability hoặc cả nhóm, không phải chỉ một công tắc Full Access. Giao diện lấy catalog khả năng của hệ điều hành và tool được cài thật trên máy.
8 nhóm quyền trên giao diện mới
| Nhóm | Ví dụ quyền điều khiển |
|---|---|
| Files & Development | Filesystem, Git, build/test, Windows shells |
| PTY / Interactive Terminal | Quyền shell PTY/ConPTY tương tác riêng |
| Desktop & Real Remote | desktop (xem) và desktop-input (chuột/bàn phím) độc lập |
| Containers & Virtualization | Docker, LXD, Podman, Incus, Kubernetes, VM |
| System & Packages | System services, package manager, sudo, Windows Services/UAC, scheduled tasks, launchd |
| Network & Firewall | Network administration, firewall, Defender, process/network diagnostics |
| Storage & Provisioning | Quản lý đĩa/volume/mount, Terraform/OpenTofu/Ansible |
| OS Security & Logs | Windows Registry/Credential Manager/Event Log, macOS unified logs |
Số quyền thay đổi theo máy. Ví dụ giao diện Windows có thể báo 23/23 locally allowed · 23 effective; đó là quyền hiện có của máy ấy, không phải Light Remote chỉ hỗ trợ cố định 23 capability trên tất cả hệ điều hành. Các capability mới chưa có trong nhóm định sẵn xuất hiện ở nhóm bổ sung.
Profile và quyền thực sự có hiệu lực
Profile gồm Safe, Developer, Remote Support, Infra / Ops, Full access và Custom. Bạn có thể chọn profile, chỉnh checkbox từng quyền hoặc dùng Allow all supported / Block all / Save local policy.
- Main device: Local Wall là bề mặt quản lý quyền của máy chính trong phạm vi capability được hỗ trợ.
- Fleet leaf: Quyền có hiệu lực là phần được server/account Owner phê duyệt và được Local Wall cho phép; bật checkbox chưa chắc đã là
effective. Quyền mới có thể cần Owner duyệt qua Account. - Tool detected ≠ permission granted: Có cài Docker/kubectl không đồng nghĩa AI được phép quản trị; ngược lại cấp quyền cho tool chưa cài cũng không làm tool xuất hiện.
- Terminal, desktop view và desktop input là ba ranh giới riêng; không suy ra quyền điều khiển màn hình từ quyền xem.
- Sudo/UAC vẫn đòi cơ chế nâng quyền thật của OS; không có quyền nào tự vượt Windows UAC hoặc policy hệ thống.
Quyền filesystem theo ổ đĩa/thư mục
Ngay cả Full access cũng không tự cho phép đọc/ghi mọi ổ đĩa. Local Wall có phần Filesystem access locations, cho phép chọn ổ đã phát hiện và khai báo thêm Additional read locations / Additional write locations.
Đường dẫn Write phải nằm trong Read. Ví dụ có thể cấp đọc/ghi cho C:\Users\Admin nhưng để ổ USB E:\ chưa được cấp; các structured Files, Search và SCP phải tôn trọng phạm vi này. Thay đổi root được áp cho các thao tác mới mà không buộc ghép nối Agent lại.
Nút Refresh capabilities and inventory quét lại tool/OS ở các thiết bị hỗ trợ quét; với trusted Main, catalog được quản lý qua Operator và nút quét có thể bị vô hiệu. Các thay đổi quyền có thể được ghi nhận cùng policy revision.
Xem policy source và security model.
Kết nối thiết bị — Short ID và phê duyệt A/B
Short ID là định danh ngắn, ổn định gồm 6 ký tự được lưu/ràng buộc với đúng thiết bị. Mã đã cấp không được tự tái sử dụng cho một thiết bị khác.
- Chủ máy cài/link Agent vào tài khoản Light Remote và kết nối thiết bị.
- AI client đăng nhập OAuth, dùng
light_remote_discover_devicesđể xem danh sách/trạng thái thiết bị thuộc tài khoản. Đây chỉ là Discovery read-only, chưa có quyền điều khiển. - Chọn chính xác Short ID của máy online (ví dụ
R01KAP). AI gọilight_remote_connection_helpervới Short ID đã chọn vàstartAbV2=true(tên tham số nội bộ của MCP; giao diện người dùng gọi tính năng này là A/B). - Server phát sinh B code cho yêu cầu đó. Chủ thiết bị mở Approve B tại Local Wall
/approvehoặc trang Account hỗ trợ phê duyệt, kiểm tra đúng thiết bị/Agent rồi chọn Approve. - AI gọi lại Connection Helper để phục hồi yêu cầu và nhận context
ready. Chỉ lúc này mới được dùng session/permissions được cấp.
Luồng Short ID hiện tại không yêu cầu tạo hay gửi A code. Không trộn việc đăng nhập tài khoản, tra cứu máy, phê duyệt B và thực thi lệnh thành một quyền. Không được tự ý chuyển đích nếu máy được chọn offline hoặc deny.
Nếu một AI client chưa thấy light_remote_discover_devices, cần làm mới metadata công cụ/plugin; Helper có đường tra cứu tương thích, nhưng không được coi danh sách granted devices là toàn bộ thiết bị online.
Cách kết nối với ChatGPT, Claude và các AI client
ChatGPT — official plugin
- Mở Light Remote trên ChatGPT, chọn kết nối/cấp quyền theo giao diện ChatGPT.
- Đăng nhập tài khoản Light Remote bằng luồng OAuth chính thức.
- Yêu cầu AI liệt kê thiết bị online, chọn Short ID, rồi gửi yêu cầu kết nối A/B.
- Xác nhận B trên Wall/Account của thiết bị đúng đích và tiếp tục khi Helper báo
ready.
Claude / Claude Desktop — custom Remote MCP
Theo hướng dẫn chính thức của Claude:
- Mở Customize → Connectors → Add → Custom → Web (hoặc Add custom connector, tùy giao diện/tài khoản).
- Đặt tên
Light Remotevà nhập URLhttps://light-remote.thaiduy.digital/mcp. - Tiếp tục bước xác thực, chọn Sign in / OAuth khi Claude nhận diện và đăng nhập tài khoản Light Remote.
- Bật connector cho cuộc trò chuyện, dùng Discovery → Short ID → Approve B → ready như trên.
Claude remote connector kết nối từ máy chủ Anthropic, vì vậy endpoint MCP phải truy cập được qua HTTPS từ hạ tầng của họ. Không dùng URL 127.0.0.1:5491 của Local Wall làm MCP endpoint. Tổ chức Team/Enterprise có thể cần quản trị viên thêm connector trước.
Claude Code — CLI
Theo Claude Code MCP docs, thêm remote HTTP MCP:
claude mcp add --transport http light-remote https://light-remote.thaiduy.digital/mcp
Mở Claude Code, chạy /mcp để kiểm tra và hoàn tất OAuth khi được yêu cầu. Sau đó chọn đúng Short ID và duyệt B trên Light Remote Wall/Account.
Các MCP client khác
Chọn giao thức Streamable HTTP, URL https://light-remote.thaiduy.digital/mcp, hoàn tất OAuth (nếu client hỗ trợ). Ví dụ cấu hình MCP theo dạng thông dụng:
{
"mcpServers": {
"light-remote": {
"type": "streamable-http",
"url": "https://light-remote.thaiduy.digital/mcp"
}
}
}
Định dạng file và tính năng OAuth/remote MCP tùy phần mềm; không phải AI client nào cũng hỗ trợ toàn bộ. Tránh nhúng bearer token hoặc mật khẩu trong file công khai.
Cập nhật và phục hồi
Windows hiện dùng một chương trình chính LightRemote.exe: Tauri/Rust phụ trách GUI/tray và thực thi worker role, gọi private WindowsHost/.NET component theo đường cố định. Node, RM V2, private .NET libraries, updater/watchdog và thành phần rollback vẫn độc lập. Signed manifests, hash/size và health-gated rollback là thiết kế của kênh cập nhật; bản dev.4 chưa có public feed được phát hành.
Các bản helper quá cũ cần đi theo pinned compatibility bridge trước khi nâng cấp dạng one-primary EXE. Không tự chỉnh manifest đã ký hoặc dùng artifact chưa xác minh.
Bảo mật và giới hạn hiện tại
- OAuth Owner ≠ quyền điều khiển thiết bị; A/B và policy ở thiết bị là bắt buộc.
- Phiên phải trỏ đúng Short ID/device ID; lệnh không fallback sang thiết bị khác.
- RM V2 cần quyền quan sát và input riêng; UIPI, secure desktop, OS permission vẫn là giới hạn thật.
- Quyền file có danh sách ổ/thư mục đọc/ghi riêng, không suy ra từ profile Full Access.
- Long Memory/Codex Bridge, browser Wall SSO, Guest/Pro Share và một số module có trạng thái triển khai khác nhau; xem Known Issues.
- Chủ máy có thể thu hồi quyền/đóng phiên; khóa riêng và token session không được đưa vào tài liệu công khai.
Developer & nguồn kiểm chứng
- Mã nguồn: repository chính thức, SSH:
git@github.com:n8n2erpnext/light-remote-mcp.git. - Nhánh:
worklà nhánh phát triển được Owner cho phép;mainđược bảo vệ bằngbaseline-required. Không tạo nhánh hoặc force-push ngoài phê duyệt. - Workspace: mọi thư mục phát triển mới trên VPS-ARM thuộc
/home/ubuntu/n8n2erpnext/light-remote-unified-20261108/; checkout đang sử dụng làimplementation-20261108/single-primary-exe. - Checkpoint: mỗi commit gồm
MASTER_CHECKPOINT.json,PROJECT_HANDOFF.md, Worklog và generated docs status trong cùng commit.
Đọc Project Truth, Master Checkpoint, Project Book, Code Map, Feature Status, Build and Deployment.
npm ci --ignore-scripts
npm run check:truth
npm run check:docs
npm test
Trạng thái dự án
| Thành phần | Phạm vi đã kiểm chứng |
|---|---|
| Windows Desktop | 0.10.1-dev.4, một LightRemote.exe chính, build/installer/migration/rollback chạy qua Windows CI |
| GitHub CI | CI #45 — 9/9 PASS: React 121, consent/token 36, browser 170, backend integration 25 |
| Internal Operator/Plugin Lab | Đã kiểm thử và triển khai bản source 947a117 trong Lab nội bộ |
| Short ID / A/B | Luồng hiện hành theo Short ID + B; quyền điều khiển chỉ sau Owner approval |
| RM V2 / Fleet / PTY | Tool/source và kiểm thử theo phạm vi; trạng thái tính năng vật lý tùy nền tảng/phiên bản |
| Windows dev.4 Owner physical UAT | Chưa kết luận PASS |
| macOS/Linux full current installers | Chưa chứng minh build/phát hành đầy đủ, native source CI có kiểm thử |
| Public Release / signed update feed dev.4 | Chưa phát hành / HOLD |
Không coi CI hoặc source implementation là bằng chứng toàn bộ tính năng đã được nghiệm thu vật lý. Evidence dev.4 · Known Issues.
License
Apache-2.0 — LICENSE, NOTICE, THIRD_PARTY_DISTRIBUTION_NOTICES.md.