Cursor Cloud Agent Setup and the Environment Contract

A Cursor cloud agent is a remote run that inherits an environment instead of borrowing yours, so write that environment down before you delegate. Cursor gives you a setup page for the product; the part that breaks teams is the part you own. An environment contract is a short, written description of the runtime, install steps, allowed paths, and secrets policy that a reviewer can check a remote diff against.

We learned this the slow way. A deploy sat blocked while we tried to reproduce, on a laptop, a change a cloud agent had made remotely. Everyone had read the setup docs. Nobody had written down what our environment actually was, so the diff was correct in a world we could not rebuild.

Write the environment contract first

The contract is the minimum context a remote agent needs so it stops guessing. Keep it short enough that a reviewer can hold it next to the actual diff and spot anything out of bounds.

Here is the shape we use. Paste it into an issue or a rule file before the first remote run.

# Cursor cloud-agent environment

- Runtime: Node 22, pnpm 10
- Install: `pnpm install --frozen-lockfile`
- Build proof: `pnpm build`
- Test proof: `pnpm test checkout`
- Allowed paths: `apps/site/src/app/checkout/**`, `tests/checkout/**`
- Forbidden paths: `.env*`, `infra/**`, `.github/workflows/**`
- Secrets: no secret reads; use mocked fixtures only
- MCP: disabled unless the PR names the server and owner

This is not bureaucracy. It is the difference between a remote diff you can rebuild and one you have to take on faith.

Stop setup drift between runs

The fastest way to lose trust in cloud agents is to let each run discover setup differently. One run installs a package, another skips a migration, a third passes because a stray file happened to exist in that agent's environment. The twelve-factor app called this dev/prod parity, and parity decays the second an environment is implicit.

Make every run answer the same five questions, with exact answers.

If the agent cannot produce these answers, the result is not ready for review yet.

Deny secrets by default

Most engineering tasks run fine on fixtures, mocked credentials, or read-only examples, so broad secret access is a choice rather than a requirement. Start from no, and make real access a deliberate, owned decision.

When secret access is genuinely unavoidable, force an owner to sign off in writing:

Secret exception request:
- Secret class: staging payment webhook
- Reason: validate parser behavior against real payload shape
- Owner: platform lead
- Expiry: after this PR
- Alternative considered: fixture payload, rejected because schema is unknown

Without that exception, the default stays no. The same caution applies to MCP servers: keep them off unless the PR names the server and who owns it.

Leave a receipt the reviewer can trust

Remote work needs a stronger PR body than local work, because the reviewer did not watch the session. Give them the setup command, the paths touched, the MCP status, the verification command, and any setup failures the agent hit along the way.

Cloud runs answer to the same surfaces as local ones: Cursor Agent, Cursor Rules, and Cursor MCP, on top of the Model Context Protocol specification. Org defaults live in Cursor Enterprise, and capability changes land in the changelog. The product docs themselves split the topic into setup, an overview, capabilities, and automations.

In our methodology, build can happen remotely, but review still needs evidence in the repo. The surrounding patterns live in the subagents and skills topic hub.

Your next move

Attach the environment contract to the next cloud-agent issue before the run starts, and treat any remote PR without setup evidence as unreviewable. If your team wants to practice this on real repos, our training walks through it step by step.