OpenPass

OpenPass

A modern, secure command-line password manager written in Go. OpenPass uses age for encryption and provides an intuitive CLI interface for managing your secrets — with built-in MCP server support for AI agent integration.

Safety Notice

OpenPass manages sensitive secrets. Use it at your own risk, keep tested backups of your vault, and verify recovery before relying on it for critical credentials.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, code style guidelines, testing requirements, and the PR process.

Code of Conduct

Please read our Code of Conduct before participating in our community.

Features

• Modern Encryption: Uses age (X25519 + ChaCha20-Poly1305) instead of GPG
• TOTP Support: Store TOTP secrets alongside passwords, generate codes on the fly
• Clipboard Auto-Clear: Copies to clipboard with automatic clearing after timeout
• Session Caching: Passphrase cached securely via OS keyring (15-minute TTL)
• Git Integration: Automatic commits and optional sync with Git repositories
• Multi-User Vaults: Manage age recipients for shared vault access
• MCP Server: Built-in Model Context Protocol server for AI agent access (stdio and HTTP)
• Cross-Platform: Works on macOS, Linux, and Windows

Installation

Homebrew:

brew tap danieljustus/openpass
brew install --cask openpass

Go:

go install github.com/danieljustus/OpenPass@latest

Or build from source:

git clone https://github.com/danieljustus/OpenPass
cd OpenPass
go build -o openpass .
mv openpass ~/bin/

Quick Start

Initialize a new vault

openpass init
# or specify a custom location
openpass init ~/my-vault

This creates:

• identity.age — Your encrypted age identity file
• config.yaml — Vault configuration
• Git repository initialized for sync

Add a password

Interactive mode:

openpass add github
# Username (optional): myuser
# Password: mysecretpassword
# URL (optional): https://github.com

Or non-interactive:

openpass set github.password --value "mysecretpassword"

With TOTP:

openpass add github --totp-secret JBSWY3DPEHPK3PXP --totp-issuer GitHub

Retrieve a password

openpass get github
# Path: github
# Modified: 2025-01-15 14:32
#
# password: mysecretpassword
# url: https://github.com
# username: myuser

Get a specific field:

openpass get github.password
# mysecretpassword

Copy to clipboard (auto-clears after 45 seconds):

openpass get github.password --clip

List entries

openpass list
# or filter by prefix
openpass list work/

Search entries

openpass find mybank

Generate secure passwords

openpass generate
# xK9#mP2$vL7@nQ4

# With specific length
openpass generate --length 32 --symbols

# Generate and store directly
openpass generate --store newaccount.password --length 20 --symbols

Edit an entry

Opens the decrypted entry in $EDITOR:

openpass edit github

Delete an entry

openpass delete github

Session management

openpass unlock   # unlock vault and cache passphrase
openpass unlock --ttl 15m   # override sessionTimeout for this session
openpass lock     # clear cached passphrase

Manage recipients

For multi-user vaults, manage who can decrypt entries:

openpass recipients list
openpass recipients add age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
openpass recipients remove age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

Git operations

OpenPass automatically commits changes. Manual sync:

openpass git log
openpass git pull
openpass git push

MCP Server

OpenPass can act as an MCP server so AI agents can securely read (and optionally write) vault entries.

Stdio mode (recommended for local agents)

openpass serve --stdio --agent claude-code

Use openpass mcp-config to generate a ready-to-paste config snippet:

openpass mcp-config claude-code
# Outputs JSON for stdio mode

openpass mcp-config claude-code --http
# Outputs JSON for HTTP mode (includes bearer token)

HTTP mode

openpass serve --port 8080

The server listens on 127.0.0.1:8080 by default. Bearer token auth is auto-generated on first start and stored at <vault>/mcp-token. Agents are identified per-request via the X-OpenPass-Agent header.

Agent configuration

Built-in profiles (default, claude-code, codex, openclaw, opencode) are available out of the box. Add custom agents in ~/.openpass/config.yaml:

agents:
  claude-code:
    allowedPaths: ["*"]
    canWrite: true
    approvalMode: none   # none | deny | prompt

  readonly-agent:
    allowedPaths: ["work/", "personal/"]
    canWrite: false
    approvalMode: deny

approvalMode values:

• none — all operations allowed
• deny — write operations rejected
• prompt — degrades to deny in MCP context (no interactive stdin)

Configuration

Environment Variables

• OPENPASS_VAULT — Path to vault directory (default: ~/.openpass)

Or use the --vault flag to override for any command:

openpass --vault ~/work-vault get aws.secret

config.yaml

Global config is stored at ~/.openpass/config.yaml. Vault-specific config is stored in the vault directory. Use config.yaml.example as a commented starting point.

# ~/.openpass/config.yaml — Global configuration

# Default vault directory
vaultDir: ~/.openpass

# Default agent for MCP (can be overridden via --agent flag)
defaultAgent: default

# Session timeout for OS keyring cache (default: 15m)
sessionTimeout: 15m

# Agent profiles for MCP server
agents:
  default:
    allowedPaths: ["*"]
    canWrite: false
    approvalMode: none
  claude-code:
    allowedPaths: ["*"]
    canWrite: true
    approvalMode: none
  # Add custom agents as needed

# Vault-specific configuration (optional, can also be in vault/config.yaml)
vault:
  # Path to vault (default: ~/.openpass)
  path: ~/my-vault
  # Default recipients for new entries (age recipients)
  default_recipients:
    - age1...

# Git configuration
git:
  # Auto-push changes after commit (default: true)
  auto_push: true
  # Commit message template
  commit_template: "Update from OpenPass"

# MCP server configuration
mcp:
  # HTTP server port (default: 8080)
  port: 8080
  # Bind address (default: 127.0.0.1)
  bind: 127.0.0.1
  # Enable stdio mode (default: false)
  stdio: false
  # HTTP bearer token file path (default: auto in vault dir)
  httpTokenFile: auto

Config Options

Agent Profile Options

Vault Config Options

Git Config Options

MCP Config Options

Clipboard Config Options

Vault Structure

~/.openpass/
├── identity.age      # Encrypted age identity
├── config.yaml       # Vault configuration
├── mcp-token         # Bearer token for HTTP MCP (auto-generated)
├── entries/          # Encrypted password entries
│   ├── github.age
│   └── work/
│       └── aws.age
└── .git/             # Git repository

Vaults created with the pre-beta root-level entry layout are migrated to entries/ on open. Root-level encrypted entries remain readable and listable for compatibility.

Each entry is an individually encrypted YAML file:

# Decrypted contents of an entry
password: mysecret
username: myuser
url: https://example.com
notes: Additional info

Security

• age encryption: X25519 key exchange + ChaCha20-Poly1305
• Passphrase never stored in plain text
• Session passphrase cached via OS keyring (15-minute TTL)
• All entries individually encrypted — each .age file is self-contained
• Git history contains only ciphertext
• HTTP MCP server bound to 127.0.0.1 by default; bearer token required

Comparison with pass

Dependencies

• Go 1.25 or later
• filippo.io/age — encryption
• spf13/cobra — CLI framework
• zalando/go-keyring — OS keyring integration

License

MIT License

Acknowledgments

• Inspired by pass from zx2c4
• MCP protocol support via a local fork of mark3labs/mcp-go

Disclaimer

Use at your own risk. Always keep tested backups of your vault.