seeqbox
Encrypted, versionable data for your applications.
seeqbox is a Python library and CLI for keeping private application data in Git. It encrypts files and their names/metadata with age. Git stores ciphertext; private keys live elsewhere. An optional seeqret adapter supplies age identities.
Status: experimental. Real age integration tests cover recovery, tampering, conflicts, and Git staging. The implementation has not undergone an independent security audit. Start with synthetic data and test your recovery process before entrusting important records to it.
What it does
- Python API:
put,get,list,delete,update,verify, androtate. - CLI: initialize, seal/unlock a working directory, inspect, and verify a vault.
- Encrypted manifest hides logical filenames, metadata, and plaintext hashes.
- Random object filenames; unchanged objects retain their ciphertext.
- Multiple native age recipients, including a separate recovery identity.
- Atomic manifest replacement, exclusive writer lock, and stale-copy checks.
- Optional keyless pre-commit check against accidentally staging working data.
- No Python runtime dependencies; age is a separate, required executable.
It does not commit or push automatically. It is not a database engine, sync service, browser SDK, or clinical application. See the security model.
Install
Requires Python 3.12+ and age / age-keygen on PATH. Tested locally with age
1.3.2. Use the official age downloads.
python -m pip install seeqbox
seeqbox --version
age --version
Releases are on PyPI; the changelog lists what each one changed. To work on seeqbox itself, clone the repository and install it editable:
git clone https://github.com/thebjorn/seeqbox.git
cd seeqbox
python -m pip install -e ".[dev]"
Quick start (PowerShell)
Run this in a separate application project, not the seeqbox source checkout.
Create a key outside the repository. Back it up separately, or add an offline
recovery recipient. Substitute your actual public recipient for age1....
# Choose an existing private directory outside the repository.
age-keygen -o C:\private\seeqbox-identity.txt
$env:SEEQBOX_IDENTITY = 'C:\private\seeqbox-identity.txt'
seeqbox init -r age1...
Before adding data, put these rules in the application's .gitignore:
/data/
/.seeqbox-state.json
*.key
.env
Keep all private identities outside the repository regardless of extension.
Ignore rules do not remove files already tracked by Git. This source repository
also ignores /vault/ to prevent committing development fixtures; your consuming
application should track its encrypted vault/ directory.
New-Item -ItemType Directory data
Set-Content data\example.txt 'Only synthetic sample data'
seeqbox seal data
seeqbox verify
git add vault .gitignore
seeqbox check-staged --workdir data
git commit -m 'Store encrypted dataset'
git push
On another authorized machine, clone the app repository, configure an identity, and restore:
$env:SEEQBOX_IDENTITY = 'C:\private\seeqbox-identity.txt'
seeqbox unlock data
The destination contains plaintext. Protect it with OS permissions and disk
encryption. Include generated reports, notebook outputs, logs, and exports in
your project's privacy policy too; the staging guard is scoped to data/ and
vault/, not arbitrary copies elsewhere.
Global options precede the command:
seeqbox --vault private-vault --identity C:\private\identity.txt verify
Python API
from seeqbox import FileIdentity, Vault
# One-time initialization uses public keys only:
# Vault.create("vault", ["age1..."])
vault = Vault("vault", FileIdentity("C:/private/seeqbox-identity.txt"))
vault.put("observations/sample.json", b'{"example": true}', {"source": "synthetic"})
content = vault.get("observations/sample.json")
entries = vault.list() # decrypted names and metadata: do not log sensitive values
vault.verify()
# Batch updates become visible together through one manifest replacement.
vault.update({"one.txt": (b"one", {}), "two.txt": (b"two", {})})
Names are portable relative paths. Metadata is any JSON object. put returns
False for an unchanged object. A Vault is a snapshot: reopen it after another
writer commits a change. Errors are SeeqboxError, IntegrityError, and
ConflictError. See format v1 for interoperability and recovery.
Using seeqret
The optional adapter fetches native age identity text, not a seeqret NaCl key. Store it through your normal secure seeqret workflow. The adapter passes it to age on stdin, not in process arguments or a temporary plaintext identity file.
from seeqbox import SeeqretIdentity, Vault
vault = Vault("vault", SeeqretIdentity("AGE_IDENTITY", app="seeqbox", env="local"))
# Install the optional adapter from the seeqbox source checkout:
python -m pip install -e '.[seeqret]'
# Then, from the consuming application project:
seeqbox --seeqret-key AGE_IDENTITY verify
A custom IdentityProvider can supply other key stores.
The provider runs trusted code and has access to private identity material.
Changes, deletion, and recipients
seal dataimports files. A missing file is a conflict, not an implicit deletion. Useseal data --pruneto explicitly remove missing entries.unlock datarefreshes an unchanged working copy. It refuses to overwrite local modifications or unrelated files and removes only unchanged managed files that were deleted from the manifest. Preserve and reconcile conflicting edits yourself.- Concurrent Git branches can conflict on
manifest.age. Version 0.1 does not merge encrypted manifests. Restore both versions separately and reconcile locally. seeqbox recipients -r age1... -r age1...replaces the recipient set and re-encrypts all current objects. Include every intended recipient, including recovery.- Removing a recipient cannot revoke old ciphertext, historical commits, or copies. Old blobs remain deliberately; no automatic garbage collection is implemented.
Git hook
Add this to your existing pre-commit hook, or use it as .git/hooks/pre-commit
(make it executable on Unix):
#!/bin/sh
exec seeqbox check-staged --workdir data
The guard reads staged bytes, rejects plaintext workdir files, unexpected
vault paths, private-key markers in configuration, and missing age headers.
An age header is not proof of valid encryption. Run verify with your private key
before pushing. Hooks are bypassable and do not replace review of staged changes.
Limits and development
Objects are limited to 64 MiB and the encrypted manifest to 16 MiB. Encryption and directory operations buffer data in memory; use small datasets initially. For a live SQLite database, create a consistent snapshot with SQLite's backup API before sealing. Raw filesystem copies of active databases are not supported.
python -m pip install -e '.[dev]'
python -m pytest -q
rainbow-fmt check src tests
python -m build
Tests generate temporary identities and use exclusively synthetic data. CI tests Windows, Linux, and macOS. Future work includes streaming large objects, structured merge tooling, and JavaScript bindings to the documented format.
Contributing
- Fork it
- It is appreciated (but not required) if you raise an issue first: https://github.com/thebjorn/seeqbox/issues
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature'), after running the checks listed above and adding a line to theUnreleasedsection of CHANGELOG.md - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
MIT licensed. The generated project icon is in assets/icon.png.
Metadata
Release files for seeqbox 0.1.1
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 |
|---|---|---|---|---|
| seeqbox-0.1.1.tar.gz | 575.7 kB | With provenance | Details for seeqbox-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| seeqbox-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for seeqbox-0.1.1-py3-none-any.whl |
Total release size: 595.6 kB
Release files / seeqbox-0.1.1.tar.gz
| Download URL | seeqbox-0.1.1.tar.gz |
|---|---|
| Size | 575.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da9bb14369719d84688ff6e7bc857fe9158b8e2c4ac42e302225cb08de0e7bc9
|
|
BLAKE2b-256 checksum How to use checksums |
f884700b023a7c59e3ff35bcd49d60d6cedc5f95edc8d0978739a880af8d7231
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / seeqbox-0.1.1-py3-none-any.whl
| Download URL | seeqbox-0.1.1-py3-none-any.whl |
|---|---|
| Size | 19.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81b555bd9d756addb83f69b6d0e0d5e6a88c9d39976505bc53c2c7cc2ed415bc
|
|
BLAKE2b-256 checksum How to use checksums |
d674a824e70b0a2dbd17f7e978e9d77b478ac164edcd1ffae13e9c1265b947b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for seeqbox 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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for seeqbox-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA 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.