Environment variables in Cursor are distributed across surfaces: the command line and programmatic interfaces, authentication, the sandbox, work trees, the server worker, the cloud and event handlers. The reference shows names and purposes but not values - secret material must not end up in a book, in a report or in a configuration repository. The split by surface is not a formality: it says immediately which process reads a variable and at what moment it has to exist.
The rule about names and values is not a formal caveat but working practice. A name is safe: it explains what is being configured and can be discussed freely in a ticket or a message. A value is not: it grants access, precisely the access it was issued for. The difference matters especially during debugging, when you want to attach the whole environment dump to a support request. The right move is to attach a list of names and state which of them are set, without revealing the contents; that is enough to diagnose almost any configuration problem.
It helps to lay the variables out by surface in a table once. Below is that map: the key and token for programmatic access, sign-in behavior in an environment without graphics, choosing the credential store, proxy and root certificate configuration, worker labels, the configuration directory. Grouping helps you understand which mechanism a variable belongs to and not to look for it in the wrong place.
| Surface | Variable | Purpose |
|---|---|---|
| Command line and API | CURSOR_API_KEY | The key for a command-line, package or interface process |
| Command line and protocol | CURSOR_AUTH_TOKEN | An alternative pre-issued token |
| Sign-in | NO_OPEN_BROWSER | Do not open a browser in an environment without graphics |
| Sign-in | AGENT_CLI_CREDENTIAL_STORE | A file store instead of the system one; apply deliberately |
| Network | HTTP_PROXY, HTTPS_PROXY | The corporate proxy for outbound connections |
| Network | NODE_EXTRA_CA_CERTS | The organization's root certificate instead of disabling verification |
| Worker |
| CURSOR_WORKER_LABELS_FILE |
| Server worker labels from a file |
| Configuration | CURSOR_CONFIG_DIR, XDG_CONFIG_HOME | The state and configuration directory for containers and benches |
|---|
Variables differ in status, and that is worth telling apart. Some are a guaranteed input: an event handler receives the workspace root and the tool's version, and logic can be built on them. Others are a convention from a documentation example: the name under which a service account key is customarily passed in a sample. The first can be treated as part of a contract, the second cannot, and carrying such a name into your own scripts as mandatory is a mistake. A variable is worth using within the scope in which it is described, without assigning it a meaning it does not have.
Variables that change security deserve a separate note. A file credential store instead of the system one, an additional root certificate, markers of weakened isolation - all of that exists for environments where there is no other way: build machines without a graphical session, containers without a keychain, corporate networks that intercept traffic. Such values are not set in a shared shell profile: they live in the specific run where their necessity is proved, and they disappear with it.
A corporate network provides the most frequent case. Downloads stop working because traffic passes through an intermediary that substitutes its own certificate, and verification honestly rejects it. The temptation is to disable verification entirely; the price is that every outbound connection stops being protected from substitution, including the ones you were not thinking about. The right move is to set the proxy address and add the organization's root certificate: trust is extended by exactly one known authority rather than abolished.
There is also a practical technique for automation: set a variable before a specific command rather than exporting it into the environment as a whole. That narrows visibility to one process and keeps the value from leaking into neighboring steps you did not write - and in continuous integration the neighboring steps are often someone else's. The additional benefit is that the run becomes self-contained: one line shows exactly what it required.
Configuration directory variables are useful in containers and on shared machines: they let you separate the state of different runs without interference. That is a rare but very helpful capability - especially when several environments with different credentials live on one machine and you need a guarantee that signing in to one does not overwrite the sign-in of another.
The engineering conclusion is simple: treat environment variables as part of the configuration rather than as temporary flags. Each has a scope, a lifetime and consequences. Recorded and deliberately granted, they make the environment reproducible; handed out by habit, they create access channels nobody remembers six months later.
The typical failures are predictable. Attaching an environment dump with values to a support request. Exporting a key into the shared environment instead of a specific command. Disabling certificate verification permanently instead of adding the organization's root certificate. Taking a convention from an example for a guaranteed input. And setting security variables in a shared shell profile.