Skip to main content

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:

terminal
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​

terminal
envshed agent install
claude mcp add --transport http envshed https://app.envshed.com/api/mcp
claude mcp login envshed
  • envshed agent install adds two hooks and a skill to ~/.claude. The hooks stop a prompt that contains a secret and block commands that would print one, such as cat .env or envshed secret get. The skill tells the agent to use envshed request and envshed run. See Agent hooks.
  • claude mcp login envshed opens the browser. Check that it names Claude Code, then choose Approve. You can also run /mcp inside Claude Code instead.

Restart Claude Code if it was open. To check the connection:

terminal
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:

~/.cursor/mcp.json
{
"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:

terminal
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 install supports Claude Code only, so nothing stops Cursor from reading a .env file.
  • Masking is not automatic. envshed run masks output by itself only when Claude Code launches it. In Cursor, ask for envshed run --redact, as in the prompt below, or set ENVSHED_AGENT_MODE=1 in 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):

terminal
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:

terminal
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:

FileRead by
AGENTS.mdCodex, Cursor, GitHub Copilot and other agents
CLAUDE.mdClaude Code
.cursor/rules/envshed.mdcCursor, as a rule applied to every chat (written when the project has a .cursor folder)
.github/copilot-instructions.mdGitHub Copilot (when the file exists)
GEMINI.mdGemini 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:

markdown
## 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:

output
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:

  1. The agent calls list_secret_keys. It gets each key name with a status, set, placeholder, disabled or missing, and no values.
  2. For a key that is not there, it calls request_secret and gives you a link to the dashboard. You enter the value on that page. It goes into Envshed, not into the chat.
  3. The agent checks the request with get_secret_request_status and runs the app once it is filled. If the app prints a secret, the output shows a marker instead of the value:
output
✔ 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:

terminal
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 set in 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 run masks 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 .env to 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 scan does not prove nothing leaked.

Next steps​