Hướng dẫn MONA Cloud cho AI agent

1. Đọc bảng giá

Với MCP, gọi cloud_prices hoặc cloud_packages.

curl -sS "$MONACLOUD_API/api/prices"

2. Tạo VPS sandbox

Với MCP, gọi cloud_vps_create sau khi đã xác nhận cấu hình và chi phí.

curl -sS -X POST "$MONACLOUD_API/api/sandbox/lxc" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"agent-demo","cpu":1,"ram_gb":1,"disk_gb":10}'

Lưu trường id thành VPS_JOB_ID. Response luôn có sandbox: true và IP giả thuộc dải 10.99.x.x.

3. Poll job tới done

Với MCP, gọi cloud_job_status với job_id vừa nhận.

export VPS_JOB_ID="<id-tu-buoc-2>"
curl -sS "$MONACLOUD_API/api/jobs/$VPS_JOB_ID" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

Lookup theo ID tự tìm trong kho sandbox nếu không có bản ghi thật, nên poll GET /api/jobs/{id} không cần gửi lại header sandbox. Job sandbox chuyển queued, rồi running, rồi done sau vài giây. Chỉ đọc result khi trạng thái là done; job tính phí dùng trạng thái hoàn tất succeeded.

4. Tạo database sandbox

Với MCP, gọi cloud_db_create, sau đó theo dõi bằng cloud_job_status.

curl -sS -X POST "$MONACLOUD_API/api/sandbox/databases" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"agent-demo-db","engine":"postgresql","cpu":1,"ram_gb":1,"disk_gb":10}'

Poll id của response qua /api/jobs/{id} như bước 3. Credential, connection string và IP trong sandbox chỉ là dữ liệu giả để kiểm tra tích hợp.

engine nhận mongodb, postgresql, mysql; alias cũ mongo được chuẩn hoá thành mongodb. Với route tính phí, backend kiểm tra template đã resolve trên Proxmox trước khi nhận job (inventory cache 10 phút). PostgreSQL/MySQL mặc định dùng template Ubuntu từ PROXMOX_LXC_TEMPLATE rồi cài engine lúc provision; nếu operator cấu hình template riêng thì backend dùng đường nhanh đó.

Khi template chưa có, API trả thẳng HTTP 409 (không tạo job):

{
  "code": "engine_not_available",
  "message": "Engine được yêu cầu tạm không khả dụng; chọn engine trong phản hồi API",
  "next_step": "Chọn engine đang khả dụng hoặc thử lại sau khi template đã được cài trên node Proxmox."
}

Route sandbox không kiểm tra inventory Proxmox. Job tính phí công bố stages[]; mỗi stage có status là running, succeeded hoặc failed, cùng started_at, completed_at và duration_seconds để agent theo dõi thời gian provision.

Connection string khi thành công:

• PostgreSQL: postgresql://user:password@host:5432/database?sslmode=require
• MySQL: mysql://user:password@host:3306/database (server bắt buộc TLS)
• MongoDB: mongodb://user:password@host:27017/database?authSource=database&tls=true

5. Lấy credential rồi deploy

Backend MONA Cloud provision hạ tầng; agent deploy source qua SSH sau khi job hoàn tất. Lấy service_id trong result, đọc service trước, rồi gọi endpoint reveal riêng khi thực sự cần SSH. Service detail và job result không trả private key hay root password.

Với MCP, dùng cloud_services_list để lấy danh sách tài nguyên hiện tại.

export VPS_SERVICE_ID="<service_id-trong-result>"
curl -sS "$MONACLOUD_API/api/services/$VPS_SERVICE_ID" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

curl -sS "$MONACLOUD_API/api/services/$VPS_SERVICE_ID/credentials" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "X-Confirm: reveal"

Endpoint reveal được audit và giới hạn 5 lần/giờ/token. Với service tính phí, dùng credential vừa reveal để rsync source, cài dependency, đưa secret database vào biến môi trường, chạy migration và kiểm tra health URL. Không thử SSH vào IP 10.99.x.x; đó là IP giả của sandbox.

6. Dừng service

Với MCP, gọi cloud_service_stop.

curl -sS -X POST "$MONACLOUD_API/api/services/$VPS_SERVICE_ID/stop" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

1. Đăng nhập, đọc dự án và thử bằng MCP

Đăng nhập MONA Pass bằng npx -y monacloud-mcp login. Dùng MCP monacloud-mcp 0.5.0 và CLI monacloud 0.4.1. Giao prompt sau cho AI:

Đọc repo của tôi. Gọi cloud_app_list và cloud_app_host_list để tránh tạo trùng, cloud_prices, cloud_plan_list và cloud_balance để tính phí. Nếu chưa có host, gọi cloud_app_create với repo_url, branch, build_type, port đúng dự án và sandbox=true. Báo ước tính để tôi đồng ý. Sau khi tôi đồng ý, gọi cloud_app_create với sandbox=false, poll bằng cloud_job_status, kiểm cloud_app_get/cloud_app_logs và HTTPS rồi trả URL.

2. Deploy bằng CLI thế nào?

CLI dùng npx -y monacloud deploy --repo <url>. Ví dụ dưới đây dùng repo Node.js mẫu có Dockerfile; thay URL, nhánh, kiểu build và cổng theo dự án của bạn:

npx -y monacloud deploy --repo https://github.com/themonagroup/monacloud-example-node --branch main --build dockerfile --sandbox
npx -y monacloud deploy --repo https://github.com/themonagroup/monacloud-example-node --branch main --build dockerfile

Lần đầu chạy thử miễn phí; lệnh thứ hai hiển thị ước tính và hỏi bạn đồng ý trước khi tạo tài nguyên tính phí. --build nhận dockerfile, nixpacks hoặc static. Với repo hiện tại có remote và nhánh, chạy npx -y monacloud deploy --git. Không có cờ nguồn, CLI deploy thư mục hiện tại. Chọn một công cụ tạo app: nếu AI đã deploy ở bước 1 thì dùng ID đó để kiểm tra, không tạo lại bằng CLI.

3. Gọi API và đọc kết quả thế nào?

Nếu dùng curl thay cho MCP/CLI, đặt token theo bắt đầu nhanh và thử POST /api/apps:

curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/themonagroup/monacloud-example-node","branch":"main","build_type":"dockerfile","dockerfile":"Dockerfile","port":3000}'

Sau khi bạn đồng ý với báo giá, bỏ header X-Vibecloud-Sandbox: 1 để tạo app tính phí. API trả job có id; thay JOB_ID bằng ID nhận được và đọc tới trạng thái cuối:

export JOB_ID="<job-id-tra-ve>"
curl -sS "$MONACLOUD_API/api/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"

Lấy result.app_id, đọc GET /api/apps/{app_id} để kiểm tra status, url, last_deploy và errorMessage. Khi timeout, đọc lại job cũ trước; không gửi create lặp. Quản lý app tại console /apps.

Kết quả mong đợi khi deploy git là gì?

Ví dụ: https://monacloud-example-node-3fb5b2.app.monacloud.vn, từ repo mẫu Node.js. Xoá app rồi tạo lại: 31 giây khi đã có app host. Đây là số đo của repo mẫu; thời gian build dự án của bạn phụ thuộc source, dependency và tài nguyên.

Job tính phí kết thúc ở succeeded; trạng thái app là done. Sandbox kết thúc ở done, có sandbox: true và URL giả; không có website chạy được. Kiểm tra HTTPS và chức năng app trước khi chuyển traffic.

Gói tháng 399.000đ, 999.000đ, 1.990.000đ và 3.990.000đ mỗi tháng, trả năm bằng giá 10 tháng; khách MONA có gói miễn phí, credit đăng ký 100.000đ. App host tính như VPS, app không tính thêm. Repo private đang mở qua GitHub App.

POST /api/app-hosts với {} tạo host mặc định 2 CPU/2 GB RAM/30 GB disk; route này không nhận sandbox. Dùng POST /api/apps với X-Vibecloud-Sandbox: 1 để mô phỏng host và xem ước tính, không tính phí. Khi dùng gói tháng, tạo host với billing_mode, plan_code, period, rồi truyền app_host_id vào app create.

Xem triển khai repo mẫu cho số đo ~150 giây / 10–20 giây / 31 giây, URL HTTPS và cách poll job. OpenAPI giữ nguyên schema nguồn; route tải .pdf trả file theo summary, dù schema nguồn vẫn khai báo response JSON tổng quát. CLI/MCP có lệnh tải file riêng.