How Cursor Cloud Agents Work and When to Use Them

Cloud agents run the same agent loop as local Cursor inside an isolated cloud environment. Your repository is cloned, dependencies install, secrets and startup commands apply, and the agent can build, test, and open a pull request while your laptop is offline. They excel at parallel work and self contained tasks. They are a poor fit for every small edit you could finish locally in one diff review.

Cloud agents require a paid Individual or Teams plan and connected source control per Cursor docs. Hobby includes limited local Agent requests but not the full cloud agent setup. Explore summary at /explore/cursor under Cloud agents and mobile.

How cloud agents differ from local Agent

• Runs in a remote VM with its own environment, not on your machine
• Can run many agents in parallel without local CPU load
• Produces pull requests, artifacts, and optional remote desktop review
• Bills model usage at API pricing for the selected model
• Needs admin connected GitHub, GitLab, Bitbucket, or Azure DevOps

Where to start a cloud agent

• cursor.com/agents in the browser
• Cursor for iOS
• Cloud option in the desktop Agent panel dropdown
• Integrations such as Slack, GitHub, Linear, or API where your plan supports them

The cloud agent workflow

Define a self contained task with clear done criteria. Provide repository context and constraints in the prompt. Start the agent from web, desktop, or mobile. Monitor progress and artifacts. Read the pull request diff. Run trusted tests locally if needed. Merge only after the same review you would apply to local Agent output.

Configure the environment

Agents are only as capable as the environment they run in. Cursor documents agent led setup, saved snapshots, and .cursor/environment.json. Add secrets through the cloud agents dashboard so tests can reach services without committing credentials. Without install steps and test commands, cloud agents may produce code that never ran in CI.

Cloud agent:
Add README setup steps for the dev container in this repo.
Verify documented commands run in the environment.
Open a PR that changes only README and .devcontainer/ files.
Stop if tests fail.

Example: documentation plus verification

Cloud agent:
Task: document local setup for npm run dev and npm test in README.
Run both commands in the cloud environment.
If a step fails, fix README or devcontainer config only.
PR must not change application source outside docs and devcontainer.

Example: focused test fix

Cloud agent:
Fix failing flaky test in src/lib/scheduling/retry.test.ts.
Reproduce failure, patch minimal logic in retry.ts only.
Done when: npm test -- --testPathPattern=retry passes three consecutive runs.
No refactors outside src/lib/scheduling/.

Example: narrow feature branch

Cloud agent:
Add health check route GET /api/health returning { status: "ok" }.
Match patterns in @src/app/api/status/route.ts
Include test file beside route.
Open PR against main; stop if lint fails.

Example: follow up after wide first run

Previous cloud run touched files outside scope.
New cloud agent:
Revert unrelated formatting changes from PR #412.
Keep only billing fix in src/features/billing/charge.ts and its test.
Re run npm test -- --testPathPattern=billing

MCP and integrations on cloud agents

Cloud agents can use MCP servers configured for your team when documented for your plan. That lets agents reach issue trackers or internal APIs during a run. Keep credentials in dashboard secrets, not in the repository. Verify MCP output in artifacts before merge.

Sharing and team visibility

Send an agent run URL to a teammate so they can read the conversation and artifacts. Viewers need repository access through their own connected source control account even when they share your Cursor team. Treat shared runs as read only unless team follow ups are enabled by an admin.

Good tasks vs poor tasks

• Good: self contained docs, tests, or bug fixes with clear commands
• Good: parallel work while you focus locally on another feature
• Good: tasks that benefit from screenshots or logs in artifacts
• Poor: vague improve the codebase with no stop condition
• Poor: changes that need constant local UI interaction you cannot describe

Review before merge

Treat cloud output like local Agent diffs. Read every file. Check artifacts. Confirm secrets were not committed. Run tests locally on the branch when the change touches critical paths. See /blog/how-to-test-and-verify-changes-made-by-cursor.

Artifacts and remote desktop review

Cloud agents can produce screenshots, videos, and logs so you can see what changed without checking out the branch immediately. Remote desktop control lets you exercise the modified software in the cloud environment. Use artifacts as evidence, not as a substitute for reading the diff.

After cloud run completes:
1. Read PR file list
2. Open screenshot artifact for UI change
3. Checkout branch locally if critical path touched
4. Run npm test before merge

Billing and usage

Cloud agents consume model usage at API pricing for the selected model. Cursor docs describe spend limits when you first use cloud agents and dashboard visibility at cursor.com/dashboard/usage. Larger context windows can increase token usage. This is separate from seat pricing on Teams plans.

Mobile workflow

Cursor for iOS lets you start and monitor cloud agents away from your desk. Android users can use cursor.com/agents in Chrome and install the progressive web app per Cursor mobile docs. Review artifacts on mobile but run deep diff review on desktop when the change is large.

When local Agent is still better

Use local Agent when you iterate quickly on UI that requires your local browser extensions, when secrets cannot leave your machine, or when you want tight diff review in the same editor session. Use cloud agents when the task is well specified and can run to completion in the remote environment.

Local Agent: tweak component spacing with hot reload feedback
Cloud agent: update README install steps and verify commands overnight

Common mistakes

• Merging cloud pull requests without reading files Agent touched
• Starting cloud agents without environment setup or secrets
• Assigning repo wide tasks with no definition of done
• Assuming Hobby tier includes full cloud agent access
• Skipping local test runs because the cloud run reported success

Secrets and environment dashboard

Add secrets through the cloud agents area of the Cursor dashboard so tests can reach staging services without committing credentials. Restart the agent after adding secrets if documentation indicates cached environments. Never paste production secrets into the chat prompt.

Cloud agent:
Use DATABASE_URL from team secrets.
Run migrations and npm test in cloud environment.
If secret missing, stop and report instead of guessing connection string.

Parallel cloud and local work

Run a cloud agent on documentation or test fixes while you implement a feature locally in Agent. Keep branches separate. Do not merge both without reading each diff. Parallelism saves calendar time when tasks do not touch the same files.

Local Agent: feature branch feature/notifications UI
Cloud agent: chore/update snapshots on branch chore/snapshots
Merge cloud PR first after review, rebase feature branch if needed.

Starting agents from mobile or web

Cursor web and mobile let you kick off cloud agents away from your desk. Write the same ticket style prompt you would locally. Repository context comes through connected GitHub. Review the resulting pull request on desktop before merge because diff reading on small screens hides subtle logic errors.

Cloud agent from phone:
Task: fix failing CI on branch main — update snapshot in LoginForm.test.tsx
Repo: org/web-app (connected)
Review PR on desktop before merge.

Related: /blog/how-to-test-and-verify-changes-made-by-cursor, /blog/how-to-use-cursor-agent-to-build-and-refactor-code, /blog/how-to-give-cursor-better-context-with-mentions-and-rules.