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.

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
• Session Caching: Passphrase cached securely via OS keyring (15-minute TTL)
• Git Integration: Automatic commits and optional sync with Git repositories
• MCP Server: Built-in Model Context Protocol server for AI agent access (stdio and HTTP)
• Cross-Platform: Works on macOS, Linux, and Windows

Installation

go install github.com/OpenPass/openpass@latest

Or build from source:

git clone https://github.com/OpenPass/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 set github
# Username (optional): myuser
# Password: mysecretpassword
# URL (optional): https://github.com

Or non-interactive:

openpass set github.password --value "mysecretpassword"

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:

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 lock     # clear cached passphrase

Git operations

OpenPass automatically commits changes. Manual sync:

openpass git status
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.

# ~/.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

Option	Default	Description
vaultDir	~/.openpass	Default vault directory
defaultAgent	default	Default MCP agent profile
sessionTimeout	15m	OS keyring cache TTL

Agent Profile Options

Option	Description
allowedPaths	Path patterns the agent can access (glob patterns, * for all)
canWrite	Whether the agent can create/update/delete entries
approvalMode	none (allow all), deny (reject writes), prompt (degrades to deny in MCP)

Vault Config Options

Option	Description
path	Vault directory path
default_recipients	Default age recipients for new entries

Git Config Options

Option	Default	Description
auto_push	true	Automatically push after commit
commit_template	"Update from OpenPass"	Commit message template

MCP Config Options

Option	Default	Description
port	8080	HTTP server port
bind	127.0.0.1	Bind address
stdio	false	Enable stdio transport
httpTokenFile	auto	Bearer token file path

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

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

Feature	OpenPass	pass (zx2c4)
Encryption	age	GPG
Session caching	OS keyring	gpg-agent
Entry format	Individual files	Individual files
Git support	Built-in	Via hooks
MCP server	Built-in (stdio + HTTP)	No
Password generation	Built-in	External tools

Dependencies

• Go 1.24 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 backups of your vault.