zo CLI và MCP server

zo deploy một thư mục hoặc repo Git, theo dõi build và log, đặt biến, thêm database và tên miền, từ terminal, CI hoặc AI agent. Chạy trên macOS, Linux và Windows.

Cài đặt

macOS, Linux:

curl -fsSL https://app.zocloud.io/install.sh | sh

Windows: tải zo.exe ở Tài khoản → mục Deploy từ máy của bạn (liên kết "Windows: tải zo.exe").

Kiểm tra: zo version.

Đăng nhập

Tạo token ở portal: Tài khoản → Token truy cập → Tạo token (xem Tổ chức, thành viên và bảo mật tài khoản).
Chạy:

zo login              # dán token khi được hỏi
zo login -token zc_pat_…
zo whoami             # e-mail, các tổ chức và vai trò
zo logout

Token được lưu ở ~/.config/zocloud/config.json (quyền 600). Trong CI hoặc agent, đặt biến môi trường ZOCLOUD_TOKEN thay vì đăng nhập.

Ngôn ngữ: zo lang vi hoặc zo lang en (mặc định theo hệ thống).

Gắn thư mục với service

Service được ghi theo dạng tổ-chức/project/service.

zo link myorg/shop/web

Lệnh này tạo file .zocloud.json trong thư mục (không phải zocloud.json cấu hình build). Các lệnh status, logs, vars, db, domains, scale, rollback, open dùng service đã gắn của thư mục hiện tại (hoặc thư mục cha).

Deploy

zo deploy -to myorg/shop/web     # lần đầu: gắn và deploy
zo deploy                        # các lần sau
zo deploy ./apps/api             # deploy một thư mục khác
zo deploy -detach                # không chờ build

Project và service được tạo tự động nếu chưa có.
zo đóng gói thư mục và gửi lên; bỏ qua .git, node_modules, .venv, venv, __pycache__…, các mẫu trong .gitignore, .zocloudignore, .dockerignore. Không bao giờ gửi file .env* (trừ .env.example): đặt biến bằng zo vars.
zo in log build, trạng thái, và địa chỉ HTTPS khi xong.
Trước khi deploy, zo detect cho biết ZoCloud sẽ nhận diện framework, runtime và lệnh cài/build/chạy thế nào.

Các lệnh khác

Lệnh	Việc
`zo status`	URL, số bản chạy ổn, 5 lần deploy gần nhất (kèm lỗi)
`zo open`	in địa chỉ của service
`zo logs`	log gần đây (`-since 1h`, `-n 200`)
`zo logs -f`	theo dõi log trực tiếp (Ctrl+C để dừng)
`zo vars`	liệt kê biến
`zo vars set KEY=value KEY2=value2`	đặt biến (có hiệu lực từ lần deploy sau)
`zo vars unset KEY`	xoá biến
`zo db` / `zo db list`	database của project
`zo db create pg -engine postgres`	tạo database (`postgres`, `mysql`, `valkey`); in biến tham chiếu cần dùng
`zo db vars pg`	thông tin kết nối đầy đủ
`zo domains`	tên miền của service
`zo domains add www.example.vn`	gắn tên miền; in bản ghi CNAME cần tạo
`zo domains remove www.example.vn`	gỡ tên miền
`zo scale 2`	đổi số bản chạy
`zo rollback 7`	quay lại deploy #7 (không build lại)

Ví dụ thêm PostgreSQL cho app:

zo db create pg -engine postgres
zo vars set 'DATABASE_URL=${{pg.DATABASE_URL}}'
zo deploy

(Dùng dấu nháy đơn để shell không hiểu ${{…}} là biến của shell.)

Dùng trong CI

# GitHub Actions
- run: curl -fsSL https://app.zocloud.io/install.sh | sh
- run: zo deploy -to myorg/shop/web
  env:
    ZOCLOUD_TOKEN: ${{ secrets.ZOCLOUD_TOKEN }}

Nếu repo đã kết nối qua GitHub App, bạn không cần CI để deploy: mỗi lần push là tự deploy.

Kết nối ChatGPT

ChatGPT (và Claude.ai, hay agent nào hỗ trợ MCP từ xa) kết nối thẳng với ZoCloud, không cần cài zo: bạn nhờ ChatGPT viết app rồi bảo "deploy lên ZoCloud", ChatGPT gửi code lên và trả về link https://…zocloud.app.

Trong ChatGPT: Settings → Apps & Connectors → Advanced settings, bật Developer mode (gói có hỗ trợ connector).
Create (tạo connector): tên ZoCloud, MCP server URL https://app.zocloud.io/mcp, Authentication OAuth.
ChatGPT mở trang ZoCloud: đăng nhập (nếu chưa), xem ChatGPT được làm gì, bấm Cho phép.
Trong cuộc trò chuyện, chọn connector ZoCloud rồi nhờ: "Viết trang giới thiệu quán cà phê và deploy lên ZoCloud vào myorg/cafe/web."

Claude.ai: Settings → Connectors → Add custom connector, URL như trên.

ChatGPT làm việc với quyền của bạn trong các tổ chức (như một token). Nó không thấy mật khẩu và không mua gì: xem giá tên miền được, còn mua thì trong portal hoặc qua zo mcp. Kết nối hiện trong Tài khoản → Token truy cập với tên ứng dụng; xoá ở đó là ngắt ngay.

Cách deploy từ ChatGPT:

Code ChatGPT viết: deploy_files gửi toàn bộ file của app (tối đa 8 MB, 2.000 file; mỗi lần deploy là đúng các file đó). ZoCloud tự nhận Node.js, Python, Go, PHP hay HTML tĩnh như khi deploy thư mục.
Repo Git, image, template: deploy_repo, deploy_image, deploy_template.
Build lâu hơn khoảng 90 giây thì ChatGPT nhận "đang build" và theo dõi tiếp bằng wait_deployment.

MCP server cho AI agent

zo mcp chạy một MCP server (stdio) để Claude, Cursor hay agent AI khác tự deploy, xem log, quản lý database, tên miền và AI key. Agent chỉ làm được những gì token của bạn được phép (theo vai trò).

Nên tạo một token riêng cho agent, đặt số ngày hiệu lực ngắn, và thu hồi khi không dùng.

Claude Code

claude mcp add zocloud -e ZOCLOUD_TOKEN=zc_pat_… -- zo mcp

Cursor và các agent khác

Thêm vào file cấu hình MCP (ví dụ .cursor/mcp.json hoặc cấu hình mcpServers của Claude Desktop):

{
  "mcpServers": {
    "zocloud": {
      "command": "zo",
      "args": ["mcp"],
      "env": { "ZOCLOUD_TOKEN": "zc_pat_…" }
    }
  }
}

Nếu agent không tìm thấy zo, dùng đường dẫn đầy đủ (kết quả của which zo).

Danh sách công cụ

Các công cụ nhận target dạng tổ-chức/project/service, hoặc org cho công cụ của tổ chức.

Nhóm	Công cụ	Việc
Tài khoản	`whoami`	người dùng, tổ chức, vai trò, đã được duyệt deploy chưa
Deploy	`detect`	ZoCloud sẽ build thư mục thế nào (chỉ `zo mcp`)
	`deploy_folder`	tải thư mục lên và deploy (không gửi `.env`), chờ build, trả URL hoặc lỗi (chỉ `zo mcp`)
	`deploy_files`	deploy các file gửi kèm (code agent vừa viết), tối đa 8 MB
	`wait_deployment`	theo dõi tiếp một deploy đang build
	`deploy_repo`	deploy repo Git công khai qua https
	`deploy_image`	deploy Docker image công khai
	`list_templates`, `deploy_template`	liệt kê và deploy template một-click
Vận hành	`status`	URL, số bản chạy ổn, deploy gần đây
	`logs`	output gần đây của container
	`set_variables`	đặt/xoá biến (giá trị rỗng là xoá), hỗ trợ `${{tên.DATABASE_URL}}`
	`scale`	số bản chạy (0–20)
	`rollback`	quay lại một deploy cũ
	`add_volume`	thêm volume tại một đường dẫn
	`set_cron`, `run_cron`	biến service thành cron job; chạy ngay và lấy kết quả
Database	`create_database`	tạo `postgres`, `mysql`, `valkey`; trả biến tham chiếu
	`database_public`	mở/đóng truy cập từ Internet (TLS)
Tên miền	`add_domain`	gắn tên miền riêng vào service, trả bản ghi DNS cần tạo
	`check_domain`	tên miền còn trống không và giá (gồm VAT)
	`buy_domain`	mua bằng ví: chỉ sau `check_domain`, cần đúng giá đã đồng ý (`confirm_price_vnd`)
	`list_domains`	tên miền đã mua, trạng thái, ngày hết hạn
	`dns_records`, `set_dns_record`, `remove_dns_record`	đọc và sửa bản ghi trên ZoCloud DNS
AI	`ai_models`	model của AI gateway và giá
	`create_ai_key`	tạo key AI (chỉ hiện một lần; agent nên đặt vào biến bằng `set_variables`)
	`ai_usage`	sử dụng AI theo ngày

buy_domain tiêu tiền thật: agent phải hỏi bạn giá trước, và nếu giá đã đổi thì không mua gì.

Ví dụ yêu cầu cho agent

"Deploy thư mục này lên ZoCloud vào myorg/shop/web, thêm PostgreSQL và gắn DATABASE_URL."
"Xem log của myorg/shop/web và sửa lỗi khiến app không khởi động."
"Kiểm tra shopcuatoi.vn còn trống không và báo giá 1 năm."