# vaultshell [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/SoWhatI/vaultshell  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vaultshell

## Description
Injects secrets into shell commands at exec time; plaintext never reaches the LLM context

## Tools
Capabilities this server exposes over MCP:

- **shell_exec** — Run a one-shot command with per-rule injection. Params: `command`, `cwd?`, `profile?`, `extraEnv?` (allowlist), `dryRun?`, `timeoutSeconds?` (≤3600)
- **shell_session_open** — Open a persistent session; secrets injected once at creation
- **shell_session_send** — Send a command to a session
- **shell_session_close** — Kill a session; secrets die with the process
- **shell_session_list** — List live sessions
- **shell_session_revoke** — Kill and rebuild the session **without secrets
- **shell_proxy_start** — Start a credential-injecting reverse proxy on 127.0.0.1
- **shell_proxy_stop** — Stop a proxy
- **shell_proxy_list** — List running proxies
- **secret_list** — List names + metadata (backend ref, resolvable)
- **secret_set** — Write to backend; persisted, never echoed
- **secret_delete** — Delete and unregister
- **secret_probe** — Check a ref resolves
- **rule_list** — Rules + static warnings (e.g. inject-everywhere)
- **rule_validate** — Static findings: unknown secrets, unreachable rules, inject-everywhere, union risk, requireConfirm capability
- **audit_query** — Read audit entries

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "vaultshell": {
    "command": "npx",
    "args": ["-y","github:SoWhatI/vaultshell"],
    "env": {
      "MASTER_KEY": ""
    }
  }
}
```

**Requires environment variables:** `MASTER_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What vaultshell does

The vaultshell MCP server manages references to secrets and supplies their values to child processes only when an applicable injection rule matches. Secret plaintext is not returned by MCP tools, written to logs or audit records, or included in redacted command output. Tool responses expose names, metadata, masks, and execution results instead.

Commands can run once with `shell_exec`, or through persistent sessions whose secrets are loaded when the session starts. Sessions can be closed, listed, or revoked; revocation rebuilds a session without secrets. For API credentials that should not enter a process environment, the server can also run a loopback reverse proxy that adds a configured header in memory.

## How it works

Secrets are stored through a backend and referenced by name or configured reference. Rules determine when values are injected. The launcher resolves references internally and passes values directly into the child process environment, rather than through the MCP tool layer. `shell_exec` does not accept an unrestricted environment map; its `extraEnv` option is allowlisted.

Every command result passes through output redaction. If redaction fails, the output is discarded instead of being returned. Dry runs report the selected rule, injected secret names, environment keys, and deny-list result without starting a command. Execution timeouts, output truncation, concurrency limits, and related flags are recorded in the audit log.

The local proxy accepts HTTP or HTTPS upstreams, validates TLS for HTTPS upstream connections, and does not provide CONNECT tunneling or TLS termination. Its client-to-proxy connection remains plaintext on loopback. Proxy instances have a time-to-live and expose metadata without secret values.

## Setup and configuration

Run the vaultshell MCP server with Node.js 20 or later. It can be installed with `npx`, installed globally from the GitHub repository, built from source, or run from the published Docker image. The encrypted-file backend uses a `MASTER_KEY` environment variable containing 64 hexadecimal characters. Configuration and rule files are placed under `~/.vaultshell` in the source-based setup.

A Docker deployment mounts `/home/node/.vaultshell` and passes `MASTER_KEY` to the container. The image runs as the non-root `node` user. Container sessions fall back to pipe mode because `node-pty` is excluded from the image; injection and redaction remain available.

The repository provides a Claude Desktop stdio configuration using `npx` and `MASTER_KEY`. The optional web command starts a loopback-only configuration UI with a one-time token. It supports write-only secret management, rule editing, static warnings, configuration editing, and redacted audit browsing; its URL should not be port-forwarded.

## Tools and capabilities

- Execute one-shot commands with a working directory, profile, dry-run mode, timeout, and allowlisted extra environment variables.
- Open, send commands to, list, close, and revoke persistent shell sessions.
- Start, stop, and list credential-injecting proxies bound to `127.0.0.1`.
- List, store, probe, and delete secrets without returning their values.
- Inspect rules and validate unknown references, unreachable rules, broad injection, union risk, and confirmation-related findings.
- Query audit entries containing names and redacted commands.

## Limitations and notes

The default command timeout is 120 seconds and the maximum is 3600 seconds. Output streams default to a 1 MiB limit and are truncated after redaction. At most eight concurrent one-shot executions are allowed by default, and excess calls are rejected rather than queued.

Persistent sessions normally expire after an idle period, defaulting to 900 seconds unless configuration, a rule, or a call changes it. PTY support depends on the optional `node-pty` native dependency; when unavailable, sessions use a plain child-process shell with reduced interactivity.

The proxy is limited to HTTP and HTTPS upstreams, and the loopback client connection shares the same-UID local-process boundary. The server is designed for local secret storage, so the repository does not publish a hosted Smithery distribution.

_Full upstream README: https://allmcps.com/mcp/vaultshell/readme_