mattcreigh/ghostsecretsvault repository overview

⁠ghostSecretsVault

ghostSecretsVault is a secret management vault that keeps credentials encrypted on disk and delivers them to CLI users, Docker containers, and AI agents strictly inside process memory.

⁠Overview

Storing plain text credentials in environment files or writing unencrypted temporary files to disk exposes sensitive keys to unauthorized access. ghostSecretsVault solves this by decrypting secrets directly into process memory and passing them safely to your applications without ever writing plain text to the filesystem. Using this project allows you to securely manage passwords, container environment variables, and agent tools from your terminal without running a complex cloud server.

⁠Key Features

• Secrets remain encrypted at rest on disk using SOPS and age encryption.
• Decrypted credentials exist exclusively in process memory and never touch the filesystem.
• The restricted Docker proxy injects secrets directly into container environments upon creation.
• AI agents access secrets through opaque lease handles rather than reading raw credentials.
• Every secret access and modification creates a hash-chained audit log entry.
• Built-in staleness tracking alerts you when credentials pass their defined rotation schedule.

⁠Quick Start

⁠Prerequisites

• Python version 3.12 or higher
• sops binary installed on your system PATH
• age binary installed on your system PATH

⁠Installation

uv pip install 'ghostSecretsVault[mcp]'

⁠Initialization & Launch

gsup init

gsup daemon

⁠Usage Example

Store a secret interactively in the vault:

gsup set DB_PASSWORD

Enter value for DB_PASSWORD: 
Re-enter value for DB_PASSWORD: 
Stored secret 'DB_PASSWORD' in ghostVault.toml

Retrieve the stored secret directly into your system clipboard without displaying it on screen:

gsup get DB_PASSWORD --clip

Copied DB_PASSWORD to clipboard.

⁠Configuration

⁠How It Works

graph TD
    User([User / CLI]) -->|gsup get / set| Vault[ghostSecretsVault]
    Container([Docker Container]) <--Injects env secrets-- Proxy[Docker API Proxy]
    Proxy <--> Vault
    Agent([AI Agent]) <--Opaque lease handles-- Broker[MCP Broker]
    Broker <--> Vault
    Vault <-->|Process Memory Only| Disk[(ghostVault.toml Encrypted File)]

This diagram shows how users, containers, and AI agents interact with ghostSecretsVault. The vault manages all credentials strictly inside process memory and safely delivers them to each consumer without writing plain text to disk.