Cursor cloud agent setup: 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, Anysphere's AI code editor, 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.

Common questions

• What should a Cursor cloud agent environment include?

  The environment contract names the runtime, the install command, build and test proof commands, allowed and forbidden paths, the secrets policy, and MCP status. Keep it short enough that a reviewer can compare it with the actual diff. That is the minimum context a remote agent needs so it does not guess its way through your repo.

• Is the Cursor cloud-agent setup page enough to run cloud agents safely?

  No, product setup alone is not enough; safe runs also need an environment contract the team owns. Write the runtime, install command, allowed paths, forbidden paths, and secret policy into the PR or issue so a reviewer can check the run against it. The docs cover the product, and your contract covers your repo.

• How should cloud agents handle secrets?

  Deny secret access by default, since most tasks run fine on fixtures, mocked credentials, or read-only examples. When secret access is unavoidable, force an owner decision with a written exception that names the secret class, the reason, the owner, the expiry, and the alternative that was rejected. Without that exception, the answer stays no.

• What evidence should a remote agent PR include?

  The PR body should carry the setup command, the paths touched, MCP status, the verification command, and any setup failures the agent hit. Remote work needs a stronger PR body because the reviewer did not watch the session. If the agent cannot produce this evidence, the result is not ready for review.

• How do you stop setup drift between cloud-agent runs?

  Use a setup check with exact answers: which runtime version is active, which install command ran, which tests prove the change, which files were forbidden, and which external tools were available. Letting each run discover setup differently is the fastest way to lose trust in cloud agents, so make every run answer the same questions the same way.

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.