Guide

Cursor Cloud agents

How autonomous / background / Cursor Cloud agents boot the PRC Platform. Most of this is handled automatically by .cursor/environment.json and the scripts in bin/setup/. Read this when the environment fails to start, or when you need to understand why a setup step exists.

For the gotchas an agent hits by hand, see AGENTS.md.

Environment requirements

  • Node.js ≥22.16.0 — Cloud VMs ship /exec-daemon/node (v22.14). Install and prefer nvm: nvm install 22.16.0, and ensure $HOME/.nvm/versions/node/v22.16.0/bin precedes /exec-daemon in PATH (the repo engines field requires ≥22.16.0).
  • PHP 8.4 (from ppa:ondrej/php) and Composer — not always present on a fresh VM; install once if php / composer are missing.
  • After pulling changes, run npm run bootstrap from the repo root to install JS + PHP deps.

Starting the dev environment

Cloud agents run the full VIP CLI dev-env (Docker-in-Docker), configured via .cursor/environment.json:

  • install → bin/setup/cursor-cloud-install.sh: runs npm run bootstrap and npm run build:all, then installs Docker (configured for Docker-in-Docker), the VIP CLI, and best-effort pre-pulls VIP/Lando images into the snapshot.
  • start → bin/setup/cursor-cloud-vip-start.sh: starts the Docker daemon, writes VIP-CLI auth from PRC_PLATFORM_VIP_BOT_USER_ID + PRC_PLATFORM_VIP_BOT_TOKEN (npm run gen:vip-cli-auth), creates (if missing) and starts the prc-platform dev-env, repairs nested /wp mounts when needed, then seeds a 7-day partial DB from alpha.

The site is served by the Lando proxy at http://prc-platform.vipdev.lndo.site/ (the .lndo.site domain resolves to 127.0.0.1; ports 80/443 are exposed). To boot or reboot it manually:

npm run vip:cloud          # ensure Docker + dev-env are up (idempotent)
vip dev-env info --slug prc-platform

After a successful start, readiness means:

  1. Nested mounts are visible inside PHP (/wp/config/wp-config.php and a non-empty /wp/wp-content/plugins)
  2. wp core is-installed succeeds via vip dev-env exec
  3. After partial DB import, https://prc-platform.vipdev.lndo.site/pewresearch-org/ returns HTTP 200 with a Pew Research Center title

If the alpha partial import is skipped (no VIP export auth), WordPress still boots with an empty network — re-run bash bin/setup/vip-partial-db-import.sh --days=7 --env=alpha or npm run vip:sync:alpha.

Do not double-start. The environment start command already boots VIP. Prefer reusing an UP instance (.cursor/skills/verify-prc-platform/bin/control-prc-platform launch / doctor) over running npm run vip:cloud again while start is still running.

Run the dev-env in tmux for long-lived sessions.

Why the cloud setup differs from local

Two Docker-in-Docker details are handled automatically. They are the reason a fresh docker / vip install previously failed in cloud agents.

1. Storage + networking

bin/setup/cursor-cloud-docker.sh installs Docker CE with the fuse-overlayfs storage driver and iptables-legacy. Both are required because the agent VM is itself a container layer.

Cursor's install-agent-store-fuse step creates /etc/fuse.conf before apt installs fuse3. The install script keeps that existing conffile (Dpkg::Options::=--force-confold) so dpkg does not prompt and fail the environment build.

Nested /wp mounts (auto-repair)

VIP/Lando bind-mounts WordPress core to /wp, then nests app-code paths (config, plugins, themes, …) under that bind. On Docker-in-Docker those nested mounts sometimes fail to appear inside prcplatform-php-1 on first create — WordPress fatals on missing /wp/config/wp-config.php while VIP may still report containers as running.

bin/setup/cursor-cloud-vip-ready.sh (called from start) detects that failure and force-recreates the php and nginx compose services so the binds re-apply. Start refuses to run the partial DB import until mounts and wp core is-installed succeed.

2. Elasticsearch is disabled in the cloud

Cursor Cloud VMs hand each agent a threaded cgroup v2 subtree, so the domain-only memory / io controllers cannot be enabled. The Lando Elasticsearch service is the only container with a memory limit (1 GB), and it fails with:

cannot enter cgroupv2 ... with domain controllers -- it is in threaded mode

The cloud start script reuses the canonical .wpvip/vip-dev-env.yml and overrides just Elasticsearch off (--elasticsearch=false). Local / interactive dev keeps it enabled.

HTTPS is trusted automatically

The Lando proxy signs service certs with a local "WPVIP Local CA". bin/setup/cursor-cloud-trust-cert.sh (run by the start script after the proxy comes up) installs that CA into the system trust store (curl / wget / PHP / wp-cli) and the per-user NSS database (Chromium / Chrome). https://prc-platform.vipdev.lndo.site/ then loads without certificate warnings.

VIP CLI keychain hang on headless VMs

Every vip dev-env * command initializes analytics via Token.uuid(), which probes the "Secure" keychain through @github/keytar → libsecret → D-Bus. On headless cloud VMs that native call hangs forever. It never throws, so the CLI's built-in fallback to its file-based Insecure keychain never fires, and the command blocks indefinitely — Lando logs stop right after compose plugin version: ....

bin/setup/cursor-cloud-vip-keychain.sh (run by both the cloud install and start scripts) disables keytar's native addon so the CLI fails over to the Insecure keychain immediately.

DO_NOT_TRACK=1 alone does not help — it is checked after the keychain probe. This is the same failure mode as google-gemini/gemini-cli#26571.

Was this helpful?