Skip to main content

xvault

xvault keeps secrets inline in the configuration files and Markdown notes you already use. Mark only the values that are secret, edit the file with xvault, and it stores those values as single-line ciphertext while leaving the rest of the file readable.

It is a local-first, Git-friendly tool: the same file can hold configuration, notes, and encrypted values, rather than splitting them across a vault and a separate configuration file.

Why xvault?

  • Keep a single source of truth for configuration and notes.
  • Encrypt only explicit secret markers, so ordinary diffs remain useful.
  • Work locally with a password and, optionally, the operating system keyring.
  • Export decrypted files or resolve file-local variable references when a tool needs a materialized configuration.

SOPS is a stronger fit for GitOps workflows that already use cloud KMS, PGP, or age. git-crypt is useful when whole files should be encrypted transparently. xvault instead focuses on explicit inline values in local configuration and notes.

Quick start

Install xvault:

pip install xvault

Create dev.env:

DB_HOST=localhost
DB_USER=enc:app
DB_PASS=${enc:choose-a-strong-password}
DATABASE_URL=postgres://${var:DB_USER}:${var:DB_PASS}@localhost/app

Open it with xvault and save the edit. xvault asks for a password when it needs one and writes the metadata and encrypted values on save:

xvault edit dev.env

The short demo below shows the editing workflow:

xvault edit workflow

Read a value or export a decrypted copy for a command that needs it:

xvault get dev.env DB_PASS
xvault export dev.env --resolve

Treat exported output as plaintext. See the usage guide for the complete workflow and command behavior.

Features

  • Inline enc: and ${enc:...} secret markers.
  • JSON, JSONC, YAML, ENV, Markdown, and OpenVPN configuration support.
  • Envelope encryption for new vaults: a random AES-256-GCM data key protected by an Argon2id password-derived key.
  • Optional file-local ${var:NAME} resolution during get and export.
  • edit, get, set, export, info, validate, unlock, lock, rekey, and explicit v1-to-v2 upgrade commands.
  • Optional OS-keyring cache for derived keys.

Supported formats

Verified handlers are available for .json, .jsonc, .yaml, .yml, .env, .md, and .ovpn. The detailed per-format behavior and limitations are in the file-format reference.

Documentation

CryptoV1 files remain readable and writable and are upgraded only by the explicit xvault upgrade command. New vaults use CryptoV2 envelope encryption: a password-derived key protects a random data key, and that data key encrypts the marked values. The versioned file contract is documented in the reference.

Security

xvault encrypts marked values and authenticates their ciphertext, but it does not make plaintext configuration trustworthy, protect a compromised machine, or make plaintext exports safe. Use a strong unique password and consider --no-cache-key on shared, remote, or headless systems. Read the security model and vulnerability-reporting policy.

Verification

The test suite covers CryptoV1 and CryptoV2 fixtures, password rotation, explicit migration, metadata failure handling, transactional writes, CLI behavior, and every supported handler. CI tests Python 3.12 and 3.13 on Linux, plus Python 3.12 compatibility on Windows and macOS, and validates wheel and source distributions.

Roadmap

Potential future work includes editor improvements, richer Markdown and binary workflows, more selective exports, and optional integrations. These are not implemented features or compatibility commitments.

License

xvault is released under the MIT License.

Metadata

Release files for xvault 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xvault 0.1.1
File Size Uploaded Provenance Actions
xvault-0.1.1.tar.gz 45.9 kB Without provenance Details for xvault-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xvault 0.1.1
File Interpreter ABI Platform Actions
xvault-0.1.1-py3-none-any.whl Python 3 none any Details for xvault-0.1.1-py3-none-any.whl

Total release size: 75.0 kB

Release files / xvault-0.1.1.tar.gz

Download URL xvault-0.1.1.tar.gz
Size 45.9 kB
Tags Source
SHA-256 checksum
How to use checksums
6e59046038c004b1bb7fc40ce386340c86f7920ef50695012db5e902132ff15a
BLAKE2b-256 checksum
How to use checksums
473f3a26c150d2c1bba8a57fa4e7c7d6d6b82ef10d2eee73a6813e9e15628822
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.6

Release files / xvault-0.1.1-py3-none-any.whl

Download URL xvault-0.1.1-py3-none-any.whl
Size 29.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ab926d41a469e8209d8f738e7e3cabebc9e94d66cc04cb10fbf756c19f42709b
BLAKE2b-256 checksum
How to use checksums
903c3f3bdb228acbaf168069db18296113130d4820faa1c6869d6c7957bf44d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.6

Security for xvault 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page