OpenCode + xCloud

Install one-click apps with OpenCode on xCloud

Installing one-click apps with OpenCode means asking the terminal agent to find an app in the xCloud catalogue, check that your server can run it, install it after you approve and hand back the address, without opening the dashboard.

Skill: xcloud:deploy
Toolsets: oneclick-apps, catalog, servers
Free with every xCloud account

Set up OpenCode All OpenCode guides

YouInstall Uptime Kuma on the Frankfurt server, staging hostname. Check the fit first.

xcloud_oneclickApps_compatibilityread-only

AgentStack and runtime match, the server is running and billing is fine. Monitoring data is missing, so the RAM, CPU and disk check was skipped: inconclusive. Install Uptime Kuma on a staging hostname anyway?

YouYes.

xcloud_oneclickApps_installneeds approval

AgentInstalling. pre_install done, install done, post_install done, provisioning done. It is ready on your staging hostname. Want the login details?

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 Install one-click apps 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

Search the xCloud one-click catalogue for a self-hosted blog. List each result with what it needs from a server.

In practice

How Does One-click apps Work from OpenCode?

OpenCode runs in the shell you already have open, so an install request is one line typed between two other commands. Because OpenCode prefixes every MCP tool with the server name, the calls appear in the session as xcloud_oneclickApps_index, xcloud_oneclickApps_compatibility and xcloud_oneclickApps_install, and you can see at a glance which step the agent is on. Ask for a self-hosted blog and OpenCode searches the catalogue, lists the matches with what each one needs from a server, and waits for you to pick. Your current repository does not matter for this job: an app from the catalogue is installed on a server, not built from the code in your working directory.

The server check is where the terminal earns its keep. You name a server, or OpenCode lists yours with servers_index and asks, and it runs the compatibility check for the app you chose. The reply is a short block: stack, runtime, server state, billing and the RAM, CPU and disk verdict. When xCloud has no recent monitoring reading for that server, the agent says the resource check was skipped rather than passed, and you decide whether to go on. After your yes, the install call carries an explicit confirmation and an idempotency key, so if the session drops and you ask again, the retried request does not create a second copy. Then OpenCode polls oneclickApps_status and prints a line each time the phase changes, from pre_install through provisioning, until the install is terminal.

Two OpenCode settings shape how smooth this feels. The first is tool scope. A one-click install needs only the catalogue, the install tools and the server list, so a connection that loads the toolsets oneclick-apps, catalog and servers keeps the model's context small. The second is which agent sees xCloud at all. OpenCode lets you switch a server's tools off globally and turn them on for one agent, so an operations agent can install and stop apps while your everyday coding agent never sees the install tools. When the app is up, OpenCode gives you the URL and fetches the login details only if you ask, then shows them once.

OpenCode specific: A long install makes OpenCode call the status tool many times, and each result lands in your context. If your permission setup asks before every MCP call, allow the read tools by pattern and leave the install and lifecycle tools on ask. If you used an xcloud* wildcard to allow everything, remember it also covers stop and redeploy, which take an app offline or recreate its containers. xCloud still asks for confirmation, but OpenCode will no longer be your first check.

What xCloud does for one-click apps

xCloud lists the one-click catalogue, checks whether an app fits a given server, installs it once you approve and reports each install phase until it finishes. Afterwards the agent can fetch the login details and stop, start or redeploy the app. A few apps install only from the dashboard, and the agent tells you where to click.

Find the app. The agent searches the catalogue by name or purpose and shows what it found. An empty catalogue means the list has not synced on that environment, so the agent never answers that an app does not exist from an empty list.
Read the install form. The agent reads the app's fields. Fields xCloud generates for you can be left out. For the address you choose a free xCloud staging hostname or your own domain, and a live domain needs the full site name.
Check the server fits. You name the server, or the agent lists yours and asks. The compatibility check covers the server stack, runtime, state, billing and RAM, CPU and disk against the latest monitoring snapshot. If monitoring data is missing the resource check was skipped, and the agent says the result is inconclusive.
Approve and install. The agent restates the app, the server and the address, and asks once. On your yes it sends the install with an explicit confirmation and an idempotency key, so a retried request cannot create a second copy.
Poll the install. The agent polls the install status every five to ten seconds until it is terminal. A failure names its phase: pre_install, install, post_install or provisioning, so you know where it stopped.
Hand over and manage. The agent gives you the URL. It fetches the login details only when you ask, shows them once in the reply and tells you to store them in a password manager. Later it can stop, start, restart or redeploy the app after your approval.

Reference

One-click apps Settings and Limits on xCloud

The facts OpenCode works within when it installs one-click apps. Where a row names the dashboard, that step stays yours to take there.

Setting or limit	What applies
Catalogue	Searchable by name. It holds hundreds of apps, and most run on a Docker server. Public facts such as supported stacks and minimum size come from the catalogue listing
Compatibility check	Per server: stack, runtime, server state, billing and RAM, CPU and disk. monitor_available set to false means the resource check was skipped, not passed
Too-small servers	A server that is too small stays too small. The agent suggests a larger server instead of retrying the install
Stack requirements	An app that needs another stack is refused with a 422 that reads "This app requires a ... server. This server is on the ... stack."
Dashboard-only installs	n8n, Supabase, Nextcloud, Mautic, LibreChat, Open WebUI, Ollama, Umami, WireGuard, phpMyAdmin and Site.pro. The API answers 404 for these eleven; install them from Add site, One-Click Apps in the dashboard
Address	Staging hostname for a free xCloud address, or go live with your own domain. A demo site promoted to a live domain cannot return to the demo address
Idempotency	The install carries an Idempotency-Key, so a retried request cannot create a duplicate site
Install phases	pre_install, install, post_install and provisioning. is_terminal marks the end, and failed_phase says where a failure happened
Credentials	Read on request and shown once in the reply. Some apps have none to read because you create the first admin inside the app
Lifecycle	Stop, start, restart and redeploy run synchronously. Stop takes the app offline and redeploy recreates its containers. Both answer 422 while an install is running or after a failed install
Agentic servers	An OpenClaw, Hermes, Paperclip or DeepSeek Harness server never takes a one-click app

Rules OpenCode has to follow

Installing, stopping and redeploying an app stop for your approval; browsing the catalogue and the compatibility check never change anything.
A missing resource reading is reported as inconclusive, never as a pass.
Login details are shown once, only when you ask, and never repeated in a summary or a later message.
For the eleven dashboard-only apps the agent checks that the server fits, then gives you the dashboard path instead of trying the install.
A failed install is not retried blindly: the agent names the failed phase and reads the site's recent events first.

Example prompts

What Can You Ask OpenCode to Do for One-click apps?

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

Search the xCloud one-click catalogue for a self-hosted blog. List each result with what it needs from a server.

Prompt

Install Uptime Kuma on the Frankfurt server on a staging hostname. Check the fit first and wait for my yes.

Prompt

Is the Ghost app on blog.example.com running? If the last install failed, tell me which phase and read the recent events.

Prompt

Which one-click apps are compatible with my Frankfurt server?

Prompt

Search the one-click catalogue for a self-hosted blog and tell me what each result needs from a server.

Prompt

Install Uptime Kuma on the Frankfurt server on a staging hostname, wait until it is ready, then give me the login details.

Prompt

Check whether Immich fits my Amsterdam server before I install it, and tell me if the resource check was inconclusive.

Prompt

I want n8n on my Frankfurt server. Check that the server fits, then tell me where to click to install it.

Prompt

The Uptime Kuma install on the Frankfurt server failed. Which phase failed, and what do the recent events say?

Prompt

Redeploy the Ghost app on blog.example.com, but tell me what a redeploy does before you run it.

OpenCode and One-click apps: Frequently Asked Questions

What people ask before they let OpenCode install one-click apps through xCloud.

Why do the xCloud tools show an xcloud_ prefix in OpenCode?

OpenCode adds the server name in front of every MCP tool, so oneclickApps_install appears as xcloud_oneclickApps_install. The same prefix lets you allow or deny the whole set with one pattern. For an install, allow the read tools and keep the install and lifecycle tools on ask.

Can I keep xCloud away from my everyday OpenCode agent and still install apps?

Yes. Switch the xcloud tools off globally and turn them on for one agent you use for operations. That agent can search the catalogue, check fit and install, while your coding agent never sees the install tools.

Can an agent install any app in the one-click catalogue?

Most of them. Eleven apps install only from the dashboard: n8n, Supabase, Nextcloud, Mautic, LibreChat, Open WebUI, Ollama, Umami, WireGuard, phpMyAdmin and Site.pro. For those the agent checks that your server fits and points you to Add site, One-Click Apps.

How does the agent know an app will fit my server?

It runs the compatibility check for that server, which covers the stack, runtime, server state, billing and the RAM, CPU and disk readings from the latest monitoring snapshot. If monitoring data is missing, the agent tells you the resource check was inconclusive.

What does a 422 during an app install mean?

Usually that the app needs a different server stack than the one you picked, and the message names both. Pick a server on the required stack. A 422 on stop, start or redeploy means an install is still running or the last install failed.

Where do the login details for a one-click app come from?

The agent can read them from xCloud when you ask and shows them once in the reply. Store them in a password manager. Some apps have no generated login because you create the first administrator inside the app.

Can an agent stop or restart a one-click app?

Yes. Stop, start, restart and redeploy are available, and they run straight away once you approve. Stop takes the app offline and redeploy recreates its containers, so the agent asks before either.

Other agents