Book a demo
Book a demo
Login

OpenCode + xCloud

Manage servers with OpenCode on xCloud

Managing servers with OpenCode means asking the open-source terminal agent to read your xCloud servers, change their services, runtimes and security rules after your approval, and report the real result instead of the acceptance.

  • Skill: xcloud:servers
  • Toolsets: servers, alerts, user
  • Free with every xCloud account
Set up OpenCodeAll OpenCode guides

YouSwitch the Frankfurt server's default Node.js to 22.

xcloud_servers_node-versions_indexread-only

Agentfrankfurt-1 has Node 20 and 22 installed, and 20 is the default. The default is server-wide, so every Node site on this server is affected. Set 22 as the default?

YouYes.

xcloud_servers_node-versions_defaultneeds approval

AgentAccepted. I read the task list until it settled: the default on frankfurt-1 is now Node 22.

. 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 Manage servers 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}"
        }
      }
    }
  }
}

  4. Check it worked

    Then ask OpenCode for the job itself, for example:

    Prompt
    List my servers with CPU, RAM and disk. Flag anything above 80% disk.

In practice

How Does Server management Work from OpenCode?

OpenCode is already open in a terminal pane next to your code, which turns server work into a one-line request instead of a trip to the dashboard. OpenCode prefixes every MCP tool with the server name, so the xCloud tools appear as xcloud_servers_index, xcloud_servers_monitoring, xcloud_servers_services_restart and so on, and the tool-call log shows exactly which one the model picked. A typical first request is a fleet check: list my servers and flag any above 80% disk. OpenCode calls the inventory tool, reads the monitoring figures for each server and answers with one line per server. A status such as Low disk space or Reboot Required gets its own mention, and on a free plan a monitoring history read comes back as a plan limit, not as a permission error you have to decode.

Changes follow the same rhythm as a code change you are reviewing. Ask for Redis on the Frankfurt server and OpenCode reads the installed services first, restates which server it is about to touch, then installs and enables the service. xCloud accepts that work and returns before it finishes, so OpenCode reads the server's task list until the task settles and only then tells you Redis is running. Switching the default Node.js version, adding a firewall rule, banning or unbanning an address in Fail2Ban and creating a server cron job all work the same way. Each time the model states the impact before it asks, for example that a Node.js default is server-wide and affects every Node site on that server. A reboot gets the strictest treatment: OpenCode starts the tracked reboot and keeps reading the operation until xCloud reports a verified new boot.

One thing OpenCode adds to this job is control over which agent sees the tools. You can switch the xcloud tools off globally and turn them on for a single agent that you set up for operations, so the agent that edits your code never has a reboot tool in its list at all. Pair that with a scoped server URL, https://app.xcloud.host/mcp?toolsets=servers,alerts, and the operations agent carries only the server and alert tools, which keeps its context small and its reach narrow.

OpenCode specific: Because every xCloud tool carries the xcloud_ prefix in OpenCode, a permission pattern such as xcloud* matches the tools that only read and the tools that change a server alike. An allow rule for the whole set would also cover the tools that restart, disable and reboot, so allow the reads by name, such as xcloud_servers_index and xcloud_servers_monitoring, and keep everything that changes a server out of the rule. xCloud still stops for its own confirmation on a reboot, a runtime change or a purchase, but it is a second check and should not be the only one.

What xCloud does for server management

xCloud lets the agent list your servers, read their monitoring, and manage services, Node.js and PHP versions, cron jobs, firewall rules, Fail2Ban and sudo users. Changes that can interrupt a server stop for your approval, and a reboot is only reported as done after xCloud verifies a new boot.

  1. Pick the team and the server. The agent works on one team at a time and uses the server you name. If a name is missing or matches several servers, it lists them and asks. It always restates which server it is about to change before it changes it.
  2. Read the state first. It reads the server's status, installed services, runtimes and monitoring figures. A status such as low disk space or reboot required is worth surfacing on its own. Monitoring history is a paid-plan feature, so a free plan answers 403.
  3. Say what will change, then ask. For a service, runtime, cron, firewall or sudo change, the agent names the server, the item and the impact, for example that a Node.js default affects every Node site on the server. It waits for your approval when the change could interrupt a service.
  4. Follow the task to the end. xCloud accepts server work and returns before it finishes. The agent reads the server's task list until the task settles and reports the real outcome, not the acceptance.
  5. Reboot with proof. A reboot starts a tracked operation. The agent reads that operation until xCloud reports a verified new boot. If the result is unconfirmed it investigates and never repeats the reboot just to check.
  6. Buy a server only after approval. A new server is billable. The agent checks what you already have, reads the plans and the card on file, shows the plan, region and price, and waits for a yes. It sends the purchase once with an idempotency key so a retry cannot buy a second server.

Reference

Server management Settings and Limits on xCloud

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

Setting or limitWhat applies
InventoryEvery server on the team with its status, stack and the sites it hosts, plus the tasks, supervisor processes and site snapshots on a server
MonitoringCurrent CPU, memory and disk are readable. Monitoring history is a paid-plan feature: xCloud answers 403 on the free plan, which is a plan limit and not a permission
ServicesInstall, enable, restart and disable. A restart runs without a server-side prompt; the agent still confirms the exact server, service and impact before any service change, because disabling ssh, nginx or a database can lock you out or cause downtime
Node.js versionsRead the installed versions and set the default. The default is server-wide and affects every Node site on the server
PHP versionsInstall, uninstall, set the default, patch and toggle OPcache. The server default changes only the command-line php and the version new sites get; it does not change existing sites, and a single site's PHP version is a dashboard setting under Site > Site Settings
Cron jobsList, create, update, delete, run now and read the last output for server cron jobs. Site cron is a separate resource
Firewall rulesList, create, delete, enable and disable rules with a name, protocol, allow or deny, port and optional source IP
Fail2Ban and IP accessList, ban and unban IP addresses, read the SSH restriction status, and whitelist your current IP or xCloud's own IPs
Sudo usersList, create or update and delete sudo users. A password is a secret and private keys are never returned
Verified rebootsStart a tracked reboot and read its operation; only a verified new boot proves it worked. An unconfirmed reboot can be rechecked without rebooting again
Buying a serverBillable, so it needs an approved plan, region and price, a card on file and an idempotency key. It buys xCloud-managed servers only
Dashboard-onlyResizing or deleting a server, a provider backup of the whole server (Server > Backup), bringing your own server, databases and database users, and PHP settings such as memory limit or upload size

Rules OpenCode has to follow

  • A change that can interrupt a server stops for your approval, and the agent names the server, the service and the impact first.
  • Buying a server is billable: the agent shows the plan, region and price and waits for your yes, and it never retries a purchase without checking your server list first.
  • A reboot is only reported as done when xCloud verifies a new boot, and an unconfirmed reboot is investigated, not repeated.
  • Disabling ssh, nginx, a database or a runtime service needs your explicit confirmation immediately before the call, because it can lock you out or take sites offline.
  • Resizing or deleting a server, provider server backups, bringing your own server and per-site PHP versions 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 Server management?

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
List my servers with CPU, RAM and disk. Flag anything above 80% disk.
Prompt
Install Redis on the Frankfurt server and enable it. Tell me when the task finishes.
Prompt
Show the Fail2Ban bans on Frankfurt, then unban 203.0.113.10.
Prompt
List all my xCloud servers with CPU, RAM and disk usage, and flag any server above 80% disk.
Prompt
List the cron jobs on the Frankfurt server with their schedules.
Prompt
Create a server cron job for the WooCommerce Action Scheduler every five minutes. Show me the final command and schedule before creating it.
Prompt
Install Redis on the Frankfurt server and enable the service.
Prompt
Switch the Frankfurt server's default Node.js to the latest LTS major.
Prompt
Reboot the staging server and tell me when it is back.
Prompt
Show me the IP addresses Fail2Ban has banned on the Frankfurt server, and unban 203.0.113.10.
Prompt
Create a new xCloud server on the smallest plan in Singapore. Show me the plan and price first and wait for my approval.

OpenCode and Server management: Frequently Asked Questions

What people ask before they let OpenCode manage servers through xCloud.

Can I keep OpenCode's everyday coding agent away from my server tools?

Yes. OpenCode lets you turn the xcloud tools off globally and enable them for one agent only. Make an operations agent with them on, and add ?toolsets=servers,alerts to the server URL so that agent loads only the server and alert tools.

Does OpenCode wait for a server task to finish before it says it is done?

It should. xCloud returns as soon as it accepts server work, so OpenCode reads the server's task list until the task settles. A reboot is only reported as done when xCloud verifies a new boot, and an unconfirmed reboot is investigated rather than repeated.

Does the agent ask before it reboots a server?

Yes. A reboot stops for your explicit confirmation, then the agent starts a tracked reboot and reads the operation until xCloud reports a verified new boot. If the result stays unconfirmed it investigates rather than rebooting a second time.

Can an AI agent buy a new server for me?

Yes, but only after you approve it. A new server is billable, so the agent first checks your existing servers, reads the available plans and your card on file, then shows the plan, region and price and waits for your yes. It sends the purchase once, so a retry cannot buy a second server.

If the agent changes the server's PHP default, do my sites change version?

No. The server default changes the command-line php and the version new sites get, and it moves no existing site. Each site keeps its own PHP version, which you change in the dashboard under Site > Site Settings.

Can the agent resize or delete a server?

No. Resizing and deleting a server are dashboard-only, as are a provider backup of the whole server, databases and bringing your own server. The agent can tell you where the control is and give you the server's dashboard link.

Why did the agent say monitoring history is not available?

Monitoring history is a paid-plan feature, so xCloud answers 403 on the free plan. Current CPU, memory and disk readings are still available, and the agent will say that it is a plan limit, not a missing permission.

Other agents

Server management with Other Agents

The same job, the same xCloud tools, a guide for each client.

More OpenCode guides

Related documentation

Run Your Hosting from OpenCode

xCloud MCP, the Agent Skills and the Public API are free with every account. Connect once and ask.

Start for freeAll OpenCode guides