Vaultshell

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.