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
- Create a token in the portal: Account → Access tokens → Create token (see Organisations, members and account security).
- 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,.zocloudignoreand.dockerignore. It never uploads.env*files (except.env.example): set variables withzo vars. - zo prints the build log, the status, and the HTTPS address when it is done.
- Before deploying,
zo detectshows 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.
- In ChatGPT: Settings → Apps & Connectors → Advanced settings, turn on Developer mode (on plans that support connectors).
- Create a connector: name
ZoCloud, MCP server URLhttps://app.zocloud.io/mcp, Authentication OAuth. - ChatGPT opens a ZoCloud page: sign in (if you are not yet), see what ChatGPT may do, click Allow.
- 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_filesuploads 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 upDATABASE_URL." - "Read the logs of
myorg/shop/weband fix the error that keeps the app from starting." - "Check whether
shopcuatoi.vnis available and quote the price for 1 year."