Ethernity

Encrypted paper backups for small, high-value files.
Getting Started · Backup Workflow · Recovery Workflow · Format Spec · Security Policy

What It Does

Ethernity turns a small file or directory into encrypted recovery documents you can print, store, scan, and recover without network access.

A backup can include:

• qr_document.pdf: QR codes for machine recovery
• recovery_document.pdf: fallback text for manual recovery
• passphrase shard PDFs for quorum recovery
• signing-key shard PDFs for extension and mint workflows
• a browser recovery kit QR document

Use Ethernity for seed phrases, small key bundles, critical config files, and recovery packets that need a paper path. Use a normal backup system for large archives, sync, and frequent background snapshots.

Install

macOS and Linux:

brew tap minorglitch/tap
brew install ethernity
ethernity --help

Python-managed install:

pipx install ethernity-paper
ethernity --help

Windows PowerShell:

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://raw.githubusercontent.com/MinorGlitch/ethernity/master/install.ps1" -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1
ethernity --help

Verify release archives with Release Artifacts before you run a downloaded binary.

First Drill

Run this with test data before you protect anything real:

printf "ethernity test payload\n" > payload.txt

ethernity backup \
  --input ./payload.txt \
  --output-dir ./backup-demo \
  --passphrase "ethernity test passphrase"

ethernity recover \
  --scan ./backup-demo \
  --passphrase "ethernity test passphrase" \
  --output ./restored.txt

cmp ./payload.txt ./restored.txt

cmp prints nothing when the restored file matches. On Windows, use:

fc.exe /b .\payload.txt .\restored.txt

Pick A Workflow

Need	Command	Result
Create a backup set	backup	writes QR, fallback, and optional shard PDFs
Restore data	recover	restores from scans, payload text, or fallback text
Add changes to an unsealed backup	extend	writes a new generation under extensions/
Flatten root plus extensions	compact	writes a fresh standalone backup
Issue new shard PDFs	mint	writes replacement or fresh shard documents
Print the browser recovery kit	kit	writes a QR PDF for the offline kit

Other useful commands:

ethernity config --onboard
ethernity render envelope-c6 --format pdf --output ./envelope_c6.pdf
ethernity api inspect recover --scan ./backup-demo --passphrase "ethernity test passphrase"

Use ethernity <command> --help for flags.

When Files Change

Create the root backup once:

ethernity backup \
  --input-dir ./docs \
  --output-dir ./backup-root \
  --passphrase "example passphrase"

Preview an extension:

ethernity extend \
  --root-dir ./backup-root \
  --input-dir ./docs \
  --base-dir ./docs \
  --passphrase "example passphrase" \
  --dry-run

Publish the extension:

ethernity extend \
  --root-dir ./backup-root \
  --input-dir ./docs \
  --base-dir ./docs \
  --passphrase "example passphrase" \
  --shard-count 0

extend needs an explicit recovery policy. Choose extension shards with --shard-threshold N --shard-count K, reuse root shards with --unlock-policy reuse-root, or use --shard-count 0 when your policy allows plaintext passphrase fallback text.

Recover the latest state:

ethernity recover \
  --scan ./backup-root \
  --passphrase "example passphrase" \
  --output ./restored-docs

Compact the chain when you want a new standalone set:

ethernity compact \
  --root-dir ./backup-root \
  --output-dir ./backup-compacted \
  --passphrase "example passphrase"

For the full operator flow, read Extension Workflow.

Custody Basics

• Start with test data.
• Store QR documents, recovery documents, and shards in separate places.
• Keep one independent backup path outside Ethernity.
• Test the minimum shard quorum during recovery drills.
• Run a recovery drill before you trust a procedure.

Ethernity gives you recoverable artifacts. Your custody plan protects the passphrase, printed pages, shard holders, and recovery environment.

Recovery Kit

The browser recovery kit gives you an offline HTML recovery surface.

ethernity kit --output ./recovery_kit_qr.pdf
ethernity kit --variant scanner --output ./recovery_kit_scanner_qr.pdf

Use the default kit for file and paste workflows. Use the scanner variant when the browser should handle camera input.

Document Preview

Sentinel preview pages from the generated PDF set:

Supported designs: archive, forge, ledger, maritime, sentinel.

Use Template Gallery to compare them.

Docs

Operator guides:

• Getting Started
• Backup Workflow
• Extension Workflow
• Recovery Workflow
• Command Cheatsheet
• Troubleshooting
• Release Artifacts

Reference docs:

• docs/format.md: backup format specification
• docs/format_notes.md: rationale and operations notes
• docs/format_changes.md: compatibility ledger
• docs/cli_api.md: NDJSON API contract
• SECURITY.md: security policy

Development

git clone https://github.com/MinorGlitch/ethernity.git
cd ethernity
uv sync --extra dev --extra build
uv run playwright install chromium
uv run ethernity --help

Core checks:

uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pytest tests/unit tests/integration -q
cd kit
npm ci
npm test
node build_kit.mjs

Read CONTRIBUTING.md before opening a pull request.

Credits

Ethernity was inspired by Paperback by cyphar.

Mention: Rememory. Ethernity does not use Rememory code or assets.

Ethernity uses these libraries:

• age via pyrage
• PyCryptodome
• Typer
• Rich
• Questionary
• Playwright

License

GPLv3 or later. See LICENSE.

(back to top)