OpenCode + xCloud

Deploy from Git with OpenCode on xCloud

Deploying from Git with OpenCode means asking the open-source terminal agent to ship the repository in your working directory, and letting xCloud detect the app, preview the site, create it after your approval and verify the live URL.

Skill: xcloud:deploy
Toolsets: sites, servers, integrations
Free with every xCloud account

Set up OpenCode All OpenCode guides

YouDeploy this repo to Frankfurt on a staging hostname. Dry run first.

xcloud_git_detectread-only

AgentNode.js 20 app on main. Build: npm run build, start: npm start. Suggested URL api-staging.acme.xcloud.site. Warning: no .env in the repo, so I will pass environment values at create time. Create it?

YouYes.

xcloud_servers_sites_git_autoneeds approval

AgentQueued, building, issuing SSL... deployed. https://api-staging.acme.xcloud.site answers 200 and failed_steps is empty.

Last updated: October 2026. Keep a human in the loop: xCloud stops and asks before anything that creates, deploys, updates, reboots, deletes or buys.

Setup

How Do You Set Up OpenCode to Deploy from Git on xCloud?

Connect OpenCode once; every job on this account uses the same connection. Then ask in plain words.

1
Add the xCloud MCP server
Run this from the project that should use xCloud, or add --global to make it available everywhere. OpenCode writes the entry under mcp.servers in its config (OpenCode v2 no longer accepts server names directly under mcp). Remote servers use OAuth by default, so there is nothing else to fill in; the equivalent hand-written entry is shown below.
Terminal
```
opencode mcp add xcloud --url https://app.xcloud.host/mcp

# the entry it writes to opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "xcloud": {
        "type": "remote",
        "url": "https://app.xcloud.host/mcp"
      }
    }
  }
}
```
2
Sign in with OAuth
This opens your browser on the xCloud approval screen, where you tick the teams and choose Read-only or Full access. Inside OpenCode, /mcps does the same: pick xcloud and sign in. Then opencode mcp list should show xcloud as connected.
Terminal
```
opencode mcp auth xcloud
opencode mcp list
```
3
No browser? Use an API key
For a headless or CI machine, create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things in Settings, Developers, API Tokens and export it as XCLOUD_TOKEN. Setting oauth to false turns off the automatic sign-in, and the {env:XCLOUD_TOKEN} reference keeps the token out of the file. The entry still lives under mcp.servers.
JSON
```
{
  "mcp": {
    "servers": {
      "xcloud": {
        "type": "remote",
        "url": "https://app.xcloud.host/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:XCLOUD_TOKEN}"
        }
      }
    }
  }
}
```

Check it worked

Then ask OpenCode for the job itself, for example:

Prompt

Deploy this repo to my Frankfurt server on a staging hostname. Dry run first, then wait for my yes.

In practice

How Does Deploy from Git Work from OpenCode?

OpenCode runs in the terminal inside your project, so the repository is already around you. When you type deploy this to my Frankfurt server, it can read the remote URL and the branch from the checkout and hand them to xCloud instead of asking you to paste an address. Every tool the xcloud server offers shows up with the server name as a prefix, so the calls in your session read xcloud_git_detect, xcloud_servers_sites_git_auto and xcloud_sites_status. The prefix is more than cosmetic. It is the handle you use in OpenCode's tool permissions, where a pattern such as xcloud* allows or denies the whole set at once, and where you can switch the tools off globally and turn them on for a single agent.

That per-agent switch suits a deploy well. Keep xcloud out of the agent you use for everyday edits, set up a second agent for operations, and enable the xcloud tools only there. Asking the operations agent to deploy then has a clear shape. It runs detection and reports the app type, branch, commands and warnings in a few lines, asks xCloud for a free staging hostname unless you named a domain, and prints the dry run before anything exists. You answer yes once. It sends the confirmed create call, polls the site status and prints one line per real step change, then fetches the URL and reads failed_steps before it says the site is live. Watch the context cost: the full server offers 188 operations, and a deploy needs only the sites, servers and integrations toolsets, so connect with ?toolsets=sites,servers,integrations and keep the model's tool list short.

A terminal agent is also a good place to deal with a failed build, because the repository is on disk. When the diagnosis names a missing environment variable or a wrong build command, OpenCode can show you the line in package.json or composer.json that disagrees with what xCloud suggested, you decide which side should change, and the retry goes to the same site after you approve. Secrets belong in the environment values you pass to xCloud, not in a file you commit, because every deploy resets the site directory to what Git holds.

OpenCode specific: The agent switch and the tool prefix are both easy to trip over. If you enabled the xcloud tools for one agent only and start a deploy from a different one, that agent will not see them, so check which agent is active before you ask. The sign-in saved by opencode mcp auth xcloud belongs to your user account, not to the repository, so a deploy started on a headless machine needs the API-key form of the entry. And creating the site always stops for your confirmation, whatever allow pattern you wrote for xcloud*, because xCloud refuses the create call without it.

What xCloud does for deploy from git

xCloud detects the app in the repository, previews the site it would create with a dry run, creates it once you approve, polls the deployment to a terminal state and checks the live URL. A failed deploy gets a diagnosis and a corrected retry on the same site, never a delete and recreate.

Pick the team and server. The agent uses the server you name. If you name none it lists provisioned servers and asks; it never picks one silently. Node.js, PHP and static builds need an Nginx or OpenLiteSpeed server; anything else needs a Docker server.
Detect the repository. git_detect reads the default branch, the app type (WordPress, Laravel, custom PHP, Node.js or Lovable), the web root, suggested install, build and start commands, repository access and server compatibility. Detection creates nothing.
Choose the address. With no domain the agent asks xCloud for a free staging hostname. With a live domain it checks whether the zone is on a connected Cloudflare account, in which case xCloud writes the DNS record and certificate itself.
Dry run, then one approval. The agent sends the create request with dry_run set to true and shows you the resolved configuration: app type, URL, branch, commands, runtime version and every warning. Then it asks once, naming the server and the URL, before sending the same body with confirm set to true and an idempotency key.
Poll and verify. A 202 means queued, not deployed. The agent polls the site status until it is terminal, reports each real step change, reads failed_steps and the SSL block, and fetches the URL before it calls the site live.
Recover if it fails. On a failed deploy the agent reads the deployment diagnosis, proposes a fix from the correctable fields, and retries on the same site with your approval. Two failed retries with the same classification stop the loop and hand you the dashboard link.

Reference

Deploy from Git Settings and Limits on xCloud

The facts OpenCode works within when it deploys from Git. Where a row names the dashboard, that step stays yours to take there.

Setting or limit	What applies
Supported app types	WordPress, Laravel, custom PHP, Node.js and Lovable on native servers; Dockerfile and Compose apps, including Python, Go and Rust, on Docker servers
Repository sources	Public HTTPS URLs, repositories on a connected GitHub, GitLab or Bitbucket provider, and private SSH repositories with a read-only deploy key
Private repositories	The agent prepares a deploy key on the server, you add the public key to the repository, xCloud verifies it. A private key or personal token never goes in the request
Preview	dry_run: true returns the would_create block and consumes no idempotency key
Idempotency	The create call carries an Idempotency-Key, so a retried request cannot create a duplicate site. A new deployment needs a new key
Deployment states	deployed, failed or cancelled once terminal is true; failed_steps can be non-empty on a deployed site and must be read
Node.js versions	The Node version is server-wide, not per site; changing it can affect other apps on the server
Redeploys	A redeploy runs git reset --hard and git clean -df in the site directory, so uncommitted server-side changes are lost. Supply environment values through env_file_content, not files in the checkout
Staging environments	Available for Git sites on paid plans through the API; WordPress staging stays a dashboard step
Agentic servers	An OpenClaw, Hermes, Paperclip or DeepSeek Harness server hosts only the site created at provisioning; a second site is refused

Rules OpenCode has to follow

Creating a site is billable and stops for your approval; detection and the dry run never create anything.
The agent explains every detection warning before asking, and a repository access problem is never worked around by naming an app type by hand.
A deployed state is not proof the application works: the agent fetches the URL and reads failed_steps first.
A failed site is retried in place with corrections; it is never deleted and recreated to retry.
Changing a live site's domain after creation, databases and server resizing are dashboard steps; the agent gives you the path and the dashboard link xCloud returned.

Example prompts

What Can You Ask OpenCode to Do for Deploy from Git?

Type these as written and swap in your own repository, site and server names. Reads and routine actions such as backups, cache purges, PageSpeed scans and vulnerability scans run straight away; creating, deploying, updating, rebooting, deleting, buying or starting a broken-link scan stops and asks first.

Prompt

Deploy this repo to my Frankfurt server on a staging hostname. Dry run first, then wait for my yes.

Prompt

Run xcloud detection on this repo and tell me the build and start commands it would use. Create nothing.

Prompt

The last deploy failed. Read the diagnosis, point me at the file that needs changing and retry on the same site.

Prompt

Deploy https://github.com/acme/shop to my Frankfurt server and show me the dry run before creating anything.

Prompt

Deploy the private GitLab repository connected to my team on a staging hostname.

Prompt

Scan the docker-compose.yml in github.com/acme/api and tell me which services and ports xCloud would use.

Prompt

Create a staging environment from the feature/checkout branch of the API site.

Prompt

Deploy the latest commit of the shop site after showing me what will change.

Prompt

The last deploy of the API site failed. Diagnose it, fix the build command and retry on the same site.

OpenCode and Deploy from Git: Frequently Asked Questions

What people ask before they let OpenCode deploy from Git through xCloud.

Does OpenCode need the repository URL to deploy to xCloud?

Not when you start it inside the checkout. It can read the Git remote and the branch from the working directory, then pass them to xCloud's detection. You still name the server, or let it list your provisioned servers and ask, and you approve the dry run before anything is created.

How do I keep the xCloud tools out of OpenCode's everyday agent?

Turn the xcloud tools off globally in the OpenCode config, then enable them for one agent you use for operations. The tools carry the xcloud_ prefix, so a single pattern such as xcloud* covers the whole set. Deploys then only happen when you choose that agent.

Does the agent create the site as soon as I give it a repository URL?

No. It detects the repository and runs a dry run first, shows you the resolved configuration, and asks once. Only after you approve does it send the create call with an explicit confirmation and an idempotency key.

Can an agent deploy a private repository through xCloud?

Yes. Either the repository is on a Git provider connected to your xCloud team, or the agent prepares an SSH deploy key on the server for you to add to the repository. A private key or a personal access token is never sent in the request.

What does a 202 response mean during a deploy?

That xCloud queued the deployment. The agent polls the site status until it is terminal and reports deployed, failed or cancelled, then checks failed_steps and fetches the URL before calling the site live.

What happens when a deploy fails?

The agent reads the deployment diagnosis, which classifies the failing step and quotes the relevant log lines, proposes a fix from the fields xCloud lets it correct, and retries on the same site after your approval. It never deletes and recreates the site to retry.

Which servers can take a Git deploy?

Node.js, PHP and static builds deploy to Nginx or OpenLiteSpeed servers. Dockerfile and Compose apps, and other language stacks, need a Docker server. Agentic servers running OpenClaw, Hermes, Paperclip or DeepSeek Harness take no additional sites.

Other agents