> Tài liệu cho AI agent trên MONA Cloud: cài MCP, dùng token đúng chỗ, chuỗi thử từng bước, bảng endpoint và cách xử lý các mã lỗi thường gặp.

Nguồn: https://monacloud.vn/agent-guide · Cập nhật: 2026-09-19

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

MONA Cloud (compute; trước đây VibeCloud) giúp AI agent tạo VPS, database và triển khai ứng dụng qua API. MONA đã làm phần mềm và hạ tầng cho 14.000+ dự án.

Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol (MCP). Mục tiêu là thử toàn bộ luồng bằng sandbox miễn phí trước khi tạo hạ tầng tính phí.

## Cài MONA Cloud MCP cho agent thế nào?

Thêm MCP vào Claude Code

```
claude mcp add monacloud -- npx -y monacloud-mcp
```

Cấu hình JSON cho client MCP

```
{
  "mcpServers": {
    "monacloud": {
      "command": "npx",
      "args": ["-y", "monacloud-mcp"]
    }
  }
}
```

Thêm MCP vào Codex

```
codex mcp add monacloud -- npx -y monacloud-mcp
```

Claude.ai · ChatGPT · Cursor (kết nối bằng URL)

```
https://mcp.monacloud.vn/mcp
```

Settings → Connectors → Add custom connector, dán URL rồi đăng nhập MONA Pass. Cursor dùng `"url": "https://mcp.monacloud.vn/mcp"` trong `mcp.json`; Codex dùng `[mcp_servers.monacloud] url = "https://mcp.monacloud.vn/mcp"`.

MCP **monacloud-mcp 0.5.0** và CLI **monacloud 0.4.1** đã LIVE. Các tool compute dùng namespace `cloud_*`:

| Tool | Công dụng |
| --- | --- |
| `cloud_link` | Kiểm tra hoặc thiết lập liên kết MONA Pass |
| `cloud_prices`, `cloud_packages` | Đọc đơn giá và các gói cấu hình |
| `cloud_vps_create` | Tạo VPS và trả job để theo dõi |
| `cloud_db_create` | Tạo database và trả job để theo dõi |
| `cloud_job_status` | Đọc hoặc poll job tới trạng thái cuối |
| `cloud_services_list` | Liệt kê VPS và database |
| `cloud_service_start`, `cloud_service_stop`, `cloud_service_rebuild` | Vận hành service |
| `cloud_agent_deploy` | Runtime agent riêng; deploy repo dùng `cloud_app_create` |
| `cloud_app_detect` | Đoán stack/port/Dockerfile từ `local_dir`, offline |
| `cloud_app_create` | Nhận `local_dir` để tự đóng zip/upload, hoặc `repo_url` cho git public |
| `cloud_app_list`, `cloud_app_get` | Liệt kê và đọc app |
| `cloud_app_deploy`, `cloud_app_env_set` | Deploy lại; thay toàn bộ env và deploy để áp dụng |
| `cloud_app_domain_add`, `cloud_app_logs`, `cloud_app_delete` | Thêm domain, đọc log, xoá app |
| `cloud_app_host_list`, `cloud_plan_list` | Đọc host và gói tháng/năm |
| `cloud_subscription_list`, `cloud_subscription_update` | Đọc và đổi subscription |
| `cloud_invoice_list`, `cloud_invoice_pdf` | Danh sách và file hoá đơn |
| `cloud_credit_redeem` | Đổi mã credit người dùng cung cấp |

Các alias cũ `vibecloud_*` vẫn chạy để giữ tương thích, nhưng tích hợp mới phải dùng tên `cloud_*` ở trên.

## Token nào dùng ở đâu?

Con agent hay kẹt ở chỗ này nên ghi thành bảng, đọc một lần là đủ.

| Việc | Token | Biến môi trường | Ghi chú |
| --- | --- | --- | --- |
| Gọi API compute `https://api.monacloud.vn` (VPS, database, app từ git hoặc upload, gói tháng, hoá đơn, mã credit) | `vc_live_*` tạo ở console → API keys, hoặc JWT MONA Pass lấy bằng `monacloud-mcp login` | `MONACLOUD_TOKEN` | Gửi `Authorization: Bearer <token>`. Cả hai loại đều dùng được cho mọi endpoint `/api/*`. |
| Ví chung `https://billing.monacloud.vn/v1/balance` | chỉ JWT MONA Pass | `MONA_PASS_TOKEN` | Token `vc_live_*` bị 401 ở đây. Tài khoản đang dùng ví local đọc số dư bằng `GET /api/me` (trả `{user: {credit_vnd, promo_credit_vnd, total_credit_vnd}}`). |
| Console web | phiên đăng nhập (MONA Pass hoặc email) | không cần | Chỉ người dùng bấm. |

Khách đã đăng ký và đưa sẵn token thì agent không cần đăng nhập gì thêm: đặt `MONACLOUD_TOKEN`, gọi `GET /api/me` để xác nhận, rồi làm việc bằng REST hoặc MCP. Không in token ra log, không ghi vào mã nguồn.

## Bắt đầu bằng các lệnh nào?

Kiểm tra token và đọc hợp đồng API

```
export MONACLOUD_TOKEN=vc_live_...        # khách đưa, hoặc lấy từ console → API keys
curl -s https://api.monacloud.vn/api/me -H "Authorization: Bearer $MONACLOUD_TOKEN"
curl -s https://api.monacloud.vn/openapi.json | head -c 400   # đọc hợp đồng thật trước khi gọi
```

Có Node thì chạy `npx -y monacloud deploy` để đưa **thư mục hiện tại** lên web, không cần GitHub. CLI monacloud 0.4.1 tự tải MCP qua npx; đặt `MONACLOUD_TOKEN` là chạy. Thêm `--git` để dùng remote hiện tại, `--repo <url>` để chỉ định repo public hoặc `--sandbox` để thử miễn phí. Không có Node, dùng hai request upload REST ở mục deploy local bên dưới.

## Đăng nhập MONA Pass thế nào?

```
npx -y monacloud-mcp login
```

Đăng nhập một lần bằng MONA Pass. MCP lưu token cục bộ và dùng cùng phiên đăng nhập cho nhóm sản phẩm MONA Cloud; không yêu cầu người dùng gửi username, password hoặc token vào chat. MONA Cloud nhận trực tiếp JWT có audience `vibecloud`.

Với curl, đặt access token MONA Pass vào biến môi trường của phiên shell, không ghi vào source hoặc log:

```
export MONACLOUD_API="https://api.monacloud.vn"
export MONA_PASS_TOKEN="<access-token>"
```

`https://api.vibecloud.vn` là alias tương thích của API và được giữ trong 12 tháng, đến hết ngày 04/09/2027. Tích hợp mới phải dùng `https://api.monacloud.vn`.

## Chuỗi thử từng bước trong sandbox

Các lệnh tạo tài nguyên dưới đây dùng prefix `/api/sandbox`. Có thể gọi route `/api/...` tương ứng với header `X-Vibecloud-Sandbox: 1` để nhận cùng hành vi.

### 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 → running → done` sau vài giây. Chỉ đọc `result` khi trạng thái là `done`; job thật 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 thật, 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 thật 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 thật, 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"
```

## Thử miễn phí bằng sandbox hoạt động thế nào?

Sandbox không gọi Proxmox, không cấp IP thật và không trừ tiền. Service và job được lưu tách bằng `sandbox: true`; dashboard trả chúng trong nhóm sandbox, không trộn với service thật. MongoDB tự dọn dữ liệu khi hết TTL, mặc định 24 giờ.

Sau khi tạo sandbox, các endpoint theo ID `GET /api/jobs/{id}`, `GET /api/services/{id}`, `POST /api/services/{id}/start|stop|rebuild` và `DELETE /api/services/{id}` tự fallback sang kho sandbox, không cần header. Response sandbox vẫn luôn có `sandbox: true`.

Endpoint danh sách vẫn tách biệt: không header chỉ trả tài nguyên thật, có header chỉ trả sandbox. Thêm `?include_sandbox=1` vào `GET /api/jobs` hoặc `GET /api/services` để gộp cả hai.

Dùng một trong hai cách:

- Prefix: `/api/sandbox/lxc`, `/api/sandbox/databases`, `/api/sandbox/jobs/{id}`, `/api/sandbox/services*`.
- Header: thêm `X-Vibecloud-Sandbox: 1` khi tạo qua `/api/lxc`, `/api/databases`, hoặc khi muốn list riêng sandbox qua `/api/jobs`, `/api/services`.

## Bảng endpoint cho agent

| Nhóm | Method và endpoint | Công dụng |
| --- | --- | --- |
| Discovery | `GET /health` | Trạng thái, phiên bản và thời gian API; không cần đăng nhập |
| Discovery | `GET /openapi.json`, `GET /docs` | OpenAPI và Swagger công khai |
| Giá | `GET /api/prices`, `GET /api/packages` | Đọc đơn giá và gói tài nguyên |
| VPS | `POST /api/lxc` | Tạo job provision LXC thật |
| Database | `POST /api/databases` | Tạo job provision database thật |
| Job | `GET /api/jobs/{id}` | Poll job thật hoặc sandbox theo ID |
| Service | `GET /api/services`, `GET /api/services/{id}` | List mặc định trả service thật; lookup ID tự fallback sandbox |
| Credential | `GET /api/services/{id}/credentials` + `X-Confirm: reveal` | Reveal credential có audit, tối đa 5 lần/giờ |
| Vận hành | `POST /api/services/{id}/start` | Khởi động service |
| Vận hành | `POST /api/services/{id}/stop` | Dừng compute của service |
| Vận hành | `POST /api/services/{id}/rebuild` | Tạo job rebuild LXC |
| Vận hành | `DELETE /api/services/{id}` | Xóa service và ngừng vòng đời tính phí |
| Sandbox | `/api/sandbox/...` | Cùng luồng agent nhưng không tạo hạ tầng và không tốn tiền |

## Mã lỗi và cách xử lý

| HTTP | Code/nguyên nhân | Agent cần làm |
| --- | --- | --- |
| `401` | Token thiếu, hết hạn hoặc JWT sai issuer/audience | Chạy lại `npx -y monacloud-mcp login`; không retry token cũ vô hạn |
| `402` | `insufficient_funds` | Yêu cầu người dùng nạp ví tại `https://monacloud.vn/console`, kiểm tra số dư rồi gọi lại |
| `402` | `budget_exceeded` | Yêu cầu người dùng tăng budget tại `https://monacloud.vn/console`; không tự bỏ giới hạn |
| `404` | Job/service/package không tồn tại hoặc không thuộc user | Kiểm tra lại ID và tài khoản đang đăng nhập |
| `409` | `engine_not_available` ở body cấp cao nhất | Chọn engine được liệt kê trong `message`; không poll vì chưa có job |
| `409` | Sai trạng thái, vượt quota hoặc thao tác xung đột khác | Đọc `detail`, poll job hiện tại hoặc gửi quota request |
| `422` | Payload sai schema | Đọc `/openapi.json`, sửa field rồi mới retry |
| `5xx` | Lỗi hạ tầng tạm thời | Giữ request context, retry có giới hạn; không tạo trùng service |

## Điều agent hay hiểu sai

- `stop` chỉ dừng compute. Disk và IP của service thật vẫn được giữ và tiếp tục tính phí; phải `DELETE /api/services/{id}` mới ngừng toàn bộ phí.
- Provision và rebuild là job bất đồng bộ. Nhận `job_id` chưa có nghĩa là xong; phải poll tới `succeeded` với job thật hoặc `done` với sandbox.
- IP, credential và connection string sandbox đều là giả. Không báo với người dùng rằng ứng dụng đã online sau một job sandbox.
- Custom domain dạng subdomain nên dùng CNAME trỏ vào hostname được cấp. Không đặt CNAME trực tiếp vào địa chỉ IP; apex domain cần A/ALIAS phù hợp nhà cung cấp DNS.
- Không gửi đồng thời `package_slug` và bộ `cpu/ram_gb/disk_gb`.
- Không đưa token, private key hoặc password database vào commit, issue hay output công khai.

## Bản đồ tài liệu cho agent

- OpenAPI máy đọc: `https://api.monacloud.vn/openapi.json`
- Swagger: `https://api.monacloud.vn/docs`
- Tài liệu agent raw: `https://monacloud.vn/ai-agent`
- Hướng dẫn API đầy đủ: `https://api.monacloud.vn/api/guide`
- Mục lục cho LLM: `https://monacloud.vn/llms.txt`
- Ngữ cảnh đầy đủ cho LLM: `https://monacloud.vn/llms-full.txt`

Trước khi tạo tài nguyên thật, agent phải đọc giá, xác nhận cấu hình, chạy luồng sandbox và chỉ chuyển sang route thật khi người dùng yêu cầu rõ ràng.

## Prompt mẫu cho AI

Prompt cho agent · không chứa secret

```
Đọc hướng dẫn này, kiểm tra giá và ví trước khi thao tác. Thử sandbox, xác minh sandbox: true và poll tới done. Báo cấu hình cùng chi phí VND, chỉ tạo tài nguyên tính phí sau khi tôi đồng ý. Không đưa token hoặc credential vào chat.
```

## Deploy app từ git đã LIVE

### Luồng deploy cho repo public

### 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 duyệt. Sau khi được duyệt, 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 duyệt trước khi tạo thật. `--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](https://monacloud.vn/docs/bat-dau-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 duyệt phí, bỏ header `X-Vibecloud-Sandbox: 1` để tạo thật. 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](https://console.monacloud.vn/apps).

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

**App từ git đã LIVE**, đo ngày 05/09/2026: repo git public → app host riêng của user (LXC + Dokploy, tạo lần đầu **~150 giây**) → deploy **10–20 giây** → URL `https://<repo>-<mã>.app.monacloud.vn` có cert Let's Encrypt.

Ví dụ thật: [https://monacloud-example-node-3fb5b2.app.monacloud.vn](https://monacloud-example-node-3fb5b2.app.monacloud.vn), từ [repo mẫu Node.js](https://github.com/themonagroup/monacloud-example-node). Xoá app → 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 thật 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 thật. Kiểm tra HTTPS và chức năng app trước khi chuyển traffic.

| Endpoint | Công dụng |
| --- | --- |
| `POST /api/apps` · `GET /api/apps` | Tạo từ git hoặc `source: "upload"`, liệt kê app |
| `POST /api/apps/{id}/upload` | Gửi multipart archive zip/tar.gz ≤ 80 MB và `build_path` |
| `GET /api/apps/{app_id}` | Đọc URL, trạng thái, lần deploy |
| `POST /api/apps/{app_id}/deploy` | Deploy lại nhánh đã chọn |
| `PUT /api/apps/{app_id}/env` | Thay toàn bộ env; deploy lại để áp dụng |
| `POST /api/apps/{app_id}/domains` | Thêm domain, trả hướng dẫn CNAME |
| `GET /api/apps/{app_id}/logs` · `DELETE /api/apps/{app_id}` | Log hoặc xoá app; xoá vẫn giữ host |
| `GET /api/app-hosts` · `POST /api/app-hosts` | Liệt kê/tạo app host riêng |
| `GET /api/plans` | Gói, cấu hình và giá tháng/năm |
| `GET /api/subscriptions` | Gói đang dùng và kỳ gia hạn |
| `POST /api/services/{service_id}/subscription` | Đổi gói/kỳ hoặc tắt gia hạn |
| `GET /api/invoices` · `GET /api/invoices/{invoice_id}.pdf` | Hoá đơn VAT 10% mỗi tháng và file tải |
| `POST /api/credit-codes/redeem` | Đổi mã credit |

Gói tháng 399.000đ, 999.000đ, 1.990.000đ, 3.990.000đ mỗi tháng, trả năm bằng giá 10 tháng; khách MONA 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](https://monacloud.vn/docs/deploy-nodejs) cho số đo ~150 giây / 10–20 giây / 31 giây, URL HTTPS thật 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.

## Deploy từ thư mục local, không cần GitHub

MCP **monacloud-mcp 0.5.0** và CLI **monacloud 0.4.1** đã hỗ trợ source local. Đặt `MONACLOUD_TOKEN` là chạy; CLI tự tải MCP qua npx. Ví local đọc số dư qua `GET /api/me`. Chọn một trong ba cách dưới đây; app host tính phí như VPS, app không tính thêm.

### 1. MCP tool: detect rồi create

`cloud_app_detect(local_dir)` đoán stack/port/Dockerfile, offline. Sau đó `cloud_app_create({local_dir})` tự đóng zip và upload; thao tác tạo app cần kết nối MONA Cloud. `local_dir` là đường dẫn tuyệt đối trên máy đang chạy MCP.

```
{"local_dir":"/duong-dan-tuyet-doi/du-an"}
```

Dùng đối số này cho `cloud_app_detect`, đọc kết quả, rồi gọi `cloud_app_create` với cùng `local_dir` và cấu hình build/cổng phù hợp. Đọc giá và ví, thử `sandbox: true` để mô phỏng, không tính phí và duyệt phí trước khi tạo thật; poll bằng `cloud_job_status`, kiểm tra `cloud_app_get` và `cloud_app_logs`.

Prompt mẫu cho Claude Code/Codex:

```
Đưa dự án trong thư mục này lên web bằng MONA Cloud. Token ở biến MONACLOUD_TOKEN. Dùng cloud_app_detect rồi cloud_app_create với local_dir, xong đưa tôi link https.
```

### 2. CLI: chạy ngay trong thư mục dự án

Có Dockerfile/package.json trong thư mục hiện tại và `MONACLOUD_TOKEN` trong môi trường:

```
npx -y monacloud deploy --sandbox
npx -y monacloud deploy
```

Lệnh có `--sandbox` thử miễn phí và trả URL giả; sau khi duyệt phí, chạy lệnh thứ hai để deploy thật. CLI mặc định deploy **thư mục hiện tại**, kể cả khi thư mục có git remote. Dùng `--git` để lấy remote hiện tại hoặc `--repo <url>` nếu có URL GitHub public. `--build nixpacks` dùng khi không có Dockerfile và stack hỗ trợ Nixpacks.

### 3. Curl: tạo app upload rồi gửi archive

Hai request dưới đây tạo app thật sau khi đã duyệt phí host. Để thử miễn phí, dùng CLI `--sandbox` hoặc MCP `sandbox: true` ở trên.

`POST /api/apps` thêm `source: "git" | "upload"`. Với `source=upload`, không cần `repo_url`. Ví dụ dưới đây dùng app có Dockerfile, cổng 3000; chỉnh theo dự án. Đặt `MONACLOUD_TOKEN` trong phiên shell và `MONACLOUD_API=https://api.monacloud.vn`.

Tạo app chờ upload:

```
curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"upload","build_type":"dockerfile","port":3000}'
```

Phản hồi có dạng:

```
{
  "id": "<app-id>",
  "upload_url": "/api/apps/<app-id>/upload",
  "max_bytes": 83886080,
  "job_id": "<job-id>",
  "status": "awaiting_upload",
  "url": "<url-https-cua-app>"
}
```

`id` là ID app, `job_id` là ID job. `awaiting_upload` chưa phải deploy xong. Gán `APP_ID` bằng `id` vừa nhận. Chuẩn bị `app.zip` sao cho Dockerfile hoặc các file ứng dụng nằm ngay gốc archive, rồi gửi lệnh thứ hai:

```
APP_ID="<app-id-tra-ve>"
curl -sS -X POST "$MONACLOUD_API/api/apps/$APP_ID/upload" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -F archive=@app.zip \
  -F build_path=/
```

`POST /api/apps/{id}/upload` nhận multipart `archive` (zip hoặc tar.gz ≤ 80 MB) + `build_path` (mặc định `/`). Có thể đổi sang `-F archive=@app.tar.gz`. Không đặt `Content-Type: application/json` cho upload; curl tự tạo multipart boundary.

Server tự loại `node_modules/`, `.git/`, `.env*`, `*.pem`; chặn zip-slip; **file phải nằm ở gốc archive**, không bọc thêm một thư mục.

Upload trả job id, sau đó poll `GET /api/jobs/{id}` như git, dùng ID job trong phản hồi upload. Đợi job trả `succeeded`, đọc `GET /api/apps/{app_id}` rồi kiểm tra URL HTTPS. Nếu job lỗi, đọc lỗi và log trước khi thử lại; không tạo app mới liên tục. Đọc [API reference](https://monacloud.vn/docs/api) cho schema.

### Kết quả mong đợi khi deploy từ thư mục local là gì?

| Kết quả mong đợi | Thời gian đo ngày 05/09/2026 (tối) |
| --- | --- |
| Upload API → URL https 200, gồm build image | 112 giây |
| MCP `cloud_app_create(local_dir)` → URL HTTPS, host đã có | 33 giây |
| App host đầu tiên | ~150 giây |

Đây là số đo thực tế, không phải cam kết thời gian build cho mọi dự án.

### Lỗi thường gặp khi upload

| Lỗi thường gặp | Cách xử lý |
| --- | --- |
| Archive bọc thêm thư mục → 502 | Đóng lại từ bên trong thư mục dự án để file nằm ngay gốc archive; `build_path` mặc định `/` |
| Thiếu Dockerfile | Dùng `cloud_app_detect` để nhận diện stack, chọn `build_type: "nixpacks"` / `--build nixpacks` nếu stack được hỗ trợ, hoặc thêm Dockerfile |
| Archive > 80 MB (83886080 byte) | Loại dependency, cache và file không cần khỏi archive trước khi gửi; server chỉ lọc sau khi nhận, không thay thế bước giảm dung lượng |

## Gói tháng và hoá đơn đã LIVE

## Gói tháng đang bán có những mức nào?

| Gói | Giá mỗi tháng | Giá trả năm (bằng giá 10 tháng) |
| --- | --- | --- |
| Khởi nghiệp | 399.000đ | 3.990.000đ |
| Kinh doanh | 999.000đ | 9.990.000đ |
| Doanh nghiệp | 1.990.000đ | 19.900.000đ |
| Quy mô lớn | 3.990.000đ | 39.900.000đ |

Khách MONA có gói miễn phí theo quyền tài khoản; credit tặng **100.000đ khi đăng ký**. Đọc `GET /api/plans` hoặc `cloud_plan_list` để lấy `code`, CPU/RAM/disk và giá tháng/năm hiện hành. Backup PBS đang mở; không coi dòng cấu hình gói là bằng chứng đã có restore.

## Mua và quản lý gói qua CLI hoặc API thế nào?

```
npx monacloud plans
npx monacloud vps create --plan kinh-doanh --monthly
npx monacloud invoices
```

Chọn mã gói từ danh sách trả về. API tạo VPS dùng `POST /api/lxc` với `app_name`, `billing_mode: "monthly"`, `plan_code` và `period: "month"` hoặc `"year"`; không trộn package hoặc custom sizing. App host dùng `POST /api/app-hosts` với cùng các trường tính phí, rồi truyền `app_host_id` cho `POST /api/apps`.

Đọc `GET /api/subscriptions` để kiểm tra kỳ và gia hạn. `POST /api/services/{service_id}/subscription` nhận `plan_code`, `period`, `auto_renew`, `cancel_action`. Nâng gói tính phần thời gian còn lại; hạ gói từ kỳ sau. Tắt gia hạn bằng `auto_renew: false`; chọn `cancel_action: "hourly"` hoặc `"stop"` và kiểm tra kỳ hiệu lực trả về.

MCP có `cloud_subscription_list` và `cloud_subscription_update`. CLI/MCP thử cấu hình gói qua hourly sandbox miễn phí, không tạo subscription sandbox; vẫn báo giá kỳ thật trước khi bạn duyệt.

## Xem hoá đơn VAT mỗi tháng ở đâu?

**Hoá đơn VAT 10% mỗi tháng đã LIVE.** Mở [console /invoices](https://console.monacloud.vn/invoices), dùng `GET /api/invoices` hoặc `cloud_invoice_list`. Tải file bằng `GET /api/invoices/{invoice_id}.pdf`, `cloud_invoice_pdf` hoặc `npx monacloud invoices --pdf <id>`.

Đọc số tiền và thuế trên hoá đơn của tài khoản. Danh sách nạp ví `GET /api/payments` là dữ liệu thanh toán riêng. Quản lý gói tại [console /subscriptions](https://console.monacloud.vn/subscriptions); đăng nhập MONA Pass đã bật.

## Dùng mã credit như thế nào?

Console đã có redeem mã credit. MCP dùng `cloud_credit_redeem` với mã bạn nhận được; API dùng:

```
curl -sS -X POST "$MONACLOUD_API/api/credit-codes/redeem" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"<ma-credit-cua-ban>"}'
```

Đặt token theo [bắt đầu nhanh](https://monacloud.vn/docs/bat-dau-nhanh); kiểm tra kết quả và số dư sau khi đổi mã. Xem [API reference](https://monacloud.vn/docs/api) cho schema đầy đủ.