vaultshell MCP server
Commit Oct 14, 2026Injects secrets into shell commands at execution time while ensuring plaintext never reaches the LLM context through mandatory redaction.
Also known as SoWhatI/vaultshell
- Stars
- 1
- Tools
- 16
- Downloads, 30 days
- —
- Latest version
- 0.1.2
- Last commit
- Oct 14, 2026
- License
- MIT
What is vaultshell MCP?
vaultshell injects secrets into shell commands at execution time while ensuring plaintext never reaches the LLM context through mandatory redaction. It exposes 16 tools, such as shell_exec, secret_list, secret_set.
Summary generated from the project's README
About vaultshell MCP server
Developers who need to run shell commands via AI agents without exposing sensitive credentials to the model context can use vaultshell. This MCP server manages secrets in local secure storage and injects them into child processes at execution time using a reference-based system. By ensuring that plaintext values never pass through the tool layer, it prevents sensitive data from appearing in LLM prompts, tool responses, or logs.
Users can interact with the server through tools like shell_exec for one-shot commands or shell_session_open for persistent sessions. The system includes mandatory output redaction to catch accidental leaks and a credential proxy for high-sensitivity API tokens. Setup requires Node.js 20+ and a 64-character hex master key provided via environment variables. It supports various backends including encrypted files, 1Password, HashiCorp Vault, and local keychains to manage secret references securely.
What you can do with it
- 1Maintain long-lived secure shell sessionsOpen a persistent shell session where secrets are injected once at creation and automatically expire after a period of inactivity.
Written from the project's README. Every use case is checked against a quote from it.
How to install vaultshell MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall vaultshell MCP in Claude Code
$ claude mcp add vaultshell -- docker run -i --rm ghcr.io/sowhati/vaultshell:0.1.2Install vaultshell MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"vaultshell": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sowhati/vaultshell:0.1.2"
]
}
}
}Install vaultshell MCP in VS Code
.vscode/mcp.json
{
"servers": {
"vaultshell": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sowhati/vaultshell:0.1.2"
]
}
}
}Install vaultshell MCP in VS Code CLI
$ code --add-mcp '{"name":"vaultshell","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/sowhati/vaultshell:0.1.2"]}'Install vaultshell MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"vaultshell": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sowhati/vaultshell:0.1.2"
]
}
}
}Install vaultshell MCP in Codex
$ codex mcp add vaultshell -- docker run -i --rm ghcr.io/sowhati/vaultshell:0.1.2Install vaultshell MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.vaultshell] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/sowhati/vaultshell:0.1.2"]
Install vaultshell MCP in Gemini CLI
$ gemini mcp add -s user vaultshell docker -- run -i --rm ghcr.io/sowhati/vaultshell:0.1.2Install vaultshell MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"vaultshell": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sowhati/vaultshell:0.1.2"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for ghcr.io/sowhati/vaultshell:0.1.2 0.1.2 in an isolated container with no network and no keys. It answered and listed 16 tools.
vaultshell MCP tools 16
Read from the server with tools/listshell_execExecute a one-shot shell command with secrets injected per matching rule. Output is redacted: injected secret values never appear in the response. Dangerous commands (env, printenv, export -p, /proc/*/environ, ...) are hard-blocked. There is no free-form env parameter; secrets are only injected by reference via rules.
secret_listList registered secret names with metadata (backend ref, resolvable). Never returns values.
secret_setStore a secret value into the configured backend. The value is persisted, never echoed back, and the name is registered in rules.yaml (ref only).
secret_deleteDelete a secret from the backend and unregister it from rules.yaml.
secret_probeCheck whether a secret ref can be resolved. Returns only {ok, masked}; masked never contains value fragments unless defaults.maskTail > 0.
rule_listList injection rules with static warnings (e.g. rules matching every directory → potential unintended full injection).
audit_queryQuery recent audit entries (newest last). Entries contain names and redacted commands only, never values.
shell_session_openOpen a persistent shell session (PTY when node-pty is available, plain child_process otherwise — the response's `pty` field says which). Secrets are injected once at creation per matching rule; idle sessions are killed after ttlSeconds (rule ttlSeconds overrides defaults.sessionTtlSeconds).
shell_session_sendSend a command to a persistent session. Output (merged stdout/stderr) is redacted before returning. Dangerous commands are blocked per security.dangerousCommands. Returns {output, exitCode}.
shell_session_closeClose a session: kill the process; injected secrets die with it.
shell_session_listList live sessions (metadata only: id, cwd, injected names, pty, ttl, timestamps).
shell_session_revokeImmediately kill a session and rebuild a fresh one WITHOUT any injected secrets. Use when a session may have been compromised. Returns the new sessionId.
| shell_exec | Execute a one-shot shell command with secrets injected per matching rule. Output is redacted: injected secret values never appear in the response. Dangerous commands (env, printenv, export -p, /proc/*/environ, ...) are hard-blocked. There is no free-form env parameter; secrets are only injected by reference via rules. | |
| secret_list | List registered secret names with metadata (backend ref, resolvable). Never returns values. | |
| secret_set | Store a secret value into the configured backend. The value is persisted, never echoed back, and the name is registered in rules.yaml (ref only). | |
| secret_delete | Delete a secret from the backend and unregister it from rules.yaml. | |
| secret_probe | Check whether a secret ref can be resolved. Returns only {ok, masked}; masked never contains value fragments unless defaults.maskTail > 0. | |
| rule_list | List injection rules with static warnings (e.g. rules matching every directory → potential unintended full injection). | |
| audit_query | Query recent audit entries (newest last). Entries contain names and redacted commands only, never values. | |
| shell_session_open | Open a persistent shell session (PTY when node-pty is available, plain child_process otherwise — the response's `pty` field says which). Secrets are injected once at creation per matching rule; idle sessions are killed after ttlSeconds (rule ttlSeconds overrides defaults.sessionTtlSeconds). | |
| shell_session_send | Send a command to a persistent session. Output (merged stdout/stderr) is redacted before returning. Dangerous commands are blocked per security.dangerousCommands. Returns {output, exitCode}. | |
| shell_session_close | Close a session: kill the process; injected secrets die with it. | |
| shell_session_list | List live sessions (metadata only: id, cwd, injected names, pty, ttl, timestamps). | |
| shell_session_revoke | Immediately kill a session and rebuild a fresh one WITHOUT any injected secrets. Use when a session may have been compromised. Returns the new sessionId. |
Show all 16 toolsShow fewer tools
rule_validateStatically validate rules.yaml and return findings: unknown secret refs, unreachable rules (shadowed by earlier ones), inject-everywhere rules (high severity), requireConfirm capability notes, union mergeStrategy risk notes.
shell_proxy_startStart a credential-injecting reverse proxy on 127.0.0.1 (random port) for a `proxies` entry in config.yaml. Point commands at http://127.0.0.1:<port> instead of the real API host; the proxy injects the secret into the configured header in memory only. Auto-stops after its TTL (default defaults.proxyTtlSeconds=300s). The secret value is never returned anywhere.
shell_proxy_stopStop a running credential proxy.
shell_proxy_listList running credential proxies (metadata only: id, port, upstreamHost, secret NAME, expiry, request count). Never includes values.
| rule_validate | Statically validate rules.yaml and return findings: unknown secret refs, unreachable rules (shadowed by earlier ones), inject-everywhere rules (high severity), requireConfirm capability notes, union mergeStrategy risk notes. | |
| shell_proxy_start | Start a credential-injecting reverse proxy on 127.0.0.1 (random port) for a `proxies` entry in config.yaml. Point commands at http://127.0.0.1:<port> instead of the real API host; the proxy injects the secret into the configured header in memory only. Auto-stops after its TTL (default defaults.proxyTtlSeconds=300s). The secret value is never returned anywhere. | |
| shell_proxy_stop | Stop a running credential proxy. | |
| shell_proxy_list | List running credential proxies (metadata only: id, port, upstreamHost, secret NAME, expiry, request count). Never includes values. |
Configuration
MASTER_KEY
| Name | Description | |
|---|---|---|
| MASTER_KEY | — |
Automated checks
Ran Nov 12, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubvaultshell
English | 简体中文
Available on the official MCP Registry: io.github.SoWhatI/vaultshell
An MCP server that stores secrets in local secure storage, injects them into shell child processes at exec time based on rules, and guarantees secret plaintext never reaches the model context — not in tool responses, not in logs, not in audit records.
The closed loop: reference-based storage + conditional injection + mandatory output redaction.
Status: M3 — one-shot commands + persistent sessions + credential proxy + external CLI backends. See CHANGELOG and docs/design-spec.md.
The iron rule
- No MCP tool returns secret plaintext — ever. Responses contain only names,
masks (
[REDACTED:NAME]), and redacted output. - Resolvers are only invoked inside the launcher; values go straight into the
child process
envand never pass through the tool layer. shell_exechas no free-formenvparameter. Secrets enter by rule reference only.- Redactor failures are fail-closed: output is discarded, never returned raw.
Quick start
Requires Node.js 20+.
Install from GitHub (no npm registry account needed)
# Run on demand directly from the repo (npm installs devDependencies and
# builds dist/ via the `prepare` script):
npx -y github:SoWhatI/vaultshell
# Or install globally:
npm i -g github:SoWhatI/vaultshell
This is the same code as the npm registry package, installed from git —
npm clones the repo, runs prepare (→ npm run build) and links the
vaultshell bin. Pin a tag for reproducibility:
npx -y github:SoWhatI/vaultshell#v0.1.1.
Docker (ghcr.io)
docker run -i --rm \
-e MASTER_KEY=<64 hex chars> \
-v ~/.vaultshell:/home/node/.vaultshell \
ghcr.io/sowhati/vaultshell:latest
MCP client config using Docker:
{
"mcpServers": {
"vaultshell": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MASTER_KEY=<64 hex chars>",
"-v", "~/.vaultshell:/home/node/.vaultshell",
"ghcr.io/sowhati/vaultshell:latest"
]
}
}
}
The image runs as the non-root node user (HOME=/home/node), so the data
volume mounts at /home/node/.vaultshell. node-pty is excluded from the
image — sessions automatically fall back to pipe mode (pty: false) in
containers; injection and redaction are unchanged. The web subcommand
passes through (docker run … ghcr.io/sowhati/vaultshell web — loopback
inside the container, of limited use).
No Smithery distribution: Smithery has gone hosted-only (it only accepts servers deployed to its own infrastructure). vaultshell's secrets must stay on the user's machine by design — third-party hosting is incompatible with its threat model, so we deliberately do not publish there.
From source
# Run via npx (after publish) or from source:
npm install && npm run build
# 1. Create a master key for the encrypted-file backend
export MASTER_KEY=$(openssl rand -hex 32)
# 2. Create ~/.vaultshell/config.yaml and ~/.vaultshell/rules.yaml
# (full annotated examples: docs/user-guide.md)
# 3. Store a secret (never echoed back) and run with injection
# via your MCP client's tools: secret_set, then shell_exec
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"vaultshell": {
"command": "npx",
"args": ["-y", "vaultshell"],
"env": { "MASTER_KEY": "<64 hex chars>" }
}
}
}
Full setup, configuration reference, rule-writing guide, client integration, and FAQ: docs/user-guide.md.
MCP tools
| Tool | Purpose | Returns |
|---|---|---|
shell_exec |
Run a one-shot command with per-rule injection. Params: command, cwd?, profile?, extraEnv? (allowlist), dryRun?, timeoutSeconds? (≤3600) |
{exitCode, stdout, stderr} (redacted), injected:[names], ruleId, redactedCount, timedOut, truncated, warnings; dryRun → {dryRun:true, ruleId, injected, envKeys, denied} |
shell_session_open |
Open a persistent session; secrets injected once at creation | {sessionId, cwd, injected:[names], pty, ttlSeconds} |
shell_session_send |
Send a command to a session | {output} (merged, redacted), exitCode, redactedCount |
shell_session_close |
Kill a session; secrets die with the process | {ok} |
shell_session_list |
List live sessions | metadata only |
shell_session_revoke |
Kill and rebuild the session without secrets | {sessionId} (new) |
shell_proxy_start |
Start a credential-injecting reverse proxy on 127.0.0.1 | {proxyId, port, expiresAt, upstreamHost} |
shell_proxy_stop |
Stop a proxy | {ok} |
shell_proxy_list |
List running proxies | metadata only (incl. secret name, never value) |
secret_list |
List names + metadata (backend ref, resolvable) | never values |
secret_set |
Write to backend; persisted, never echoed | {name, ok} |
secret_delete |
Delete and unregister | {name, ok} |
secret_probe |
Check a ref resolves | {ok, masked:"****"} |
rule_list |
Rules + static warnings (e.g. inject-everywhere) | — |
rule_validate |
Static findings: unknown secrets, unreachable rules, inject-everywhere, union risk, requireConfirm capability | {ok, findings[]} |
audit_query |
Read audit entries | names + redacted commands only |
Execution limits (M3)
dryRun: trueonshell_execreports the would-beruleId,injectednames, final env key list (never values) and the deny-list verdict — without executing anything.timeoutSeconds(defaultdefaults.execTimeoutSeconds= 120, capped at 3600) kills the command and returnstimedOut: true.defaults.maxOutputBytes(default 1 MiB) truncates each output stream and setstruncated: true. Truncation happens after the Redactor — it can never bypass redaction.defaults.maxConcurrentExecs(default 8) rejects excess concurrentshell_execcalls with a clear error (no queue).- All of the above are recorded in the audit log (
dryRun/timedOut/truncatedflags).
Web config UI
vaultshell web # loopback-only HTTP UI on a random port
vaultshell web --port 5317
Prints a one-time-token URL like http://127.0.0.1:5317/?token=… — open it
to manage secrets (write-only), edit rules with live static-validation
warnings and a matcher dry-run, edit config, and browse the redacted audit
log. The token dies with the process; every API call needs it, mutations
require same-origin application/json requests, and no endpoint can ever
return a secret value. Do not port-forward it. Design & threat model:
docs/web-config-ui-design.md.
Credential proxy (M3)
For high-sensitivity API tokens, prefer not landing the secret in env at
all. Declare a proxy in config.yaml:
proxies:
- id: stripe
upstreamHost: https://api.stripe.com
secretRef: STRIPE_KEY # registry name or full ref
headerTemplate: "Authorization: Bearer ${value}"
Then shell_proxy_start { "id": "stripe" } → { port, expiresAt }, and
commands call http://127.0.0.1:<port>/v1/charges instead of
https://api.stripe.com/v1/charges. The proxy injects the header in
memory only and auto-stops after its TTL (default 300s). Audit records the
host and secret name, never the header value.
Boundaries: http:///https:// upstreams only (proxy→upstream TLS is
properly validated; no CONNECT tunneling, no TLS termination); the
client→proxy leg is plaintext on 127.0.0.1, which inherits the same-UID
local-process boundary from the threat model.
Persistent sessions (M2)
shell_session_open spawns a long-lived shell with the matched rule's
secrets injected at creation. The session is recycled after an idle TTL
(defaults.sessionTtlSeconds, default 900s, overridable per rule via
ttlSeconds or per call) — when the process dies, the secrets die with it.
shell_session_revoke kills a possibly-compromised session immediately and
rebuilds one without any secrets.
Sessions use a real PTY via node-pty
(an optional dependency — native build, needs Xcode CLT on macOS /
build-essential + python3 on Linux). If node-pty cannot be loaded or spawned,
vaultshell automatically falls back to a plain child_process shell and the
shell_session_open response says pty: false; injection and redaction
behave identically, only interactivity is degraded. Session output merges
stdout/stderr (PTY semantics) and passes through the same Redactor.
Backend support matrix
| Backend | Ref scheme | Status | Platforms | Notes |
|---|---|---|---|---|
| Encrypted file | encfile://NAME |
✅ Implemented | all | AES-256-GCM; master key from env:MASTER_KEY or macOS keychain; default |
| Local keychain | keychain://svc/acct |
⚠️ macOS only | macOS | spawns security CLI; Linux/Windows give a clear error |
| Process env | env://NAME |
✅ Implemented | all | read-only; good for CI |
| File | file://path |
✅ Implemented | all | first line; refuses permissions > 0600 |
| Inline | inline: |
⚠️ Restricted | all | plaintext in config; disabled by default, startup warning when enabled |
| 1Password | op://vault/item/field |
✅ via CLI | all | needs authenticated op CLI; read-only |
| Vault | vault://path#field |
✅ via CLI | all | needs authenticated vault CLI; read-only |
| Infisical | infisical://proj/env/KEY |
✅ via CLI | all | needs authenticated infisical CLI; read-only |
| Doppler | doppler://proj/config/KEY |
✅ via CLI | all | needs authenticated doppler CLI; read-only |
Details, per-backend setup, and how to register a plugin resolver: docs/backends.md.
Threat model
| Threat | Mitigation |
|---|---|
| Model-context leakage | Structural: values never cross the tool layer; only names and masks |
| Command output echoing secrets | Mandatory redaction (exact + URL/Base64 variants + generic patterns), fail-closed |
Agent dumping env (env, printenv, /proc/*/environ, …) |
Hard-blocked deny-list (configurable via security.dangerousCommands: extra patterns, or mode: warn to allow-with-audit) + shell_exec_blocked audit events |
Same-UID local process reading /proc/PID/environ |
OS-level limit, cannot be fully fixed; per-command injection shrinks the window. Explicit boundary. |
| Long secret residency | Per-command injection by default; sessions have idle-TTL recycling + instant revoke |
| Misconfigured rule causing inject-everywhere | rule_validate / rule_list static warnings; mergeStrategy defaults to override; requireConfirm rules demand interactive approval (fail-closed without elicitation) |
| Config files leaking | Config stores refs only, never values; inline: disabled by default; store files forced to 0600 |
Full discussion: docs/design-spec.md §7. Report vulnerabilities privately per SECURITY.md.
Data layout
~/.vaultshell/
config.yaml # main config
rules.yaml # injection rules + secret refs (refs only, never values)
secrets.enc # encrypted-file backend (0600)
audit/ # JSONL audit, redacted
VAULTSHELL_HOME overrides the data directory (used by tests).
Development
npm run build # tsc
npm test # vitest — redactor property tests, backend round-trips,
# rule matching, shell_exec end-to-end
See CONTRIBUTING.md — including the security red lines every PR must respect.
License
MIT © 2026 vaultshell contributors
vaultshell MCP questions
How do I add vaultshell MCP to Claude Code?
Run claude mcp add vaultshell -- docker run -i --rm ghcr.io/sowhati/vaultshell:0.1.2 in your terminal. Add --scope user to make it available in every project.
How do I add vaultshell MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does vaultshell MCP provide?
It exposes 16 tools, including shell_exec, secret_list, secret_set, secret_delete, secret_probe.
Does the LLM see my secret values?
No, the server guarantees that secret plaintext never reaches the model context, tool responses, logs, or audit records.
How are secrets injected into commands?
Secrets are injected into shell child processes at exec time based on rules, and values go straight into the child process env without passing through the tool layer.
What happens if the redactor fails to hide a secret?
The system is designed to fail-closed, meaning the output is discarded rather than being returned in its raw form.