ZoCloud User Guide Tiếng Việt Open ZoCloud

zo CLI and MCP server

zo deploys a folder or a Git repository, follows builds and logs, sets variables, adds databases and domains, from a terminal, CI or an AI agent. It runs on macOS, Linux and Windows.

Installation

macOS, Linux:

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

Windows: download zo.exe under Account → Deploy from your machine (the "Windows: download zo.exe" link).

Check it: zo version.

Signing in

  1. Create a token in the portal: Account → Access tokens → Create token (see Organisations, members and account security).
  2. Run:
zo login              # paste the token when asked
zo login -token zc_pat_…
zo whoami             # e-mail, organisations and roles
zo logout

The token is saved in ~/.config/zocloud/config.json (mode 600). In CI or an agent, set the ZOCLOUD_TOKEN environment variable instead of signing in.

Language: zo lang vi or zo lang en (the system's by default).

Linking a folder to a service

A service is written as organisation/project/service; add @environment (or -env NAME) for an environment other than production.

zo link myorg/shop/web
zo link myorg/shop/web@staging        # or: zo link -env staging myorg/shop/web

This writes a .zocloud.json file in the folder (not the zocloud.json build configuration). The commands status, logs, vars, env, db, buckets, domains, scale, rollback and open use the service (and environment) linked to the current folder (or a parent).

Deploying

zo deploy -to myorg/shop/web     # first time: link and deploy
zo deploy                        # from then on
zo deploy ./apps/api             # deploy another folder
zo deploy -env staging           # this once, deploy to the staging environment (the folder stays linked as it was)
zo deploy -detach                # do not wait for the build
  • The project and the service are created automatically when they do not exist yet.
  • zo packs the folder and uploads it; it skips .git, node_modules, .venv, venv, __pycache__… and the patterns in .gitignore, .zocloudignore and .dockerignore. It never uploads .env* files (except .env.example): set variables with zo vars.
  • zo prints the build log, the status, and the HTTPS address when it is done.
  • Before deploying, zo detect shows how ZoCloud will recognise the framework, the runtime and the install/build/start commands.

Other commands

Command What it does
zo status URL, healthy instances, the 5 latest deployments (with errors)
zo open prints the service's address
zo logs recent logs (-since 1h, -n 200)
zo logs -f follows the logs live (Ctrl+C to stop)
zo logs -q "connection refused" only the lines containing that text (search the last 7 days with -since 7d)
zo logs -stream http -status 5xx the router's request log (-stream http), 5xx errors only (`-status 2xx
zo vars lists the variables
zo vars set KEY=value KEY2=value2 sets variables (they apply from the next deployment)
zo vars unset KEY removes a variable
zo env the project's environments (* marks the linked one)
zo env create staging -from production -branch develop -fresh-db creates an environment: a copy of the services, variables and volumes of -from (default production), building the -branch branch (leave it out to keep each service's own); -fresh-db gives it empty databases like the source's
zo env delete staging deletes an environment with its services and its own databases
zo db / zo db list the databases of the linked environment
zo db create pg -engine postgres creates a database (postgres, mysql, valkey); prints the reference variable to use
zo db vars pg the full connection details
zo db backups pg the backups (time, kind, status, size)
zo db backup pg backs up now
zo buckets the S3 buckets of the linked environment
zo buckets create files -quota-gb 5 creates a bucket (size limit; the plan's by default); prints how to attach it to a service
zo buckets creds files endpoint, access key, secret key (the S3_* variables)
zo buckets delete files deletes a bucket with its files
zo domains the service's domains
zo domains add www.example.vn attaches a domain; prints the CNAME record to create
zo domains remove www.example.vn detaches a domain
zo scale 2 changes the number of instances
zo rollback 7 goes back to deployment #7 (without rebuilding)

Example: adding PostgreSQL to an app.

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

(Use single quotes so the shell does not read ${{…}} as a shell variable.)

In 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 }}

If the repository is connected through the GitHub App, you do not need CI to deploy: every push deploys by itself.

Connecting ChatGPT

ChatGPT (and Claude.ai, or any agent that supports remote MCP) connects to ZoCloud directly, without installing zo: you ask ChatGPT to write an app and tell it to "deploy it to ZoCloud"; ChatGPT uploads the code and gives you back a https://…zocloud.app link.

  1. In ChatGPT: Settings → Apps & Connectors → Advanced settings, turn on Developer mode (on plans that support connectors).
  2. Create a connector: name ZoCloud, MCP server URL https://app.zocloud.io/mcp, Authentication OAuth.
  3. ChatGPT opens a ZoCloud page: sign in (if you are not yet), see what ChatGPT may do, click Allow.
  4. In a conversation, pick the ZoCloud connector and ask: "Write a landing page for a coffee shop and deploy it to ZoCloud at myorg/cafe/web."

Claude.ai: Settings → Connectors → Add custom connector, with the URL above.

ChatGPT acts with your rights in your organisations (like a token). It does not see your password and buys nothing: it can look up a domain's price, but buying is done in the portal or through zo mcp. The connection shows under Account → Access tokens with the application's name; deleting it there disconnects at once.

How ChatGPT deploys:

  • Code ChatGPT wrote: deploy_files uploads the app's files (at most 8 MB, 2,000 files; each deployment is exactly those files). ZoCloud recognises Node.js, Python, Go, PHP or static HTML as it does for an uploaded folder.
  • A Git repository, an image, a template: deploy_repo, deploy_image, deploy_template.
  • When a build takes longer than about 90 seconds, ChatGPT gets "still building" and follows it with wait_deployment.

MCP server for AI agents

zo mcp runs an MCP server (stdio) so that Claude, Cursor or another AI agent deploys, reads logs and manages databases, domains and AI keys by itself. The agent can only do what your token allows (by role).

Create a separate token for the agent, give it a short validity in days, and revoke it when it is no longer used.

Claude Code

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

Cursor and other agents

Add this to the MCP configuration file (for example .cursor/mcp.json, or Claude Desktop's mcpServers configuration):

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

If the agent cannot find zo, use the full path (the output of which zo).

The tools

The tools take a target of the form organisation/project/service (add @environment for an environment other than production, e.g. myorg/shop/web@staging), or org (and project) for the organisation's tools.

Group Tool What it does
Account whoami the user, organisations, roles, and whether they are approved to deploy
Deploy detect how ZoCloud would build a folder (zo mcp only)
deploy_folder uploads a folder and deploys it (never .env), waits for the build, returns the URL or the error (zo mcp only)
deploy_files deploys the files passed along (code the agent just wrote), at most 8 MB
wait_deployment keeps following a deployment that is still building
deploy_repo deploys a public Git repository over https
deploy_image deploys a public Docker image
list_templates, deploy_template lists and deploys one-click templates
Operations status URL, healthy instances, recent deployments
logs the containers' recent output; filtered by a text (text), a stream (app, http, waf) and a status class (status: 4xx, 5xx)
set_variables sets/removes variables (an empty value removes), supports ${{name.DATABASE_URL}}
scale the number of instances (0–20)
rollback goes back to an earlier deployment
add_volume adds a volume at a path
set_cron, run_cron makes a service a cron job; runs it now and returns the result
Environments list_environments the project's environments, their services and addresses
create_environment creates an environment (staging…) copied from another, building its own branch, with empty databases if asked (fresh_databases)
Databases create_database creates postgres, mysql, valkey; returns the reference variable
database_public opens/closes access from the internet (TLS)
Storage create_bucket creates an S3 bucket in an environment; returns the S3_* variables to set on the service
Domains add_domain attaches your own domain to a service, returns the DNS records to create
check_domain whether a domain is available and its price (VAT included)
buy_domain buys with the wallet: only after check_domain, with the exact price agreed to (confirm_price_vnd)
list_domains the domains bought, their status and expiry date
dns_records, set_dns_record, remove_dns_record reads and edits records on ZoCloud DNS
AI ai_models the AI gateway's models and prices
create_ai_key creates an AI key (shown once; the agent should put it in a variable with set_variables)
ai_usage AI usage by day

buy_domain spends real money: the agent must ask you about the price first, and if the price has changed it buys nothing.

Example requests for an agent

  • "Deploy this folder to ZoCloud at myorg/shop/web, add PostgreSQL and wire up DATABASE_URL."
  • "Read the logs of myorg/shop/web and fix the error that keeps the app from starting."
  • "Check whether shopcuatoi.vn is available and quote the price for 1 year."