Fix: Cursor Cloud Agent Can't Access Secrets

You added an API key on the dashboard, started a cloud agent, and the run fails anyway: the test suite wants DATABASE_URL, the agent says the variable is unset, or printenv in the shared terminal comes back empty. This is one of the most-reported cloud agent problems on Cursor's forum, and nearly every case traces to one of five causes.

• The environment VM predates the secret. Secrets added after an environment was set up don't reach existing machines until you update or recreate the environment.
• The scope doesn't cover this run. Environment-scoped secrets apply only to agents using that environment, and a secret's repository setting can exclude the repo you launched against.
• Wrong secret type. A Build Secret is only available to the Docker build; the running agent never sees it. A Runtime Secret works but shows as [REDACTED] in the transcript, which looks like a failure and isn't.
• You're checking at the wrong moment. Secrets that don't appear during the setup wizard can still be present once a real agent run starts.
• A bug window. In June 2026, automation-launched agents in multi-repo environments received no secrets at all while manual and API launches got them.

All of them live in the Secrets tab of the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. dashboard on cursor.com, where they're exposed to the agent as environment variables. None of them live in .cursor/environment.json: Cursor's published schema for that file has no secrets field, so a key pasted there is just a plaintext leak in your repo. The environment.json reference covers what the file actually holds.

What the agent can read depends on the type you assign each secret. Cursor documents three, and picking the wrong one is the quietest way to lose a credential.

Scope is the second axis. The setup docs describe user secrets, team secrets and environment-scoped secrets; the kv below maps where each applies.

Timing causes more confusion here than configuration does. Cursor staff confirmed on the forum that secrets often don't appear inside the terminal during the environment setup wizard, and that this is expected: they arrive once setup finishes and a real run starts. So a bare printenv during setup proves nothing.

The lifecycle differs by type. Build Secrets exist only while the Docker image builds, then vanish. Environment Variables and Runtime Secrets are injected for the run itself, which means your install and start commands and the agent's own shell all see them. The one thing a Runtime Secret never does is appear as text in the model's context; the process reads the real value while the transcript shows the placeholder.

Work the ladder from cheapest to most drastic. Most cases resolve at step three, and each earlier step rules out a cause that would make the later ones pointless.

1. 1Check the type. If the credential is needed at runtime, it must be an Environment Variable or Runtime Secret. A Build Secret will never reach the agent, by design.
2. 2Check the scope. Confirm the secret's repository setting covers the repo you're launching against, and that an environment-scoped secret belongs to the environment this agent actually uses.
3. 3Update the environment. In the Environments view, run Update with Agent or New Setup Run so a fresh VM is built with the current secrets. Machines created before the secret won't have it.
4. 4Verify in a real run, not the wizard. Start an agent and have it test for the variable; wizard-phase terminals are documented as unreliable for this.
5. 5If an automation launched the agent into a multi-repo environment, try the same task as a manual or API launch. That was the staff-confirmed workaround for the June 2026 injection bug, which the thread reports resolved by mid-July.

Prove presence without printing the value. Ask the agent to run a shell test that reports whether the variable is set and non-empty, which works for every type the running agent can see.

test -n "$STRIPE_API_KEY" && echo "STRIPE_API_KEY: present" || echo "STRIPE_API_KEY: missing"

For a Runtime Secret, expect the transcript to show [REDACTED] anywhere the raw value would appear. That is the redaction working. If you need to eyeball the actual value, the shared terminal shows it to you, since redaction applies to the model's view, not the human one.