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 and scope. Build Secrets exist only while the Docker image builds, then vanish. Team and environment secrets can be available while Cursor prepares a Build. User secrets arrive only when an agent starts, so they are unavailable to the Build and never become part of its shared snapshot. A Runtime Secret can still reach the process while its value appears as [REDACTED] in the model's context.

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. 3Check the Build. Saving environment configuration or changing secrets starts a new Build. Open the Builds tab, confirm it succeeded and became active, or inspect its logs if agents stayed on the last successful Build.
4. 4Verify in a fresh real run. User secrets are injected only when an agent starts, so start a new agent and test for the variable without printing its value.
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.