Giới thiệu

Mục đích: Giúp người dùng cuối và AI agent hiểu cách giao tiếp với hệ thống CarSky qua REST API và MCP server. Không yêu cầu biết lập trình sâu.

Cập nhật: 2026-07-16
Trạng thái: Tài liệu tham khảo — cập nhật khi API hoặc MCP server có thay đổi.

1. Tổng quan

CarSky cung cấp hai cách chính để tự động hóa và điều khiển từ xa:

Cách tiếp cận	Mô tả	Khi nào dùng
REST API	Giao thức HTTP/JSON truyền thống. Bạn gọi đến các địa chỉ endpoint để lấy dữ liệu, điều khiển VM, gửi tín hiệu, v.v.	Dùng cho script tự động, ứng dụng bên thứ ba, hoặc agent chạy trên cloud.
MCP Server	Một server theo chuẩn Model Context Protocol (MCP) mà các AI agent có thể kết nối. Nó đóng gói các thao tác thường dùng thành các tool có tên, mô tả và tham số rõ ràng.	Dùng cho AI assistant/agent muốn điều khiển CarSky một cách tự nhiên.

Quan hệ giữa API và MCP: Hầu hết các MCP tool đều gọi ngầm đến REST API của CarSky. MCP chỉ là "lớp bao bọc" giúp AI agent dễ dùng hơn.

2. Xác thực (Authentication)

Cả API và MCP đều cần một khóa API hoặc token để xác thực.

2.1 Lấy khóa API

Đăng nhập vào giao diện CarSky (Rework UI).
Bấm vào ảnh đại diện góc trên → chọn tab Credentials (cần quyền Admin/Editor tùy cấu hình).
Bấm Create credential → sao chép chuỗi khóa API được hiển thị một lần duy nhất.
Lưu khóa vào nơi an toàn. Nếu mất, bạn phải tạo khóa mới.

Lưu ý: Khóa API thường có dạng a8k_... (machine-to-machine key). Đây là khóa dành cho máy/agent, không phải mật khẩu đăng nhập của bạn.

2.2 Dùng khóa API với REST API

Thêm vào header của mọi request:

Code

X-API-Key: <khóa_api_của_bạn>

Hoặc dùng dạng Bearer:

Code

Authorization: Bearer <khóa_api_của_bạn>

Ví dụ bằng curl:

curl

curl -H "X-API-Key: <khóa_api_của_bạn>" \
     https://carsky.example.com/api/v1/healthz

2.3 Dùng khóa API với MCP Server

Nếu dùng stdio transport (mặc định): đặt khóa vào biến môi trường A8_API_KEY khi khởi động MCP server.
Nếu dùng HTTP transport: gửi khóa qua header X-API-Key hoặc Authorization: Bearer trong mỗi request đến MCP server.

3. Luồng làm việc cơ bản: từ blueprint đến kiểm thử (quan trọng nhất)

Đây là quy trình chuẩn để biến một bản thiết kế thành một môi trường kiểm thử thực tế trên CarSky. Bạn có thể thực hiện bằng giao diện Rework UI hoặc qua API/MCP.

3.1 Sơ đồ tổng thể

Code

Bước 1: Vào Nydus ──► Bước 2: Tạo/Import Blueprint
                                │
                                ▼
Bước 5: Kiểm thử/Điều khiển ◄── Bước 4: Tạo/Chọn Device
                                ▲
                                │
                        Bước 3: Deploy Blueprint

3.2 Bước 1: Vào Nydus

Trên Rework UI:

Đăng nhập vào CarSky.
Trên thanh Dock chính, bấm Nydus.
Giao diện Nydus mở ra với các tab chính:
Blueprints: danh sách bản thiết kế.
Deployments: các lần triển khai đang chạy.
Registry/Artifacts: kho image, DBC, script...

3.3 Bước 2: Tạo hoặc import blueprint

Cách A — Tạo blueprint mới trên UI:

Trong tab Blueprints, bấm New blueprint.
Đặt tên và mô tả cho blueprint.
Mở graph editor, kéo thả các node từ palette vào sân khấu:
Skycraft — thiết bị ảo Android Automotive.
CAN bus / LIN bus — mạng xe.
GPIO panel — bảng nút/công tắc ảo.
Script node — chạy script tự động hóa.
Container — chạy service/container ECU.
Kết nối các chân (pin) giữa các node bằng cách kéo dây (edge).
Cấu hình từng node: chọn image, DBC, script, v.v.
Bấm Save.

Cách B — Import blueprint có sẵn:

Trong tab Blueprints, bấm Import.
Chọn file JSON blueprint từ máy tính (thường nằm trong examples/<tên-demo>/blueprint.json).
Hệ thống kiểm tra định dạng. Nếu hợp lệ, blueprint xuất hiện trong danh sách.

Cách C — Qua API/MCP:

API: POST /api/v1/blueprints để tạo rỗng, sau đó dùng POST /api/v1/blueprints/{id}/batch để thêm node/pin/edge.
MCP: create_blueprint với nodes và edges.
Sau khi tạo, luôn gọi validate_blueprint (MCP) hoặc POST /api/v1/blueprints/{id}/validate (API) để kiểm tra topology.

Mẹo: Nếu chỉ muốn chạy demo có sẵn, hãy import thay vì tạo từ đầu. Điều này giảm thiểu lỗi cấu hình.

3.4 Bước 3: Deploy blueprint

Trong danh sách Blueprints, chọn blueprint muốn chạy.
Bấm nút Deploy (biểu tượng tên lửa hoặc chữ "Deploy").
Hệ thống hiển thị hộp thoại Deploy blueprint.

3.5 Bước 4: Tạo device và chọn làm mục tiêu deploy

Trong hộp thoại Deploy blueprint:

Chọn device đích từ danh sách nếu đã có.
Hoặc bấm Create new device để tạo thiết bị mới:
Đặt tên device (ví dụ: Demo-AAOS-01).
Chọn loại device phù hợp (thường là room hoặc loại do hệ thống định nghĩa).
Lưu ý: device ID này chính là roomId dùng trong API/MCP sau này.
Bấm Deploy để bắt đầu triển khai.

Hệ thống sẽ bắt đầu khởi tạo các pod/container/node trong Kubernetes. Quá trình này có thể mất vài chục giây đến vài phút tùy độ phức tạp của blueprint.

Qua API/MCP:

API: POST /api/v1/deployments với body { blueprintId, roomId, name }.
MCP: deploy(blueprintId, roomId, name).
Sau đó dùng wait_ready (MCP) hoặc poll GET /api/v1/deployments/{roomId}/status (API) để chờ tất cả node chuyển sang Running.

3.6 Bước 5: Kết nối và kiểm thử device

Sau khi deploy thành công, bạn có thể kiểm tra và điều khiển device bằng nhiều cách.

3.6.1 Xem trạng thái deployment

UI: tab Deployments trong Nydus, hoặc panel Dashboard.
API: GET /api/v1/deployments/{roomId}/status.
MCP: deployment_status(roomId).

3.6.2 Xem màn hình VM (Skycraft)

UI: mở device, chọn node Skycraft, bấm Screen.
API: GET /api/v1/vms/{roomId}/{nodeKey}/screenshot.
MCP: screenshot(roomId, nodeKey).

3.6.3 Điều khiển màn hình

UI: click trực tiếp vào màn hình ảo trong panel Screen.
API/MCP:
Chạm: tap(roomId, nodeKey, x, y) / POST .../tap
Vuốt: swipe(...) / POST .../swipe
Nhập text: input_text(roomId, nodeKey, text) / POST .../text
Bấm phím: press_key(roomId, nodeKey, "KEYCODE_HOME") / POST .../key

3.6.4 Kiểm tra UI tree (tìm nút/icon)

API: GET /api/v1/vms/{roomId}/{nodeKey}/accessibility
MCP: ui_tree(roomId, nodeKey) hoặc find_text(roomId, nodeKey, "Settings")

3.6.5 Đọc/ghi tín hiệu CAN/LIN/GPIO

UI: mở panel Signal hoặc GPIO, chọn node nguồn tín hiệu.
API:
Đọc: POST /api/v1/signals/{roomId}/{nodeKey}/values
Ghi: POST /api/v1/signals/{roomId}/{nodeKey}/actuate
MCP:
Đọc: get_signal_values(roomId, nodeKey, ["Vehicle.Speed"])
Ghi: send_signals(roomId, nodeKey, [{path:"Vehicle.Speed", value:60}])

3.6.6 Xem log

UI: panel Logs trong Dashboard, chọn node.
API: GET /api/v1/deployments/{roomId}/logs/{nodeKey}
MCP: pod_logs(roomId, nodeKey) hoặc search_logs(...) để tìm log lịch sử.

3.6.7 Dùng ADB (nâng cao)

Một lệnh: adb_shell(roomId, nodeKey, "logcat -d")
Tunnel liên tục: vm_tunnel_open(roomId, nodeKey) → adb connect localhost:<port> → dùng adb local bình thường.

3.7 Khi nào cần redeploy?

Bạn cần redeploy khi:

Sửa topology blueprint (thêm/xóa node, thay đổi kết nối).
Thay đổi artifact/image được dùng trong node.
Cấu hình node thay đổi.

Bạn không cần redeploy khi:

Chỉ điều khiển màn hình, gửi tín hiệu, hoặc xem log.
Thay đổi widget/dashboard của device.

3.8 Dừng và dọn dẹp

Khi kiểm thử xong:

UI: trong tab Deployments, chuột phải vào deployment → Delete.
API: DELETE /api/v1/deployments/{roomId}.
MCP: undeploy(roomId).

Lưu ý: Xóa deployment sẽ dừng các pod/container đang chạy nhưng không xóa blueprint. Bạn có thể deploy lại blueprint này sau.

4. REST API — Cách sử dụng

4.1 Base URL

Tất cả API đều nằm dưới:

Code

https://<tên-miền-carsky>/api/v1

Ví dụ: https://carsky.example.com/api/v1/blueprints

4.2 Tài liệu OpenAPI tự động

CarSky tự sinh tài liệu API:

OpenAPI JSON: GET /api/v1/openapi.json
Swagger UI: GET /api/v1/docs

Bạn có thể mở /api/v1/docs trên trình duyệt để xem chi tiết từng endpoint, tham số và ví dụ response.

4.3 Định dạng phản hồi chung

Hầu hết response đều ở dạng JSON. Một số endpoint (như screenshot) trả về binary (ảnh PNG).

200 OK — thành công.
201 Created — tạo mới thành công.
400 Bad Request — tham số sai hoặc thiếu.
401 Unauthorized — chưa xác thực hoặc khóa API không hợp lệ.
403 Forbidden — đã xác thực nhưng không đủ quyền.
404 Not Found — tài nguyên không tồn tại.
500 Internal Server Error — lỗi phía server.

5. Danh sách REST API Endpoint

Dưới đây là các nhóm endpoint chính. Mỗi endpoint đều yêu cầu header xác thực như đã mô tả ở trên, trừ các endpoint công khai được đánh dấu riêng.

5.1 Meta — Kiểm tra hệ thống (Public)

Method	Path	Mô tả
`GET`	`/api/v1/healthz`	Kiểm tra sức khỏe API, database, Zero sync.
`GET`	`/api/v1/openapi.json`	Trả về OpenAPI 3.1 spec.
`GET`	`/api/v1/docs`	Giao diện Swagger UI.

5.2 Blueprints — Bản thiết kế hệ thống

Blueprints là bản thiết kế mô tả topology của một "phòng" ảo: các node (Skycraft, CAN bus, script, container...), các chân kết nối (pin) và các liên kết (edge) giữa chúng.

Method	Path	Mô tả
`GET`	`/api/v1/blueprints`	Liệt kê blueprints (phân trang, lọc theo tên).
`GET`	`/api/v1/blueprints/:id`	Lấy chi tiết một blueprint, bao gồm nodes, pins, edges.
`POST`	`/api/v1/blueprints`	Tạo blueprint mới.
`PATCH`	`/api/v1/blueprints/:id`	Cập nhật tên/mô tả blueprint.
`POST`	`/api/v1/blueprints/:id/lock`	Khóa/mở khóa blueprint (ngăn sửa đổi).
`DELETE`	`/api/v1/blueprints/:id`	Xóa blueprint.
`POST`	`/api/v1/blueprints/:id/clone`	Nhân bản blueprint.
`POST`	`/api/v1/blueprints/:id/validate`	Kiểm tra topology trước khi triển khai.
`POST`	`/api/v1/blueprints/:id/batch`	Thực hiện nhiều thao tác topology trong một lệnh (thêm node/pin/edge).
`GET`	`/api/v1/blueprints/:id/export`	Xuất blueprint ra JSON để backup hoặc chia sẻ.
`POST`	`/api/v1/blueprints/import`	Nhập blueprint từ file JSON đã xuất.
`POST`	`/api/v1/blueprints/:id/nodes`	Thêm node vào blueprint.
`PATCH`	`/api/v1/blueprints/nodes/:nodeId`	Sửa node.
`DELETE`	`/api/v1/blueprints/nodes/:nodeId`	Xóa node.
`POST`	`/api/v1/blueprints/nodes/:nodeId/pins`	Thêm pin vào node.
`PATCH`	`/api/v1/blueprints/pins/:pinId`	Sửa pin.
`DELETE`	`/api/v1/blueprints/pins/:pinId`	Xóa pin.
`POST`	`/api/v1/blueprints/:id/edges`	Thêm liên kết giữa hai pin.
`DELETE`	`/api/v1/blueprints/edges/:edgeId`	Xóa liên kết.

5.3 Devices — Thiết bị

Trong CarSky, "device" thường được dùng như một "room" để triển khai blueprint.

Method	Path	Mô tả
`GET`	`/api/v1/devices`	Liệt kê thiết bị (phân trang, lọc theo tag).
`GET`	`/api/v1/devices/:id`	Xem chi tiết thiết bị, tags, widgets.
`POST`	`/api/v1/devices`	Tạo thiết bị mới.
`PATCH`	`/api/v1/devices/:id`	Cập nhật tên thiết bị.
`POST`	`/api/v1/devices/:id/lock`	Khóa/mở khóa thiết bị.
`DELETE`	`/api/v1/devices/:id`	Xóa thiết bị.
`POST`	`/api/v1/devices/:id/tags`	Gán tag cho thiết bị.
`DELETE`	`/api/v1/devices/:id/tags/:tag`	Gỡ tag.
`POST`	`/api/v1/devices/:id/widgets`	Thêm dashboard widget.
`PATCH`	`/api/v1/devices/:id/widgets/:widgetId`	Sửa widget.
`DELETE`	`/api/v1/devices/:id/widgets/:widgetId`	Xóa widget.
`POST`	`/api/v1/devices/:id/widgets/:widgetId/reorder`	Sắp xếp lại widget.

5.4 Artifacts — Kho tài nguyên

Artifacts là các file/tài nguyên dùng trong blueprint: ảnh đĩa VM, file DBC, script, firmware...

Method	Path	Mô tả
`GET`	`/api/v1/artifacts`	Liệt kê artifacts (phân trang, lọc theo category).
`GET`	`/api/v1/artifacts/:id`	Xem chi tiết artifact và các phiên bản.
`POST`	`/api/v1/artifacts`	Tạo metadata artifact.
`PATCH`	`/api/v1/artifacts/:id`	Cập nhật metadata.
`DELETE`	`/api/v1/artifacts/:id`	Xóa artifact.
`POST`	`/api/v1/artifacts/:id/versions`	Thêm phiên bản mới.
`DELETE`	`/api/v1/artifacts/:id/versions/:versionId`	Xóa phiên bản.

5.5 Deployments — Triển khai blueprint

Method	Path	Mô tả
`POST`	`/api/v1/deployments`	Triển khai một blueprint lên một thiết bị (room).
`GET`	`/api/v1/deployments/find`	Tìm deployment đang chạy theo tên device hoặc blueprint.
`GET`	`/api/v1/deployments/:roomId/status`	Xem trạng thái deployment.
`GET`	`/api/v1/deployments/:roomId/nodes`	Liệt kê các node trong deployment.
`GET`	`/api/v1/deployments/:roomId/nodes/watch`	Theo dõi trạng thái node theo thời gian thực (SSE).
`POST`	`/api/v1/deployments/:roomId/restart`	Khởi động lại tất cả node.
`POST`	`/api/v1/deployments/:roomId/restart/:node`	Khởi động lại một node cụ thể.
`DELETE`	`/api/v1/deployments/:roomId`	Dừng và xóa deployment.
`GET`	`/api/v1/deployments/:roomId/adb-tunnel`	Lấy thông tin lệnh mở ADB tunnel cho Skycraft node.
`POST`	`/api/v1/deployments/:roomId/adb-exec/:nodeKey`	Chạy lệnh ADB một lần.
`POST`	`/api/v1/deployments/:roomId/container-exec/:nodeKey`	Chạy lệnh bên trong container node.
`POST`	`/api/v1/deployments/:roomId/container-file/:nodeKey`	Đọc/ghi file trong container.
`GET`	`/api/v1/deployments/:roomId/pods`	Liệt kê Kubernetes pods.
`GET`	`/api/v1/deployments/:roomId/logs/:nodeKey`	Đọc log pod.
`GET`	`/api/v1/deployments/:roomId/logs/:nodeKey/search`	Tìm log lịch sử qua Loki.

5.6 VM Interaction — Điều khiển thiết bị ảo Android

Các endpoint này cho phép điều khiển màn hình Android ảo như thể bạn đang cầm thiết bị thật.

ADB routes (luôn có)

Method	Path	Mô tả
`GET`	`/api/v1/vms/:roomId/:nodeKey/screenshot`	Chụp màn hình PNG.
`POST`	`/api/v1/vms/:roomId/:nodeKey/text`	Nhập văn bản vào ô đang focus.
`POST`	`/api/v1/vms/:roomId/:nodeKey/key`	Bấm phím Android (keycode).
`POST`	`/api/v1/vms/:roomId/:nodeKey/shell`	Chạy lệnh ADB shell tùy ý.
`GET`	`/api/v1/vms/:roomId/:nodeKey/accessibility`	Lấy cây accessibility (UI tree) dạng JSON.

Touch routes (chỉ khi hệ thống có `COOLGATE_URL_SERVER`)

Method	Path	Mô tả
`POST`	`/api/v1/vms/:roomId/:nodeKey/tap`	Chạm vào tọa độ màn hình.
`POST`	`/api/v1/vms/:roomId/:nodeKey/swipe`	Vuốt màn hình.

Lưu ý: roomId là ID của device đã triển khai, nodeKey là tên node trong blueprint (ví dụ: vm-1, screen-1).

5.7 Signals — Tín hiệu CAN/LIN/GPIO/KUKSA

Gửi và nhận tín hiệu giữa các node trong deployment. CarSky sử dụng Zenoh peer-to-peer làm backbone.

Method	Path	Mô tả
`GET`	`/api/v1/signals/:roomId`	Tìm các node nguồn tín hiệu trong room.
`GET`	`/api/v1/signals/:roomId/:nodeKey`	Liệt kê các tín hiệu trên một node.
`POST`	`/api/v1/signals/:roomId/:nodeKey/values`	Đọc giá trị hiện tại của một hoặc nhiều tín hiệu.
`POST`	`/api/v1/signals/:roomId/:nodeKey/actuate`	Gửi giá trị tín hiệu (actuate).
`GET`	`/api/v1/signals/:roomId/:nodeKey/subscribe`	Đăng ký theo dõi thay đổi giá trị (SSE).
`POST`	`/api/v1/signals/:roomId/:nodeKey/periodic/start`	Bắt đầu gửi tuần hoàn một tín hiệu (CAN).
`POST`	`/api/v1/signals/:roomId/:nodeKey/periodic/stop`	Dừng gửi tuần hoàn.
`GET`	`/api/v1/signals/:roomId/:nodeKey/periodic`	Liệt kê các tín hiệu đang gửi tuần hoàn.
`GET`	`/api/v1/signals/:roomId/:nodeKey/periodic/subscribe`	Theo dõi trạng thái gửi tuần hoàn (SSE).

5.8 Credentials — Quản lý khóa API (M2M)

Method	Path	Mô tả
`GET`	`/api/v1/credentials`	Liệt kê các khóa M2M của tài khoản bạn.
`POST`	`/api/v1/credentials`	Tạo khóa M2M mới. Trả về khóa `a8k_...` một lần duy nhất.
`DELETE`	`/api/v1/credentials/:clientId`	Thu hồi khóa.

5.9 Auth — Kiểm tra token

Method	Path	Mô tả
`POST`	`/api/v1/auth/introspect`	Kiểm tra thông tin của một khóa `a8k_...` (chỉ admin/bootstrap key).

5.10 Config — Cấu hình hệ thống (Public)

Method	Path	Mô tả
`GET`	`/api/v1/config/limits`	Xem giới hạn tài nguyên đang áp dụng.
`GET`	`/api/v1/config/cpu-status`	Xem trạng thái CPU monitor.

5.11 Users & Account Limits

Method	Path	Mô tả
`GET`	`/api/v1/users`	Liệt kê các account identifier (public).
`GET`	`/api/v1/account-limits`	Liệt kê giới hạn tài khoản.
`GET/PUT/POST/DELETE`	`/api/v1/account-limits/:account`	CRUD giới hạn cho một tài khoản (admin).

6. MCP Server — Cách sử dụng

6.1 MCP là gì?

Model Context Protocol (MCP) là chuẩn do Anthropic khởi xướng, cho phép AI assistant kết nối với các dịch vụ bên ngoài qua các tool. Mỗi tool có:

Tên (ví dụ: screenshot, tap, deploy).
Mô tả ngắn gọn để AI hiểu chức năng.
Schema tham số đầu vào.
Hành động thực thi phía server.

Khi bạn yêu cầu AI "chụp màn hình VM và bấm vào nút Settings", AI sẽ tự động gọi các tool phù hợp thay vì bạn phải viết code.

6.2 Kết nối MCP Client

CarSky MCP server hỗ trợ hai transport:

Transport	Mô tả	Cách dùng
stdio	Server chạy như một process con, giao tiếp qua stdin/stdout.	Dùng cho Claude Desktop, Cursor, hoặc các MCP client chạy local. Cấu hình command đến `node mcp/dist/index.js`.
HTTP (Streamable)	Server lắng nghe HTTP.	Đặt `MCP_TRANSPORT=http`, server chạy trên cổng `3100`. Gửi request đến `http://localhost:3100/mcp`.

Ví dụ cấu hình stdio cho Claude Desktop (claude_desktop_config.json):

JSON

{
  "mcpServers": {
    "carsky": {
      "command": "node",
      "args": ["E:/A8/a8-reborn/mcp/dist/index.js"],
      "env": {
        "A8_URL": "https://carsky.example.com",
        "A8_API_KEY": "<khóa_api_của_bạn>"
      }
    }
  }
}

Lưu ý: MCP server sử dụng A8_URL để biết địa chỉ CarSky API backend. Thay https://carsky.example.com bằng URL thật của bạn.

7. Danh sách MCP Tool

CarSky MCP server hiện cung cấp 42 tool chia thành 10 nhóm.

7.1 Health — Kiểm tra kết nối

Tool	Tham số	Mô tả
`health_check`	không có	Kiểm tra API có hoạt động không (Prisma, Zero).

7.2 Blueprints — Quản lý bản thiết kế

Tool	Tham số chính	Mô tả
`list_blueprints`	`name?`, `limit?`, `cursor?`	Liệt kê blueprint.
`get_blueprint`	`id`	Lấy chi tiết blueprint.
`create_blueprint`	`name`, `description?`, `nodes?`, `edges?`	Tạo blueprint, có thể kèm topology.
`update_blueprint`	`id`, `name?`, `description?`, `operations?`	Cập nhật blueprint hoặc topology batch.
`clone_blueprint`	`id`, `name`, `isSnapshot?`	Nhân bản blueprint.
`validate_blueprint`	`id`	Kiểm tra topology trước khi deploy.
`export_blueprint`	`id`	Xuất blueprint ra JSON.
`import_blueprint`	`data`, `name?`	Nhập blueprint từ JSON.

7.3 Devices — Thiết bị

Tool	Tham số chính	Mô tả
`list_devices`	`tag?`, `limit?`, `cursor?`	Liệt kê thiết bị. ID thiết bị thường được dùng làm `roomId`.

7.4 Artifacts — Tài nguyên

Tool	Tham số chính	Mô tả
`list_artifacts`	`category?`, `limit?`, `cursor?`	Liệt kê artifact theo loại (DBC, VM_IMAGE, SCRIPT, v.v.).

7.5 Deployments — Triển khai

Tool	Tham số chính	Mô tả
`find_deployment`	`device?`, `blueprint?`	Tìm deployment đang chạy để lấy `roomId`.
`deploy`	`blueprintId`, `roomId`, `name`	Triển khai blueprint lên thiết bị.
`deployment_status`	`roomId`	Xem trạng thái deployment.
`wait_ready`	`roomId`, `timeoutMs?`, `pollIntervalMs?`	Chờ đến khi tất cả node chạy xong.
`undeploy`	`roomId`	Dừng deployment.

7.6 VM Interaction — Điều khiển thiết bị ảo

Tool	Tham số chính	Mô tả
`screenshot`	`roomId`, `nodeKey`	Chụp màn hình VM, trả về ảnh base64 PNG.
`tap`	`roomId`, `nodeKey`, `x`, `y`, `screenWidth?`, `screenHeight?`	Chạm vào tọa độ màn hình.
`swipe`	`roomId`, `nodeKey`, `x1`, `y1`, `x2`, `y2`, `durationMs?`	Vuốt màn hình.
`input_text`	`roomId`, `nodeKey`, `text`	Nhập văn bản.
`press_key`	`roomId`, `nodeKey`, `keycode`	Bấm phím Android (ví dụ: `KEYCODE_HOME`).
`adb_shell`	`roomId`, `nodeKey`, `command`	Chạy lệnh ADB shell.
`ui_tree`	`roomId`, `nodeKey`	Lấy cây accessibility dạng JSON.
`wait_boot`	`roomId`, `nodeKey`, `timeoutMs?`	Chờ Android boot xong (`sys.boot_completed=1`).
`find_text`	`roomId`, `nodeKey`, `text`, `exact?`	Tìm text trong UI tree.

7.7 Signals — Tín hiệu

Tool	Tham số chính	Mô tả
`list_signal_nodes`	`roomId`	Tìm các node nguồn tín hiệu.
`list_signals`	`roomId`, `nodeKey`, `pattern?`	Liệt kê tín hiệu.
`get_signal_values`	`roomId`, `nodeKey`, `paths`	Đọc giá trị một hoặc nhiều tín hiệu.
`send_signals`	`roomId`, `nodeKey`, `signals`	Gửi giá trị tín hiệu.
`start_periodic_send`	`roomId`, `nodeKey`, `path`, `value`, `intervalMs?`	Gửi tuần hoàn.
`stop_periodic_send`	`roomId`, `nodeKey`, `path`	Dừng gửi tuần hoàn.
`list_periodic_sends`	`roomId`, `nodeKey`	Liệt kê các tín hiệu đang gửi tuần hoàn.
`subscribe_signals`	`roomId`, `nodeKey`, `paths`, `maxEvents?`, `timeoutMs?`	Thu thập các sự kiện thay đổi giá trị trong một khoảng thời gian.

7.8 Tunnels — ADB Tunnel cục bộ

Tool	Tham số chính	Mô tả
`vm_tunnel_open`	`roomId`, `nodeKey`, `localPort?`	Mở tunnel ADB local (`localhost:port`).
`vm_tunnel_close`	`roomId`, `nodeKey`	Đóng tunnel.
`vm_tunnel_list`	không có	Liệt kê các tunnel đang mở.

Khi nào dùng tunnel? Khi bạn muốn dùng adb local, Appium, hoặc UIAutomator để kết nối trực tiếp đến VM ảo như thể nó đang cắm USB vào máy tính của bạn.

7.9 Containers — Thao tác container Linux

Tool	Tham số chính	Mô tả
`container_shell`	`roomId`, `nodeKey`, `command`, `timeout_secs?`	Chạy lệnh shell trong container.
`container_file_read`	`roomId`, `nodeKey`, `path`	Đọc file từ container.
`container_file_write`	`roomId`, `nodeKey`, `path`, `content`	Ghi file vào container.

7.10 Logs — Log pod và Loki

Tool	Tham số chính	Mô tả
`list_pods`	`roomId`	Liệt kê pods/containers.
`pod_logs`	`roomId`, `nodeKey`, `tail?`, `since?`, `container?`	Đọc log container trực tiếp.
`search_logs`	`roomId`, `nodeKey`, `query?`, `since?`, `limit?`	Tìm log lịch sử qua Loki.

8. Ví dụ luồng làm việc thường gặp

8.1 Luồng 1: AI agent tự động mở app trên Android VM

Code

AI agent gọi MCP tool: list_devices → chọn device (roomId).
AI agent gọi: find_deployment(device="...") hoặc deployment_status(roomId).
Nếu chưa có deployment, gọi: deploy(blueprintId, roomId, name).
Chờ VM sẵn sàng: wait_boot(roomId, nodeKey="vm-1").
Chụp màn hình: screenshot(roomId, nodeKey="vm-1").
AI phân tích ảnh hoặc ui_tree để tìm icon app.
Bấm vào icon: tap(roomId, nodeKey="vm-1", x=..., y=...).
Chờ và chụp lại màn hình để xác nhận app đã mở.

8.2 Luồng 2: Gửi tín hiệu CAN từ script tự động

Script

# 1. Xác thực và tìm roomId
ROOM_ID=$(curl -H "X-API-Key: <key>" \
  "https://carsky.example.com/api/v1/devices?limit=1" | jq -r '.items[0].id')

# 2. Tìm node tín hiệu trong room
NODE_KEY=$(curl -H "X-API-Key: <key>" \
  "https://carsky.example.com/api/v1/signals/$ROOM_ID" | jq -r '.nodes[0].key')

# 3. Gửi tín hiệu
curl -X POST -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  "https://carsky.example.com/api/v1/signals/$ROOM_ID/$NODE_KEY/actuate" \
  -d '{"signals":[{"path":"Vehicle.Speed","value":60}]}'

8.3 Luồng 3: Mở ADB tunnel để dùng adb local

Code

Gọi MCP tool: vm_tunnel_open(roomId, nodeKey="vm-1").
Server trả về localhost:port, ví dụ localhost:5038.
Trên máy local, chạy: adb connect localhost:5038
Giờ có thể dùng: adb shell, adb logcat, appium, v.v.
Khi xong, gọi: vm_tunnel_close(roomId, nodeKey="vm-1").

9. Lưu ý quan trọng

Phân quyền: Các thao tác sửa/xóa/triển khai thường yêu cầu vai trò editor hoặc admin. Nếu gặp 403 Forbidden, hãy kiểm tra vai trò tài khoản.
Khóa API bảo mật: Không chia sẻ khóa a8k_... công khai. Nếu nghi ngờ lộ, xóa và tạo lại trong tab Credentials.
roomId và nodeKey:
roomId thường chính là ID của device đã chọn.
nodeKey là tên node trong blueprint (do người tạo blueprint đặt, ví dụ vm-1, can-1).
SSE endpoints (/watch, /subscribe): là Server-Sent Events, chỉ dùng được với client hỗ trợ stream.
MCP HTTP transport: khi bật MCP_TRANSPORT=http, server lắng nghe trên cổng 3100. Đảm bảo cổng này không bị chặn bởi firewall.
Tài liệu tự động: Luôn ưu tiên kiểm tra /api/v1/openapi.json và /api/v1/docs để có thông tin schema mới nhất.

10. Tóm tắt nhanh

Bạn muốn làm gì?	Dùng API endpoint	Dùng MCP tool
Kiểm tra hệ thống	`GET /api/v1/healthz`	`health_check`
Liệt kê blueprint	`GET /api/v1/blueprints`	`list_blueprints`
Triển khai blueprint	`POST /api/v1/deployments`	`deploy`
Chụp màn hình VM	`GET /api/v1/vms/{roomId}/{nodeKey}/screenshot`	`screenshot`
Chạm màn hình	`POST /api/v1/vms/{roomId}/{nodeKey}/tap`	`tap`
Nhập text	`POST /api/v1/vms/{roomId}/{nodeKey}/text`	`input_text`
Lấy UI tree	`GET /api/v1/vms/{roomId}/{nodeKey}/accessibility`	`ui_tree`
Chạy ADB shell	`POST /api/v1/vms/{roomId}/{nodeKey}/shell`	`adb_shell`
Đọc tín hiệu	`POST /api/v1/signals/{roomId}/{nodeKey}/values`	`get_signal_values`
Gửi tín hiệu	`POST /api/v1/signals/{roomId}/{nodeKey}/actuate`	`send_signals`
Mở ADB tunnel local	`GET /api/v1/deployments/{roomId}/adb-tunnel`	`vm_tunnel_open`
Đọc log	`GET /api/v1/deployments/{roomId}/logs/{nodeKey}`	`pod_logs`

11. Tài nguyên tham khảo

OpenAPI spec: https://<carsky-domain>/api/v1/openapi.json
Swagger UI: https://<carsky-domain>/api/v1/docs
MCP specification: https://modelcontextprotocol.io/