Start with AI
This guide sets up an AI coding agent, Claude Code or Cursor, to work on a project with Envshed. At the end the agent runs your app with its secrets, asks you for a key that is missing, and the values stay out of the chat.
It takes about ten minutes. Steps 1 and 2 are done once per machine, step 4 once per project.
:::info Before you start An Envshed account (the first sign-in creates it: Start free), Node.js 20.12 or later, and Claude Code or Cursor. Tested with Claude Code 2.1.323 and Cursor CLI 2026.11.13. :::
1. Install the CLI and sign in
Run this in your own terminal, not in the agent:
npm install -g envshed
envshed login
envshed login opens the browser and prints a code. Check that the browser shows the same code, then choose Approve sign-in. The agent's envshed commands use this login, with your permissions.
2. Connect the agent
Claude Code
envshed agent install
claude mcp add --transport http envshed https://app.envshed.com/api/mcp
claude mcp login envshed
envshed agent installadds two hooks and a skill to~/.claude. The hooks stop a prompt that contains a secret and block commands that would print one, such ascat .envorenvshed secret get. The skill tells the agent to useenvshed requestandenvshed run. See Agent hooks.claude mcp login envshedopens the browser. Check that it names Claude Code, then choose Approve. You can also run/mcpinside Claude Code instead.
Restart Claude Code if it was open. To check the connection:
claude mcp get envshed
It shows Status: ✔ Connected.
Cursor
Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project:
{
"mcpServers": {
"envshed": { "url": "https://app.envshed.com/api/mcp" }
}
}
The Cursor editor and the Cursor CLI read the same file. To sign in from the CLI:
cursor-agent mcp login envshed
cursor-agent mcp list-tools envshed
The second command lists 10 tools, such as list_secret_keys and request_secret. Use a current Cursor version: the Cursor CLI from September 2025 asks for a scope Envshed does not issue, and sign-in stops with "This connection can't continue".
Two things work differently in Cursor:
- No hooks.
envshed agent installsupports Claude Code only, so nothing stops Cursor from reading a.envfile. - Masking is not automatic.
envshed runmasks output by itself only when Claude Code launches it. In Cursor, ask forenvshed run --redact, as in the prompt below, or setENVSHED_AGENT_MODE=1in the environment of Cursor's terminal.
3. Bring a project
A project that already has .env files: let the agent move them. See Migrate with an agent. The agent creates the project, imports each file by key name and never reads a value.
A new project: from the project folder, replace <org> with your organization slug (envshed orgs lists them):
envshed project create --name my-app -o <org>
envshed init -o <org> -p my-app -e development --yes --no-guide --no-import
init writes .envshed.json, which holds names only and is safe to commit. Add the values you already have in the dashboard, or in your own terminal with envshed secret set API_KEY -e development, which asks for the value with a masked prompt. Leave out the ones you do not have yet: the agent asks for them in the next step.
4. Make it a rule
Write a project rule so every agent that opens this repository uses Envshed for secrets, without you repeating it in each prompt. From the project folder:
envshed agent rules
It shows the files and the text, then asks before writing. It adds the rule between markers and keeps the rest of each file:
| File | Read by |
|---|---|
AGENTS.md | Codex, Cursor, GitHub Copilot and other agents |
CLAUDE.md | Claude Code |
.cursor/rules/envshed.mdc | Cursor, as a rule applied to every chat (written when the project has a .cursor folder) |
.github/copilot-instructions.md | GitHub Copilot (when the file exists) |
GEMINI.md | Gemini CLI (when the file or a .gemini folder exists) |
Pass --all to write every file, and --yes to write without a terminal. Running it again changes nothing unless the rule changed. envshed init shows this command as a hint when it ends, and envshed init --agent-rules writes the rule during setup. Commit the files: they hold no secret, and everyone's agent gets the rule.
To add it by hand, paste this into your agent's instructions file:
## Secrets (Envshed)
This project keeps its secrets in Envshed. When you work here:
- Never read, print or copy `.env` files or any secret value, and never ask the user to paste a value in the chat.
- Run commands that need secrets with `envshed run --redact -- <command>`, for example `envshed run --redact -- npm run dev`. The process gets the values; the output stays masked.
- To see which keys exist, use the MCP tool `list_secret_keys` or `envshed definition list`. Both show names, never values.
- If a key is missing, ask for it with `envshed request <KEY> --reason "<why>"` (or the MCP tool `request_secret`) and wait until a person fills it in.
- To move a `.env` file into Envshed, use `envshed import`. Do not copy values by hand.
- If `envshed` is not installed, use `npx envshed@latest` in its place.
:::caution A rule is an instruction, not a barrier
An agent can still ignore it. The barrier comes from the Claude Code hooks (envshed agent install) and from what the server allows each role and token.
:::
5. Give the agent a task
Paste this into the agent, with your organization, project and start command:
Run this app with Envshed. Organization: <org>. Project: my-app. Environment: development.
1. Use the Envshed MCP server to list the key names and find any that are missing.
2. For each missing key, call request_secret, give me the link and wait until I fill it.
3. Run the app with: envshed run -- npm start
Never read .env files, never print secret values and never ask me to paste a value in the chat.
In Cursor, write envshed run --redact -- npm start in step 3.
What happens:
- The agent calls
list_secret_keys. It gets each key name with a status,set,placeholder,disabledormissing, and no values. - For a key that is not there, it calls
request_secretand gives you a link to the dashboard. You enter the value on that page. It goes into Envshed, not into the chat. - The agent checks the request with
get_secret_request_statusand runs the app once it is filled. If the app prints a secret, the output shows a marker instead of the value:
✔ Loaded 3 secrets
Masking 3 secret values in output, 0 too short or common to mask. Output is piped, so the command may drop colors.
Starting agent-demo with config:
DATABASE_URL=[ENVSHED:DATABASE_URL]
PAYMENTS_API_KEY=[ENVSHED:PAYMENTS_API_KEY]
EMAIL_API_KEY=[ENVSHED:EMAIL_API_KEY]
You can also ask for a key yourself, from any terminal: envshed request EMAIL_API_KEY --reason "send email". See Secret requests.
6. Check the history with scan
envshed scan searches the agent's local history for the values in your vault and for known token formats, such as Stripe or GitHub keys. It never shows a value. Run it in the project folder:
envshed scan
After the steps above it prints Nothing found. If it finds something, it lists the key, file and date, exits with code 2 and prints the commands to rotate. Rotate what it finds: the agent may already have sent the value to its model provider.
scan reads Claude Code's history by default. For other files, pass --path <file or folder>. See Scan agent histories.
Try it with the demo project
envshed/agent-demo is a small app with three fake secrets that prints its configuration at startup. Its README goes through these steps in about five minutes, then runs the app with a .env file and with envshed run: envshed scan finds the values in the first output and nothing in the second.
What Envshed guarantees, and what it does not
These hold on every plan:
- The MCP server never returns or accepts a value. Its tools deal in key names and statuses. A test fails if a tool gains a field that could hold a value.
- A requested value never passes through the chat. A person enters it in the dashboard or with
envshed secret setin a separate terminal. - The agent gets no more than your role. MCP calls follow the same permissions as the API and are written to the audit log with the client's name.
- In Claude Code,
envshed runmasks known values in stdout and stderr, as[ENVSHED:KEY_NAME], without any flag.
This reduces accidental leaks. It is not a barrier against an agent with shell access:
- The agent can reach what your login can. It could run
envshed secret get, print its environment, or copy.envto another name and read the copy. The hooks block the common routes in Claude Code, and Cursor has no hooks. Limits that must hold, such as who reads production, belong on the server: use roles and scoped service tokens. - Masking matches values as they are. A value cut in pieces, encoded in another way, written to a file or sent over the network is not masked. See what gets masked.
- A value you paste into the chat is in the transcript. The prompt hook stops it from reaching the model, but Claude Code still writes it to local files. Rotate it.
- Key names enter the model's context. Envshed does not treat key names as secret.
- Finding nothing with
scandoes not prove nothing leaked.
Next steps
- MCP server: all tools, hosted agents and machine tokens.
- Agent sessions: give an agent its own short-lived, limited access.
- Invite your team.