reVault is a fast, local toolkit for creating secure portable archives called Lockboxes. Each Lockbox is encrypted, compressed, and signed. It can store:

Lockboxes are easy to copy, share, and back up, and they do not require a hosted service. The engine is designed for speed and effective compression. Applications can read, write, and seek within stored files without extracting the archive, and recover data from partial corruption.

Read the reVault manual for the quick start, core concepts, and security model.

The project goals state reVault's purpose and priorities. Contributors should use the v4 work entry point to locate the implementation branch and its plan, and the documentation map to find maintained references.

reVault runs on Linux, macOS, and Windows. You can use it through the command line interface or through libraries for supported programming languages.

A Lockbox is a portable archive with the .lbox extension.

A key or password controls who can open a Lockbox.

A Vault stores local profiles, contacts, keys, and remembered access to Lockboxes.

Pre-release: the Rust implementation is currently alpha software. The archive format and public APIs may change between releases. Do not use it as the only copy of important data, and keep vault backups and profile recovery material offline.

The best way to start with reVault is to install the CLI tooling.

The easist way to install the reVault CLI is from crates.io

cargo install revault_cli

repo

You can also install the CLI by cloning the github repo.

git clone https://github.com/onepub-dev/reVault.git cd reVault/rust cargo xtask install-cli cargo xtask dev-tools

Initialise your vault

In order to create a lockbox you must first initialise your Vault.

When you install the reVault CLI, Cargo installs both lockbox app and its alias lbx into ~/.cargo/bin. Ensure that directory is on your PATH.

cargo xtask dev-tools installs revault-tool, the repository developer command hub. Run revault-tool --help to see release preparation/publication, binding generation and checks, conformance tests, and the dev commands that wrap repository validation tasks.

lbx vault init

The init command will create the keys need to create/open and close lockboxes. The keys are stored in your reVault vault.

The init command will also dump those keys to the terminal. You need to backup those keys safely.

Create a lockbox for the default vault profile: (recommended)

lockbox secrets.lbox create

For a lockbox protected by a passphrase instead of a vault profile:

This form is less secure than using a profile.

lockbox secrets.lbox create --password

Open it for normal commands:

lockbox secrets.lbox open

Persistent directory mirrors

A mirror project records a one-way relationship between a host directory and an exclusively managed directory inside the lockbox. The project definition, including its include and exclude rules, is encrypted inside the lockbox and travels with it.

lbx secrets.lbox mirrors source create --from ./src --to /projects/source lbx secrets.lbox mirrors source rules add exclude target/** '*.tmp' lbx secrets.lbox mirrors source status lbx secrets.lbox mirrors source update

status previews the complete plan; update recalculates and applies it. Multiple projects can coexist when their destination directories do not overlap. See the CLI guide for ownership, deletion, rule, and safety details.

The open is cached in a per-user in-memory agent which will automatically close it after about 30mins. Lock it when you are done:

lockbox secrets.lbox add --recursive ./project --to project/ lockbox secrets.lbox add ./generated.env --to secrets/prod.env

List and extract:

lockbox secrets.lbox list / lockbox secrets.lbox list '/project/**/*.rs' lockbox secrets.lbox extract /project/README.md ./out/README.md

See docs/cli_how_to.md for command-focused examples.

lockbox vault profiles create laptop

Create an independent encrypted vault with a fresh profile and register that profile's public key as a contact in the current vault:

lbx vault beget production

Creates production.vault.lbx with profile:production.

Saves only the public key locally as contact:production.

lbx access grant shared.lbox contact:production

Use --output to choose the new vault path, --contact-name to avoid a local contact-name collision, or --no-contact to leave the current vault unchanged. beget never grants lockbox access automatically and never copies private material from the current vault.

lockbox vault profiles list lockbox vault profiles export ./laptop.pub --name laptop

Import a contact public key after independently verifying its fingerprint:

lockbox vault contacts import alice ./alice.pub
--fingerprint <fingerprint>
--fingerprint-channel phone-call-to-owner

Create a lockbox for a recipient:

lockbox shared.lbox create --for alice

Grant or revoke access on an existing lockbox:

lockbox shared.lbox access grant alice lockbox shared.lbox access list lockbox shared.lbox access revoke alice

Exporting a private key is supported for backup and migration, but treat the output as a secret:

lockbox vault profiles backup ./default.profile-backup

Private vault keys are stored inside the local vault as secret variable records, not as normal files in the vault lockbox. See the CLI help and CLI how-to for vault backup and profile recovery.

Variables are encrypted metadata, not files. They do not appear in file listings and are loaded only when variable commands or APIs request them. The command group is variables.

Plain variables are for values that are useful configuration but not high-value secrets:

lockbox secrets.lbox variables set DATABASE_URL --value 'postgres://localhost/app' lockbox secrets.lbox variables set DATABASE_URL='postgres://localhost/app' lockbox secrets.lbox variables get DATABASE_URL

With a session-default lockbox, assignment syntax is also supported:

lockbox variables set DATABASE_URL='postgres://localhost/app' lockbox variables set DATABASE_URL 'postgres://localhost/app'

Secret variables are for passwords, API tokens, signing keys, and similar material. They use secure-memory handling in the variable path and must be provided through an explicit source:

lockbox secrets.lbox variables set --secret API_TOKEN --interactive lockbox secrets.lbox variables set --secret API_TOKEN --file ./api-token.txt lockbox secrets.lbox variables set --secret API_TOKEN --stdin lockbox secrets.lbox variables set --secret API_TOKEN --from-env API_TOKEN

Avoid passing secrets as command-line arguments. Shell history and process inspection can expose argv. Prefer --interactive, --stdin, --file, or --from-env.

Sensitivity is chosen when a variable is created. Updating the value preserves that sensitivity. To change plain to secret, or secret to plain, delete and recreate the variable.

Use these defaults unless you have a specific reason not to:

Lockbox protects data inside the container. It cannot protect a secret after you write it to a normal terminal, shell history, clipboard, exported file, build log, or process environment controlled by other tooling.

revault_key_server is a short-lived rendezvous service for sharing candidate contact public keys. A publisher uploads a payload, verifies their email, and shares the resulting publish code with the recipient. The recipient uses that code to receive the candidate key, then verifies its fingerprint independently before trusting it. The server does not establish profile trust and is not a store for private keys.

A first deployment uses one server with server_id = 0. Publish codes include that server id as their first digit, followed by a random code body. Using a self-routing code from the start keeps pending publishes compatible if the deployment later gains standby servers.

Servers publish a topology document containing the known server URLs and the primary/failover route for each publish-code owner id. Clients use it as follows:

DNS can provide normal host resolution, but it is not the routing mechanism. Round-robin DNS alone can send a receive request to a server that does not own the corresponding publish code.

Each server is authoritative for the codes carrying its own server id. It sends signed state events—published payloads, receive counts, payload lifecycle tombstones, and rate-limit blocks—to configured standby peers through the separate /v1/replicate endpoint. Events carry an origin server id, epoch, and sequence number, so standbys apply duplicates idempotently and never replicate received peer events again.

Replication does not make the cluster hot/hot. A standby keeps replica state but serves an owner's payloads only after an operator explicitly promotes it for that owner id. This avoids two servers consuming a single-use publish at the same time during a network partition. See the key-server deployment guide, configuration reference, and redundancy design for the deployment and recovery procedures.

Use revault_lockbox_api when you need the portable storage engine:

use revault_lockbox_api::{Lockbox, LockboxOpen, LockboxPath, LockboxProtection, SecretVec}; use std::path::Path;

let key = SecretVec::try_from_slice(b"correct horse battery staple")?; let signing_key = revault_lockbox_api::OwnerSigningKeyPair::generate()?; let mut lockbox = Lockbox::create_file( Path::new("secrets.lbox"), LockboxProtection::ContentKey(key.try_clone()?), &signing_key, )?;

lockbox.add_file(&LockboxPath::new("/docs/a.txt")?, b"alpha", false)?; lockbox.add_file(&LockboxPath::new("/docs/b.txt")?, b"bravo", false)?; lockbox.commit()?;

let reopened = Lockbox::open( Path::new("secrets.lbox"), LockboxOpen::ContentKey(&key), )?; let file = reopened.get_file(&LockboxPath::new("/docs/a.txt")?)?;

Use revault_vault_api for native applications that want the Vault and Session Agent behavior:

use revault_vault_api::{local_vault, SecretString};

let vault = local_vault(); let password = SecretString::try_from_bytes(b"pw".to_vec())?;

vault.create_lockbox_with_password("secrets.lbox", &password)?;

let lockbox = vault.open_lockbox_with_password("secrets.lbox", &password)?; let mut lockbox = lockbox; lockbox.add_file_from_path("notes.txt", &revault_lockbox_api::LockboxPath::new("/notes.txt")?)?; lockbox.commit()?;

Documentation

Performance results for Lockbox using the published pure-Rust zstd-complete 0.1.0 crate, compared with encrypted GPG and unencrypted ZIP, are documented in the benchmark report.

Follow the reVault terminology standard when updating the manual, READMEs, CLI help, API guides, or other user-facing material.

cd rust cargo fmt --all cargo check --workspace --all-targets --all-features cargo test --workspace cargo clippy --workspace --all-targets --all-features -- -D warnings

Generate Rust API docs:

cd rust revault-tool dev generate-api-docs

Release checklist

Before publishing a component:

For complete procedures, read the CLI distribution guide and the binding contribution and release guide.

reVault Source Available License 1.0 - see LICENSE.

The source remains available for inspection, modification, and redistribution. Derivative works must publish their corresponding source code in a publicly accessible repository such as GitHub or a similar service. The license also restricts third parties from offering reVault, modified reVault, or substantially similar reVault-derived functionality as a hosted, managed, or network-accessible service without a separate written license.