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:
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 duringgetandexport. edit,get,set,export,info,validate,unlock,lock,rekey, and explicit v1-to-v2upgradecommands.- 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
- Usage guide
- File-format reference
- Internals and security model
- Engineering case study — Architecture evolution, design decisions, trade-offs, and interoperability.
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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xvault-0.1.0.tar.gz | 42.8 kB | Without provenance | Details for xvault-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xvault-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for xvault-0.1.0-py3-none-any.whl |
Total release size: 70.4 kB
Release files / xvault-0.1.0.tar.gz
| Download URL | xvault-0.1.0.tar.gz |
|---|---|
| Size | 42.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0fcc8c893a70453d07b16438b8f79873170dce20f02dc14478702f9587ea4ca8
|
|
BLAKE2b-256 checksum How to use checksums |
705f8617c7e13341f25454bbb452b470ea3e6ea4750a4e1e07771a122484c74a
|
| 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.0-py3-none-any.whl
| Download URL | xvault-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc772a7e206c0517e1396badec5e52ecffb4c34f561087b5e5840636522e269e
|
|
BLAKE2b-256 checksum How to use checksums |
85cec50b863c5d42a8766c9bb14a657d1575804d1efcc17c2ed43c359780b20d
|
| 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.0
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.