Getting Started
Create your first agent, authorize environments, provision its encryption keys, generate its API key, and verify the connection.
Coming Soon — the Agent Vault is not yet generally available. This documentation describes the feature ahead of its release; details may change before launch.
This guide walks through connecting your first agent to SecretStash — from creating it in the web application to a passing connection test.
Prerequisites
- A SecretStash account with at least one application that has an environment containing variables. See Applications and Variables if you haven't set these up yet.
- A browser session on a device that has already unlocked (decrypted) the environments you want to authorize the agent for. The vault-unlock step below relies on your browser's local device key, not your account password — if this device has never opened the target application before, unlock it there first.
- The Agents section enabled for your account, available from the main sidebar.
Agent limits follow your plan: the Personal plan includes 1 agent, while Team and Organization plans include unlimited agents. You'll see an upgrade prompt if you hit your limit.
Connect an agent
Create the agent
From the Agents page, click New agent. Provide:
- Name — something you'll recognize later, e.g. "Local Claude Code" or "CI Deploy Bot".
- Type —
Claude Code,Cursor,Codex,OpenAI, orCustom. This only affects labeling in the UI; it doesn't change how the agent authenticates. - Description — optional context for your team.
Authorize environments
Select every environment this agent should be able to resolve secrets from. Be as narrow as you can — an agent authorized only for staging can never resolve a production secret, even by mistake.
Authorized environments are enforced on every resolution, on both the MCP and REST surfaces. There is no way for an agent to request a secret outside the environments you select here.
Unlock the vault
When you finish the wizard, your browser unwraps the Data Encryption Key (DEK) for each environment you selected — using this device's local key, the same way opening an application to view its variables does — and sends each one to SecretStash already sealed for this agent. SecretStash never sees the DEK in plaintext.
If this browser can't decrypt one of the selected environments yet (for example, you're setting this up from a brand-new device), that environment is skipped with a message explaining why. You can finish provisioning it later from a device that can decrypt it — open the agent's page and re-save its authorized environments from there.
Generate the API key
Once the agent is created, its API key is displayed exactly once.
Copy this key now and store it in your agent's configuration. SecretStash cannot show it to you again — if you lose it, revoke the agent and reconnect it to get a new one.
Run a connection test
From the agent's page, click Test connection. This runs the same verification protocol available to the agent itself (see Verification & Operations) and checks:
- The agent is active and its token still exists.
- Each authorized environment's key unseals correctly.
- A live secret resolves successfully through the real resolution path.
A passing test confirms the agent is ready to connect for real.
Connect the agent
With the API key in hand, wire the agent up using whichever surface fits it best:
- MCP (recommended for Claude Code, Cursor, Codex, and VS Code) — see MCP Integration.
- REST API (for anything else — scripts, CI, custom runtimes) — see REST API.
Next steps
- Walk through a full worked example resolving a real credential end-to-end.
- Learn how to revoke or rotate an agent's credential.