// Cursor Cloud VM setup and service startup instructions for local development
| name | cloud-dev-environment |
| description | Cursor Cloud VM setup and service startup instructions for local development |
apps/web): Next.js 16 app (Turbopack). Runs on port 3000.docker-compose.dev.yml.sudo dockerd &>/dev/null &, then confirm with docker info (or sudo docker info if the client cannot reach the daemon yet).docker compose -f docker-compose.dev.yml up -d. If you get permission denied on /var/run/docker.sock, run the same command with sudo docker compose instead of making the socket world-writable.cd apps/web && pnpm prisma:migrate:local (uses dotenv -e .env.local; do NOT use bare prisma migrate dev — it won't load .env.local).pnpm dev from repo root.The app reads apps/web/.env.local. Required non-obvious env vars beyond .env.example defaults:
DEFAULT_LLM_PROVIDER (e.g. openai) — app crashes at startup without this.GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET — hard-required by env.ts validation. Use Google emulator credentials for local dev (see below).UPSTASH_REDIS_TOKEN must be set to dev_token to match the SRH_TOKEN default in docker-compose.dev.yml.MICROSOFT_WEBHOOK_CLIENT_STATE — required if MICROSOFT_CLIENT_ID is set.Use the Google emulator instead of real OAuth credentials:
GOOGLE_CLIENT_ID=emulate-google-client.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=emulate-google-secret
GOOGLE_BASE_URL=http://localhost:4002
Start the emulator: docker compose -f docker-compose.dev.yml --profile google-emulator up -d.
pnpm test runs Vitest unit/integration tests (no DB or external services required).pnpm lint runs Biome. Pre-existing lint warnings/errors in the repo are expected.pnpm test-ai) require a real LLM API key and are skipped by default.The cloud VM is a Docker-in-Docker setup. Docker requires fuse-overlayfs storage driver and iptables-legacy. These are configured during initial setup. After snapshot restore, run sudo dockerd &>/dev/null & if Docker daemon is not running.
The VM may not have the Docker Compose v2 plugin pre-installed. If docker compose version fails, install it:
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -fsSL https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
After a fresh login via the Google emulator, the app forces an onboarding wizard. Some onboarding buttons require JavaScript click() calls rather than standard browser clicks (React event delegation quirk in headless/automation contexts).
Guidelines for testing the application with Vitest, including unit tests, integration tests (emulator), AI tests, and eval suites for LLM features
Simplify and refine recently modified code for clarity, consistency, and maintainability while preserving exact behavior. Use when asked to simplify, polish, refactor lightly, or clean up current-session changes before review or PR.
Commit changes and open a pull request with safe metadata
Review prompt and tool-description changes in a branch or PR. Use when asked to audit system prompts, prompt builders, tool descriptions, prompt inputs, or nearby evals/tests; summarize what changed; identify guidance that feels eval-shaped or too heavy for product use; and find repeated instructions between the main prompt and tool descriptions.
Add a new changelog entry to docs/changelog-entries/
Update workspace packages while respecting the repo's pinned package list in .ncurc.cjs. Use when the user asks to update dependencies or refresh package versions.