The first thing to understand about Cursor is that it is not an editor with smart autocomplete but a family of surfaces around one agent. The desktop app with Tab and Inline Edit, a separate window for parallel agents, the terminal CLI, isolated Cloud Agents, automated review and programmatic APIs are all different execution environments that share part of the configuration but do not share trust boundaries. Until that difference sinks in, the product looks capricious: the same command behaves differently in two places, and the explanation gets pinned on the wrong cause. The actual cause is almost always the same: matching names do not mean a matching environment in which the name executes.
The naive model is understandable and therefore durable: there is Cursor, it has features, and somewhere they are simply displayed differently. From that model grows the expectation that a setting made in the editor also applies in the cloud, that a command from the CLI changelog will be found in the desktop interface, and that a permission granted once extends to everything. The interface helps that expectation along: it deliberately smooths the differences and shows a familiar window on top of entirely different executors. Every one of those expectations eventually breaks, usually at an inconvenient moment - when the agent did not do what you thought was allowed, or did what you thought was forbidden.
It breaks on a simple fact: the place of execution determines both the context and the permissions. A local agent sees your working directory, your terminal and your environment variables. A Cloud Agent sees a fresh clone of the repository in someone else's container and exactly the secrets you put there. The CLI works in the current shell with its rights, and the API runs from your code with a key that has its own quota and its own policy. The same words - "agent", "edit", "permission" - mean different things across those boundaries, because behind each word stands a different file system, a different set of processes and a different network policy.
Hence the working technique that holds everything else together: ask four questions about any feature. Where does it execute. What context does it receive. What actions is it allowed. How do you verify the result. Those four questions are not philosophy but a way not to confuse layers: they immediately show where to look for the setting and which boundary limits what is happening. The first question settles whose machine this is. The second settles which files entered the field of view at all. The third settles what the agent can do without you. The fourth settles how you tell a claimed result from an actual one.
It helps to lay the surfaces out in a table once, so the choice is deliberate rather than a habit of one window. Below is that map: from the desktop IDE to the Cloud API. You come back to it when deciding where to run a particular task: a pointed edit next to the code goes in the editor; several tasks with visual control go in the agents window; scripts and CI go in the CLI; long autonomous work without your machine goes to the cloud; bulk runs from your own service go through the API and the SDKs.
| Surface | Where it runs | What to choose it for | Main boundary |
|---|---|---|---|
| Cursor IDE | On the local machine, next to the editor and the terminal | Tab, Inline Edit, Agent, a fast edit-and-check loop | Workspace Trust, the Run Mode, the local sandbox |
| Agents Window | Locally or in a worktree and cloud target | Several tasks at once, browser work, shared review | The chosen execution target and checkout isolation |
| Cursor CLI | In the current shell and working directory | Terminal workflow, scripts, CI, ACP | cli-config.json, allow and deny, the sandbox |
| Cloud Agents | In a Cursor-managed or your own VM | Long parallel tasks, PRs, computer use, automations | The cloud environment, secrets and a separate network policy |
| Cloud API and SDKs | From your application, local or cloud runtime | Your own orchestration and bulk runs | The API key, runtime options, hooks, quotas |
One case is worth working through in full. The task is to update dependencies and confirm that the project checks still pass. Where to run it: the update pulls the network and takes time, and your machine is not needed for it, so the cloud. What context: the cloud agent gets a clone of the repository rather than your working copy, so uncommitted edits and a local environment file never reach it - they are either committed or placed into the environment separately. What is allowed: installing packages and going to the network yes, touching other branches and publishing artifacts no. How to verify: not by the agent's summary but by a green run of the existing checks and a file-by-file look at the diff. Four answers took a minute and settled both the surface and the boundaries of the task.
Neighboring mechanisms are worth telling apart, because they solve a similar problem by different means. The parallel agents window and Cloud Agents both give you several tracks of work at once, but they pay for it differently. The agents window stays on your machine: the agents see local state, share your resources and demand your attention, but the result is right there with nothing to catch up on. Cloud Agents run in a separate environment, do not occupy your processor and survive a closed laptop, but in exchange they know nothing about whatever did not make it into the repository and into the cloud environment configuration. Choosing between them is choosing between closeness to your state and independence from it.
The cost of picking the wrong surface is not abstract. Running a long migration in the editor means tying up your machine and your attention for an hour. Sending a task to the cloud when it needs your local services and uncommitted files means getting an agent that honestly works on the wrong state. And giving the CLI in CI the same rights you have at your own terminal means exposing a secret to everything that job runs. The surface is chosen for the task, not by which window is already open.
There is a flip side: the surfaces share more than it seems. Repository rules, AGENTS.md, skills and part of the settings carry across, and that is exactly what makes moving between windows possible without rewriting the process. The practical conclusion is to keep portable whatever defines the agent's behavior, and not to build a team process on top of what is specific to one client. Then changing surfaces becomes a decision about the task rather than retraining the team.
The typical failure here is explaining behavior by the wrong cause. The setting did not apply because it belongs to another surface; the agent did not see the file because it works in a cloud clone; the command was not found because it exists only in the CLI. The sign that gives this away in real work is simple: the problem gets described as "for some reason it does not see" or "for some reason it does not apply", with no mention of a layer. Before hunting for a bug, answer the four questions about the layer - in most cases the answer is right there.