Windsurf + xCloud

Run Docker apps with Windsurf on xCloud

Running Docker apps with Windsurf means asking the Devin Local agent in the editor where your Dockerfile or Compose file is open to scan it, deploy it to an xCloud Docker server after you confirm and keep the app backed up.

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

Set up Windsurf All Windsurf guides

YouThe app on notes.example.com answers 502. Check the compose file's ports against xCloud's.

git_compose-scanread-only

AgentThe open docker-compose.yml publishes no port for web, so xCloud has nothing to proxy to. I can publish 127.0.0.1:8080:8080 in the file. Edit it?

YouYes, then I will push and you redeploy.

sites_statusread-only

AgentFile edited, not pushed. Once it is on main I will redeploy the same site after you approve.

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 Windsurf to Run Docker apps on xCloud?

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

1
Add xCloud to the Devin Local agent
New tabs in Devin Desktop use the Devin Local agent, which reads MCP servers from the Devin CLI config files. Run this in a terminal: the URL is treated as Streamable HTTP, and the second command opens the browser for the xCloud sign-in (the agent also prompts on first use). By default the entry lands in .devin/mcp_config.local.json for the current project; add -s user to the first command to share it across projects in ~/.config/devin/mcp_config.json, where the entry reads url plus transport http.
Shell
```
devin mcp add xcloud https://app.xcloud.host/mcp
devin mcp login xcloud
```
2
Or edit the legacy Cascade config
If your tab runs the legacy Cascade agent, click the three-dot menu in the Cascade panel, then the Open MCP config file icon in the MCPs section, and add this under mcpServers. Cascade allows 100 tools in total and the full xCloud server offers 188 operations plus two search tools, so point serverUrl at the compact profile, five tools that reach every operation through search and call; a single toolset such as ?toolsets=sites (60 tools) also fits, but sites and servers together are 121 tools. Windsurf's file has been at ~/.codeium/windsurf/mcp_config.json, and the current documentation lists ~/.config/devin/mcp_config.json on macOS and Linux and %APPDATA%\devin\mcp_config.json on Windows; the icon opens the one your version reads.
JSON
```
{
  "mcpServers": {
    "xcloud": {
      "serverUrl": "https://app.xcloud.host/mcp?profile=compact"
    }
  }
}
```
3
No browser sign-in? Use an API key
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, export it as XCLOUD_TOKEN and add a headers field to the xcloud entry. Both agents fill in the ${env:XCLOUD_TOKEN} reference from your environment, so the token itself stays out of the file. The Devin Local entry is shown; for Cascade the same headers field sits beside serverUrl.
JSON
```
"xcloud": {
  "url": "https://app.xcloud.host/mcp",
  "transport": "http",
  "headers": {
    "Authorization": "Bearer ${env:XCLOUD_TOKEN}"
  }
}
```

Check it worked

Then ask Windsurf for the job itself, for example:

Prompt

Deploy this project to my Frankfurt Docker server as a Compose app. Scan docker-compose.yml first and show me the ports before anything is created.

In practice

How Does Docker apps Work from Windsurf?

In Windsurf the Compose file is usually one tab away from the agent chat, and the agent can read it as easily as it reads the scan result. Ask the Devin Local agent to deploy the app and it calls git_detect, then git_compose-scan, and tells you which services and ports xCloud found next to what the open file actually declares. If a service binds 80:80 or the file publishes no port, it says so and can edit the Compose file right there, for example publishing 127.0.0.1:8080:8080 with the image built from source. You commit that change before the deploy, because xCloud runs the file as committed and does not rewrite it. Windsurf now ships as Devin Desktop and new tabs use Devin Local, so the connection is one command, devin mcp add xcloud https://app.xcloud.host/mcp, followed by devin mcp login xcloud.

Approval has two layers. Devin Local asks before an MCP tool runs by default, and xCloud adds its own step for a create or a deploy: the create runs as a dry run, prints the resolved compose file, port and address, and waits for your explicit confirmation before the confirmed call. The agent then polls the site status, fetches the URL and reports the result in the chat instead of calling the deploy done on a 202. Devin Local has no documented tool cap, so the full URL is fine. If your tab runs the legacy Cascade agent, its 100-tool limit matters: set serverUrl to https://app.xcloud.host/mcp?profile=compact and Cascade reaches the deploy, scan and backup operations through five tools, since the sites and servers toolsets together are 121 tools and do not fit.

For backups, ask for one before you upgrade an image and the agent takes a Docker backup, then reads the backup list to confirm it completed. xCloud runs that backup without a confirmation of its own, though Devin Local still asks before the tool call. The app is stopped during capture, so choose a quiet moment. A restore is not something the agent can do for you: it gives you the dashboard path, Site, Backup, Previous Backups, and you apply it there.

Windsurf specific: Check which file holds the xcloud entry before you debug a missing tool. Devin Local reads ~/.config/devin/mcp_config.json for your user, .devin/mcp_config.json for a project shared through git, and .devin/mcp_config.local.json for a local, gitignored entry, which is the default scope. Its entry is a url with transport set to http, and an API key goes in a headers field. A legacy Cascade tab opens its file from Open MCP config file in the Cascade panel menu, where Windsurf has also used ~/.codeium/windsurf/mcp_config.json, and its remote entries use serverUrl or url. Only Cascade needs the compact or toolsets URL, because of its 100-tool total.

What xCloud does for docker apps

xCloud reads the repository, scans the Compose file for services and ports before anything is created, previews the site with a dry run and deploys it behind its own nginx once you approve. Docker sites can be backed up on demand and on a schedule, and a failed deploy is diagnosed and retried on the same site.

Pick a Docker server. The agent uses the server you name, or lists your servers and asks. A Docker deploy needs a Docker server; any other stack answers with an incompatible_server refusal, and an agentic server never takes a second site. WordPress is not supported on Docker servers.
Detect the repository. git_detect reads the repository root for a Dockerfile or one of the four Compose file names, and checks access and server compatibility. It creates nothing, and an access problem is never worked around by naming an app type by hand.
Scan the Compose file. git_compose-scan runs before the dry run. It lists the services and the host ports the file publishes, resolves which Compose file name it found, and suggests a primary port. The agent never guesses the port.
Dry run, then one approval. The agent sends the Docker create request with dry_run set to true and shows the resolved configuration: compose file, port, address and warnings. 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 running. The agent polls the site status until it is terminal, reads failed_steps and the SSL block, and fetches the URL before it calls the app live. A 502 here usually means the Compose file publishes no port.
Back up and recover. The agent can take a Docker backup, read the backup list and settings, and add a note to a backup. If a deploy fails it reads the diagnosis, proposes a fix from the correctable fields and retries on the same site after your approval. Restoring a backup is a dashboard step.

Reference

Docker apps Settings and Limits on xCloud

The facts Windsurf works within when it runs Docker apps. Where a row names the dashboard, that step stays yours to take there.

Setting or limit	What applies
Supported inputs	A Dockerfile for a single container, or a Compose file for one or more services, on a Docker server. Go, Python, Rust and Java apps all deploy this way
Server stack	Docker servers only. The Docker deploy on any other stack, including an agentic server, answers 422 with the code incompatible_server
Which Compose file runs	docker-compose.yml at the repository root. A file named compose.yaml, compose.yml or docker-compose.yaml, or one in a subdirectory, deploys through the pinned Docker create with docker.compose_file set to the path the scan resolved
Public port	xCloud's nginx owns ports 80 and 443 and proxies to one host port of 1024 or higher on 127.0.0.1. xCloud runs your Compose file as-is and never rewrites its ports mapping
Port refusals	A port another site already holds is refused as port_unavailable. A port the file does not publish is refused as port_not_published, with the published ports listed
No published port	A Compose file that publishes no port is accepted and then answers 502, so the scan is the step that catches it
Private registries	The deploy runs docker compose pull and never docker login, so an image from a private registry cannot be pulled. Build the image from source instead
Environment and redeploys	Send environment values through env_file_content. A redeploy runs git reset --hard and git clean -df in the site directory, so uncommitted server-side changes are lost
What a Docker backup holds	Named volumes, eligible bind mounts, the Compose file and the app's .env, in an encrypted snapshot. The app is stopped while the backup captures and restarted afterwards
Backup tools	Take a backup, list backups, read the count and the settings, change the settings, add a note and delete a backup. Remote copies go to a storage provider you add in the dashboard
Restores	A restore replaces the app's data in place, so it stays a dashboard step: Site, Site Backup, Previous Backups, Restore Backup
Dot-prefixed paths	A 403 on a path that starts with a dot is the dot-path allowlist. It is fixed with docker.allowed_dot_paths in the deploy settings, without a rebuild

Rules Windsurf has to follow

The Compose file is scanned before the dry run, and the port always comes from the scan, never from a guess.
A file that binds ports 80 or 443, publishes no port or pulls from a private registry is not deployed as-is. The agent shows the rewrite, such as publishing 127.0.0.1:<high port>:<app port> and building the image from source, and the change goes into your repository.
Creating a site, deploying, redeploying and deleting a backup stop for your approval. A backup runs without a separate prompt but stops the app while it captures, so ask for one at a quiet time.
A failed Docker site is retried in place with corrections. It is never deleted and recreated, because it keeps its domain and port.
Restoring a backup, adding a backup storage provider and changing a live site's domain are dashboard steps; the agent gives you the path and the dashboard link xCloud returned.

Example prompts

What Can You Ask Windsurf to Do for Docker 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

Deploy this project to my Frankfurt Docker server as a Compose app. Scan docker-compose.yml first and show me the ports before anything is created.

Prompt

The Compose app on notes.example.com answers 502. Compare the ports in my open docker-compose.yml with the port xCloud is using.

Prompt

Take a backup of the Docker app on notes.example.com before I bump the image tag, and tell me when it completes.

Prompt

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

Prompt

Deploy github.com/acme/shop to the Frankfurt Docker server as a Compose app. Scan the compose file first, show me the services and ports, then wait for my approval before creating anything.

Prompt

Deploy the main branch of github.com/acme/api to my Docker server as a Compose app on a staging hostname.

Prompt

My Compose app on notes.example.com answers 502. Check which port its compose file publishes and which port xCloud is using.

Prompt

Take a backup of the Docker app on notes.example.com now, before I upgrade it, and tell me when it is done.

Prompt

Show the backup settings and the last backup of every Docker app on this team, and list the ones with no schedule.

Prompt

The last deploy of the API site failed. Diagnose it, show me the settings I can correct, fix the build command and retry on the same site.

Windsurf and Docker apps: Frequently Asked Questions

What people ask before they let Windsurf run Docker apps through xCloud.

Which xCloud connection does Windsurf need for Docker apps?

Devin Local can use the full URL, https://app.xcloud.host/mcp, because no tool cap is documented for it. On the legacy Cascade agent use https://app.xcloud.host/mcp?profile=compact as the serverUrl, which reaches the Docker deploy, the Compose scan and the Docker backup operations through five tools inside its 100-tool cap; the sites and servers toolsets together are 121 tools, which does not fit.

Can Windsurf's agent edit my docker-compose.yml to fix a 502?

Yes, since the file is open in the editor. It can change the ports mapping and the image source, but xCloud deploys what is committed, so you commit and push before the agent redeploys the same site after you confirm.

Which servers can run a Docker app on xCloud?

Docker servers. Node.js, PHP and static builds use Nginx or OpenLiteSpeed servers, and the Docker deploy on any other stack is refused with an incompatible_server code. An OpenClaw, Hermes, Paperclip or DeepSeek Harness server hosts only the site created at provisioning, so it takes no Docker app.

Why does the agent scan the Compose file before deploying?

xCloud proxies to the host port your file publishes and never rewrites it. The scan lists the services and ports, so the agent picks a port that is free on the server and published by the file instead of guessing.

Why does my Compose app answer 502 after it deployed?

The most common cause is a Compose file that publishes no port: xCloud accepts it, then its nginx has nothing to proxy to. Publish the app on 127.0.0.1 with a high port, such as 127.0.0.1:8080:8080, and redeploy.

Can an agent deploy an image from a private registry?

Not as-is. The deploy runs docker compose pull and never docker login, so a private image cannot be pulled. Build the image from source in the Compose file, or deploy a repository that does.

Can an agent back up and restore a Docker app?

It can take a backup, read the backup list and settings, change the settings, add a note and delete a backup. Restoring replaces the app's data in place, so you do that in the dashboard under Site, Site Backup, Previous Backups.

Can I run WordPress as a Docker app on xCloud?

No. Creating a WordPress site on a Docker server is refused because WordPress is not supported on Docker servers. Use an Nginx or OpenLiteSpeed server for WordPress.

Other agents