Skip to main content
Glama
Password Space

Password Space

by vishnutvm

Password Space

CI keychain License: MIT Node 20+

Give AI coding agents your API keys by name, not by pasting them into chat.

Password Space is a local secret store for developers who work with AI agents (Claude Code, Cursor, OpenAI Codex). After you install the plugin, the agent sets it up for you. You hand it a key once (or type it in your Terminal), and from then on the agent sees only its name and runs commands like

password-space run -s GITHUB_TOKEN -- gh repo list

which puts the value straight into that command's environment and scrubs it from the output. Values live in your OS keychain, and hooks stop a prompt from being sent if it contains one.

Why

Agents need credentials to do real work: call an API, push a package, query a database. The usual ways to hand them over all leak:

What people do

What goes wrong

Paste the key into chat

It is stored in the transcript, logs and screenshots for good

Commit or share a .env file

It ends up in git history and shared workspaces

Re-type it every session

Friction, and sooner or later it gets pasted somewhere it shouldn't

Password Space keeps the value on your machine and gives the agent a name to work with instead.

Related MCP server: secrets-mcp-server

Features

  • OS keychain storage. Values go to the macOS Keychain, Windows Credential Manager or Linux Secret Service, using the system tools (no native Node addon). secrets.json keeps only names, tags, notes and keyed fingerprints.

  • run by name. run -s NAME -- <cmd> starts the command without a shell, with the secret in its environment, and replaces the value with [REDACTED] in output that is not a terminal (which is how agents run commands).

  • MCP server for agents. Set up the store (setup_vault), list secret names, save a key the user hands over (store_secret), remove one (remove_secret), and get the exact run command to use. No tool returns a value by default.

  • Prompt and tool hooks. Warn when a prompt contains a stored value (the prompt still goes through and the agent is told to use it by name), and block agent commands that would read a value directly (get, keychain lookups, reading the store or inject files).

  • One plugin, three hosts. The same bundled folder works as a Claude Code plugin, a Cursor plugin, and in Codex via codex-setup.

  • Audit log. Every add, update and remove is logged with the name and the actor, never the value.

Install

Pick the tool you use. All of them share one store in ~/.password-space.

Claude Code

/plugin marketplace add vishnutvm/password-space
/plugin install password-space@password-space-marketplace

Restart Claude Code and run /password-space:setup-password-space (or just say "set up Password Space"). Claude creates the store itself; there is no command to paste. Details: docs/claude-code.md.

Cursor

Settings → Plugins → Add marketplace → https://github.com/vishnutvm/password-space, install password-space, reload the window, then run /setup-password-space. The agent creates the store itself. Details: docs/cursor.md.

OpenAI Codex

git clone --depth 1 https://github.com/vishnutvm/password-space ~/password-space
node ~/password-space/plugins/password-space/dist/cli.js codex-setup --write

Restart Codex and trust the hooks with /hooks. Details: docs/codex.md.

CLI only (npm)

npm install -g password-space

The CLI is published once the first release is tagged; until then use the plugin's bundled dist/cli.js. Requires Node.js 20 or newer.

Usage

Set up and save a secret (just ask the agent)

After installing the plugin, everything happens in chat:

  1. /password-space:setup-password-space (Claude Code) or /setup-password-space (Cursor). The agent calls setup_vault, which creates ~/.password-space with values in your OS keychain. Nothing to paste.

  2. "Save this token as GITHUB_TOKEN: ghp_…". The agent calls store_secret.

  3. "Use GITHUB_TOKEN to list my repos". A later session finds it by name.

  4. "Remove GITHUB_TOKEN". The agent calls remove_secret.

The agent only needs Node.js 20+. If it is missing, the setup command says how to install it.

Save a secret yourself, in Terminal (optional)

password-space setup              # create the store (keychain when available)
password-space set GITHUB_TOKEN   # value typed at a hidden prompt
password-space list               # names and tags, never values
password-space status             # where values are stored

Inside a plugin, the same commands are node "<plugin>/dist/cli.js" …; ask the agent for the exact path (vault_status returns it). set also reads a value from stdin when piped, and --value exists for scripts (avoid it for real secrets: it lands in shell history).

Use it (the agent)

The agent checks names with list_secrets, then wraps any command that needs a secret:

password-space run -s GITHUB_TOKEN -- gh repo list
password-space run -s OPENAI_API_KEY=openai-prod -s DATABASE_URL -- npm test

-s ENV_VAR=name maps a stored name to a different variable. The agent only ever handles the name.

Handing a key to the agent: the trade-off

When you give a key to the agent ("save this as GITHUB_TOKEN: ghp_…"), the value goes to the keychain and later sessions use it by name. The copy you pasted stays in that one chat's history, so for keys that should never touch a chat, use Terminal set instead.

MCP tools

Tool

Returns a value?

Purpose

setup_vault

No

Create the store (keychain when available) and move old plain-text values into it. Safe to call again

vault_onboard

No

Guided setup: the one next step

vault_status

No

Store ready, storage backend, the run command to use

list_secrets / get_secret_metadata

No

Names, ids, tags, notes

store_secret

No

Save a key the user handed over (overwrite: true to replace)

remove_secret

No

Delete a secret by name

inject_secret

No

Fallback when a command can't be wrapped with run: writes a 60-second env file and returns its path

vault_manager

No

Read-only status view for hosts that support MCP Apps

resolve_secret

Yes

Not registered unless you set PASSWORD_SPACE_ENABLE_RESOLVE=1

Architecture

flowchart LR
  Human[You, in Terminal, optional] -->|setup / set / remove| CLI[password-space CLI]
  CLI --> Store
  subgraph Store[Local store]
    KC[(OS keychain: values)]
    JSON[(secrets.json: names, fingerprints)]
  end
  Agent[AI agent] -->|setup, list, store, remove| MCP[MCP server]
  MCP --> Store
  Agent -->|run -s NAME -- cmd| CLI
  CLI -->|value in env, output redacted| Cmd[Child process]
  Hooks[Prompt + tool hooks] -.->|warn on values, block direct reads| Agent

The repository is a pnpm workspace. Three TypeScript packages are bundled with esbuild into one self-contained plugin folder, so installing the plugin needs no build step.

Path

Role

packages/vault

Store, keychain backends (macOS, Windows, Linux), fingerprints, inject files, redaction

packages/cli

Terminal CLI, including run, migrate and codex-setup. Published to npm as password-space

packages/mcp-server

MCP server and the optional Vault Manager MCP App

plugins/password-space

The shipped plugin: bundled dist/, skill, setup command, hooks, manifests for Claude Code and Cursor

scripts/

Bundling, version sync, and tests for the hook scripts

More in docs/architecture.md.

Storage

Platform

Where values go

Tool used

macOS

Login Keychain, service password-space

/usr/bin/security

Windows

Credential Manager, targets password-space:*

PowerShell calling advapi32 Cred*

Linux

Secret Service (GNOME Keyring, KWallet)

secret-tool from libsecret-tools

Values are passed to these tools on stdin, never on the command line. If no keychain works (a headless Linux server, a container), setup falls back to plain values in secrets.json (mode 0600) and every status screen says so. PASSWORD_SPACE_STORAGE=keychain refuses the fallback; =file always uses it. password-space migrate moves existing values into the keychain after reading each one back, and migrate --to file moves them out again.

Keychain items have size limits: about 1,900 bytes on macOS and 2,560 on Windows. Longer values, such as large PEM keys, are refused with a clear error.

Security model

Password Space is built to keep secrets out of chat transcripts when the agent uses them by name. It is not a sandbox, and it says so plainly:

  • Protects against: values ending up in prompts, tool results, transcripts and logs through normal agent use; the store file leaking values when it is copied or read (with the keychain backend).

  • Does not protect against: malware, or an agent running as your user that deliberately works around it. The OS keychain trusts every process of that user, so obfuscated keychain commands, running get inside a pseudo-terminal, or encoding a value before printing it can all still get a value out. String redaction only catches values printed as-is.

  • Closed by default: CLI get only prints to an interactive terminal and asks first; run --no-redact needs a terminal; resolve_secret is off; inject files live 60 seconds and are deleted when the server exits.

For a hard barrier, run the agent as a different OS user or in a container without access to your keychain. The full threat model, including each known bypass, is in SECURITY.md.

Development

pnpm install
pnpm build    # compiles packages and rebuilds plugins/password-space/dist
pnpm test     # unit, integration, MCP stdio and hook tests, plus a version check

CI builds and tests on every push and fails if the committed plugin bundles don't match a fresh build. A second workflow round-trips values through the real keychain on macOS, Windows and Linux.

pnpm demo runs setup, set, list and status against a throwaway store in /tmp/password-space-demo.

See CONTRIBUTING.md, CHANGELOG.md and docs/RELEASING.md.

Upgrading from the encrypted vault

Builds before 0.2.0 kept secrets in an encrypted vault.db unlocked with a passphrase. That file is never deleted or migrated automatically. Run setup, then re-add each secret with set.

License

MIT © Vishnu

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Encrypts and stores API keys and environment variables locally, providing them to AI agents via MCP with tools for listing, describing, getting secrets, and running commands with secret values redacted.
      2
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI agents to securely store and manage encrypted secrets locally while using them indirectly through environment-variable injection or file writes, so plaintext values never enter the agent's context.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to securely inject API keys and secrets into environment files, configs, or commands without the agent ever seeing the secret values.
      10 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to scan and audit environment files for leaked secrets, sanitize them, encrypt/decrypt vaults, and run processes with zero-disk secret injection.
      MIT