Bỏ qua đến nội dung chính
Thuê và điều khiển máy Cloud bằng agent hoặc script

Tài liệu API & MCP AIDev Cloud

Cho agent AI (Claude, Cursor, Codex…) hoặc script của bạn thuê, bật, tắt và trả máy GPU/CPU AIDev Cloud bằng token riêng, tiền trừ vào ví AIDev của bạn.

Cập nhật: 08/10/2026
API v1
Mục lục
1. Bắt đầu
2. Cài MCP
3. Luồng mẫu
4. REST API
5. Tiền và giới hạn
6. Mã lỗi
7. An toàn

1. Bắt đầu

  • Bật xác thực hai lớp (TOTP) trong tài khoản.
  • Nạp ví AIDev ít nhất một lần.
  • Tạo token agent (cần mật khẩu và mã TOTP). Token chỉ hiện một lần: lưu lại ngay.
Bật TOTPTạo token agent

Scope

ScopeCho phép
cloud:selfXem gói, xem máy, bật, tắt, khởi động lại máy, quản lý SSH key.
cloud:self:spendThuê máy và trả máy (trừ tiền ví).

Mỗi token sống tối đa 90 ngày, mỗi tài khoản có tối đa 5 token. Xoay hoặc thu hồi token ở cùng trang tạo token.

Máy chạy Ubuntu hoặc Windows đều dùng được với agent. Trên Windows, agent vào máy bằng SSH key với tài khoản Administrator và chạy lệnh qua PowerShell; bạn vẫn vào bằng Remote Desktop với mật khẩu xem trên web.

2. Cài MCP

Thay <token> bằng token agent của bạn (dạng aidev_pat_…).

Claude Code (terminal)
claude mcp add --transport http aidev-cloud https://api.forai.dev/mcp --header "Authorization: Bearer <token>"
Claude Desktop: claude_desktop_config.json (cần Node.js)
{ "mcpServers": { "aidev-cloud": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.forai.dev/mcp", "--header", "Authorization:${AIDEV_AUTH}" ], "env": { "AIDEV_AUTH": "Bearer <token>" } } } }
Cursor: ~/.cursor/mcp.json
{ "mcpServers": { "aidev-cloud": { "url": "https://api.forai.dev/mcp", "headers": { "Authorization": "Bearer <token>" } } } }
Codex: ~/.codex/config.toml (đặt biến môi trường AIDEV_TOKEN=<token>)
[mcp_servers.aidev-cloud] url = "https://api.forai.dev/mcp" bearer_token_env_var = "AIDEV_TOKEN"

Skill aidev-cloud dạy agent luồng thuê máy an toàn: hỏi bạn trước khi tiêu tiền, chỉ gửi public key, trả máy khi xong.

Tải Skill aidev-cloud

3. Luồng mẫu

Ví dụ với máy Ubuntu. Trên Windows làm y hệt, user là Administrator và lệnh chạy qua PowerShell.

1. Sinh SSH key (bỏ qua nếu ~/.ssh/aidev đã có: không ghi đè key cũ)
ssh-keygen -t ed25519 -f ~/.ssh/aidev -N ""
  • 2. Nhờ agent: "thuê một máy RTX 3090 với key ~/.ssh/aidev.pub".
  • 3. Agent đọc giá theo giờ (pricePerHour, hoặc pricePerHourWithPublicIp nếu thuê kèm IP công khai), xem gói còn chỗ không (slotState) và chờ bạn đồng ý.
  • 4. Agent hỏi lại máy mỗi 15–30 giây tới khi status active, vmStatus running. Gặp status error thì dừng: tiền giữ đã được trả lại, không bị tính.
5. Vào máy (host và port lấy từ mục connections có protocol ssh, user từ sshUser)
ssh -i ~/.ssh/aidev -p <port> <sshUser>@<host>

6. Xong việc thì bảo agent "trả máy". Chỉ trả máy mới dừng tính tiền.

4. REST API

Base URL
https://api.forai.dev/capi/v1/cloud
  • Xác thực: header Authorization: Bearer aidev_pat_…. Không dùng cookie hay JWT.
  • Idempotency-Key: <uuid> bắt buộc với lệnh thuê, trả, bật, tắt, khởi động lại máy và xóa key. Timeout thì gửi lại đúng key cũ với đúng body cũ: không bao giờ tạo máy thứ hai. Key gắn với body, đổi body thì phải dùng key mới.
  • Đường dẫn mang ids, lệnh bật/tắt/khởi động lại gửi revision trong body, trả máy gửi ?revision=. Kết quả trả về là dữ liệu của tool MCP tương ứng.
  • Lỗi trả về { code, message, details, requestId }.

Các route

RouteTool MCPScopeGhi chú
GET /planscloud_plans_listcloud:self?page&limit. Các gói, giá theo giờ hiện hành, còn chỗ hay không.
GET /plans/:idscloud_plan_getcloud:selfHệ điều hành chọn được (images), giá có và không có IP công khai.
GET /instancescloud_my_instancescloud:self?status&page&limit. Mặc định active: gồm cả máy đang tắt (vẫn tính tiền); status=all để xem mọi máy.
GET /instances/:idscloud_my_instance_getcloud:selfstatus, vmStatus, revision, sshUser, connections, sshKeys. Không có mật khẩu.
POST /instancescloud_my_instance_createcloud:self:spendThuê máy, trừ tiền ví (201). Mọi lỗi từ chối xảy ra trước khi ghi gì: không có máy, không mất tiền. Cần Idempotency-Key.
POST /instances/:ids/startcloud_my_instance_startcloud:selfBật máy, body { revision }. Cần Idempotency-Key.
POST /instances/:ids/stopcloud_my_instance_stopcloud:selfTắt máy (vẫn tính tiền), body { revision }. Cần Idempotency-Key.
POST /instances/:ids/restartcloud_my_instance_restartcloud:selfKhởi động lại, body { revision }. Cần Idempotency-Key.
DELETE /instances/:ids?revision=cloud_my_instance_terminatecloud:self:spendTrả máy: dừng tính tiền, dữ liệu trên ổ đĩa mất vĩnh viễn. Cần Idempotency-Key.
GET /ssh-keyscloud_ssh_keys_listcloud:selfSSH key lưu trong tài khoản (tối đa 20).
POST /ssh-keyscloud_ssh_key_addcloud:selfLưu key (201); key đã có thì trả lại key đó với existing: true. Idempotency-Key tùy chọn.
DELETE /ssh-keys/:idscloud_ssh_key_removecloud:selfXóa key khỏi tài khoản (204), không gỡ khỏi máy đang chạy. Cần Idempotency-Key.

Ví dụ curl

Đặt token vào biến môi trường
export AIDEV_TOKEN=aidev_pat_…
Danh sách gói
curl -s "https://api.forai.dev/capi/v1/cloud/plans?limit=20" -H "Authorization: Bearer $AIDEV_TOKEN"
Thuê máy (giữ nguyên KEY nếu phải gửi lại sau timeout)
KEY=$(uuidgen) curl -s -X POST "https://api.forai.dev/capi/v1/cloud/instances" -H "Authorization: Bearer $AIDEV_TOKEN" \ -H "Idempotency-Key: $KEY" -H "Content-Type: application/json" \ -d '{"planIds":"<planIds>","imageIds":"<imageIds>","sshPublicKeys":["ssh-ed25519 AAAA… you@laptop"],"expectedPricePerHour":"<giá VND/giờ>"}'
Bật máy
curl -s -X POST "https://api.forai.dev/capi/v1/cloud/instances/<ids>/start" -H "Authorization: Bearer $AIDEV_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ -d '{"revision":"<revision>"}'
Trả máy
curl -s -X DELETE "https://api.forai.dev/capi/v1/cloud/instances/<ids>?revision=<revision>" -H "Authorization: Bearer $AIDEV_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"

Tham chiếu từ OpenAPI

RouteTham số bắt buộcBody
GET /capi/v1/cloud/plans——
GET /capi/v1/cloud/plans/{ids}ids (path)—
GET /capi/v1/cloud/instances——
POST /capi/v1/cloud/instancesIdempotency-Key (header)JSON
GET /capi/v1/cloud/instances/{ids}ids (path)—
DELETE /capi/v1/cloud/instances/{ids}ids (path), Idempotency-Key (header), revision (query)—
POST /capi/v1/cloud/instances/{ids}/startids (path), Idempotency-Key (header)JSON
POST /capi/v1/cloud/instances/{ids}/stopids (path), Idempotency-Key (header)JSON
POST /capi/v1/cloud/instances/{ids}/restartids (path), Idempotency-Key (header)JSON
GET /capi/v1/cloud/ssh-keys——
POST /capi/v1/cloud/ssh-keys—JSON
DELETE /capi/v1/cloud/ssh-keys/{ids}ids (path), Idempotency-Key (header)—

Tài liệu OpenAPI đầy đủ: https://api.forai.dev/capi/v1/openapi.json

5. Tiền và giới hạn

Máy tắt vẫn tính tiền

Máy tính tiền theo giờ, trừ vào ví AIDev. Máy đang tắt vẫn tính tiền; chỉ trả máy mới dừng tính. Ví hết tiền thì hệ thống thu hồi máy, và dữ liệu trên ổ đĩa cũng mất như khi trả máy.

  • Không giới hạn số máy.
  • Mặc định 1000 lệnh ghi mỗi ngày (giờ Việt Nam) cho mỗi token, chỉnh được ở trang quản lý token; lệnh đọc, lệnh bị từ chối hoặc lỗi, gửi lại cùng yêu cầu và trả máy không tính vào giới hạn này.
  • Bật, tắt, khởi động lại: tối đa 1 lệnh mỗi phút cho mỗi máy.
  • 120 lượt gọi mỗi phút cho mỗi token.
  • CLOUD_LOW_RUNWAY: tính cả máy mới, số dư chỉ đủ chạy dưới 3 giờ; agent hỏi lại bạn và chỉ tạo máy khi bạn đồng ý.
  • INSUFFICIENT_FUNDS: nạp ví trên web rồi thử lại.
  • CLOUD_PRICE_CHANGED: giá đã đổi, đọc lại giá rồi hỏi lại bạn; bạn đồng ý thì gửi lại với Idempotency-Key mới.

6. Mã lỗi

MãKhi nàoCách xử lý
AGENT_GATEWAY_DISABLED503: cổng agent đang tạm tắt.Thử lại sau.
UNAUTHORIZED401: token không dùng được. Xem details.reason.AGENT_TOKEN_INVALID (sai, hết hạn, bị thu hồi): tạo hoặc xoay token. CLOUD_AGENT_DISABLED: tính năng đang tắt, chờ AIDev mở; token mới không giúp được.
AGENT_SCOPE_FORBIDDEN403: token thiếu scope của lệnh.Tạo token có cloud:self:spend nếu cần thuê hoặc trả máy.
AGENT_ROLE_FORBIDDEN403: tài khoản không được dùng lệnh này.Liên hệ AIDev.
AGENT_RATE_LIMITED429: vượt giới hạn gọi, hoặc bật/tắt một máy quá 1 lệnh mỗi phút.Chờ details.retryAfter giây rồi thử lại (giới hạn theo lượt và theo máy còn kèm details.retryAfterSeconds).
AGENT_LIMIT_UNAVAILABLE500: tạm không đếm được giới hạn của lệnh; chưa có gì được ghi.Thử lại sau khoảng một phút, giữ nguyên requestId nếu lệnh có.
VALIDATION_ERROR400: tham số sai, kể cả key sai (sshPublicKeys.<i>), hơn 5 key trong một mảng hoặc không có key nào.Xem details.issues.
RESOURCE_NOT_FOUND404: không có máy, gói hay key này trong tài khoản của bạn.Kiểm lại ids.
PAYLOAD_TOO_LARGE413: body REST lớn hơn 100 KB.Gửi body nhỏ hơn.
INTERNAL_ERROR500: lỗi phía AIDev.Thử lại sau; lặp lại thì báo AIDev kèm requestId.
IDEMPOTENCY_KEY_REQUIRED400 (chỉ REST): lệnh ghi thiếu header Idempotency-Key.Gửi một uuid mới cho mỗi lệnh mới.
AGENT_REQUEST_IN_PROGRESSLệnh cùng requestId đang chạy.Chờ 10–30 giây rồi gửi lại đúng requestId đó.
AGENT_REQUEST_ID_REUSEDrequestId đã dùng cho một lệnh khác tham số.Không đổi tham số khi gửi lại; lệnh mới cần requestId mới.
AGENT_REQUEST_FAILEDLệnh cùng requestId đã thất bại trước đó (details.originalCode).Xử lý theo originalCode. Với lệnh thuê máy: xem GET /instances?status=all trước khi gửi requestId mới.
AGENT_IDEMPOTENCY_UNAVAILABLETạm không kiểm được requestId.Thử lại sau ít phút.
CLOUD_PRICE_CHANGEDThuê máy: expectedPricePerHour khác giá hiện hành (details.pricePerHour).Đọc lại giá, hỏi lại chủ tài khoản; đồng ý thì gửi lại với requestId (Idempotency-Key) mới.
CLOUD_LOW_RUNWAYThuê máy (409): tính cả máy mới, ví và credit Cloud chỉ đủ cho các máy chạy dưới 3 giờ (details.runwayMinutes).Báo chủ tài khoản: hết tiền, máy tự tắt và xóa dữ liệu. Đồng ý thì gửi lại với acknowledgeLowRunway: true và requestId (Idempotency-Key) mới, hoặc nạp thêm rồi thử lại.
INSUFFICIENT_FUNDSThuê máy: ví và credit Cloud không đủ cho giờ đầu (details.required, details.available).Nạp ví trên web rồi thử lại.
CLOUD_NO_CAPACITYThuê máy: gói hết máy chủ hoặc IP trống.Chọn gói khác hoặc chờ.
CLOUD_PUBLIC_IP_UNAVAILABLEThuê máy: hết IP công khai.Thuê lại không kèm usePublicIp, giá là pricePerHour (hỏi lại chủ tài khoản).
CLOUD_PLAN_INACTIVEThuê máy: gói đã ngừng bán.Chọn gói khác.
CLOUD_IMAGE_INCOMPATIBLEThuê máy: hệ điều hành không dùng được với gói này.Chọn một images của chính gói đó.
CLOUD_SSH_KEY_TOO_MANYThuê máy: key đã lưu cộng key dán thêm vượt 5.Gửi tổng cộng 1 đến 5 key.
FEATURE_DISABLEDThuê máy: AIDev đang tạm dừng cho thuê.Thử lại sau.
AGENT_STALEMáy đã đổi từ lần đọc trước.Đọc lại máy, lấy revision mới.
AGENT_CLOUD_VM_STATEMáy không ở trạng thái cho phép lệnh này.Xem allowedActions của máy.
CLOUD_INSTANCE_VM_STATE_CHANGED409, bật/tắt/khởi động lại: trạng thái máy vừa đổi.Đọc lại máy rồi thử lại.
CLOUD_INSTANCE_ALREADY_TERMINATEDTrả máy: máy đã được trả hoặc thu hồi.Không cần làm gì thêm.
CONFLICT_ERROR409, trả máy: máy đang có thao tác khác.Đọc lại máy rồi thử lại.
BILLING_CLOUD_CREDIT_SETTLE_RETRYTrả máy: chưa chốt xong tiền.Gửi lại với đúng requestId cũ.
BILLING_CLOUD_CREDIT_HOLD_STALETrả máy: chưa chốt xong tiền.Gửi lại với đúng requestId cũ.
CLOUD_SSH_KEY_LIMITLưu key: tài khoản đã đủ 20 key. Key đã lưu thì vẫn trả 201 với existing: true.Xóa bớt key không dùng.
CLOUD_SSH_KEY_DUPLICATETrên web: key đã có trong tài khoản.Dùng key đã có, id ở details.ids.

7. An toàn

  • Không bao giờ gửi private key cho agent hay AIDev: chỉ public key (.pub) rời máy bạn.
  • Token bị lộ thì xoay hoặc thu hồi ngay ở trang token agent.
  • Sau khi agent tạo máy, mở chi tiết máy trên web, xem khối "SSH key trên máy" và đối chiếu fingerprint với key của bạn.
Xem fingerprint key của bạn
ssh-keygen -lf ~/.ssh/aidev.pub