Skip to main content

seeqbox secure storage cube

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: 0.1.0, 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, and rotate.
  • 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 data imports files. A missing file is a conflict, not an implicit deletion. Use seal data --prune to explicitly remove missing entries.
  • unlock data refreshes 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

  1. Fork it
  2. It is appreciated (but not required) if you raise an issue first: https://github.com/thebjorn/seeqbox/issues
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Commit your changes (git commit -am 'Add some feature'), after running the checks listed above and adding a line to the Unreleased section of CHANGELOG.md
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request

MIT licensed. The generated project icon is in assets/icon.png.

Metadata

Release files for seeqbox 0.1.0

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

Source distribution (sdist)

Source distribution for seeqbox 0.1.0
File Size Uploaded Provenance Actions
seeqbox-0.1.0.tar.gz 572.1 kB With provenance Details for seeqbox-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 591.8 kB

Release files / seeqbox-0.1.0.tar.gz

Download URL seeqbox-0.1.0.tar.gz
Size 572.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2b64dd7439af15db27fdb145709c4e467a2a051e1a77e3dc000ee56afeb69e8e
BLAKE2b-256 checksum
How to use checksums
ee9c0ce5be4d036b60f8abe28cd39bc7a4db3537db04169d7b81d622953c503e
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 log

Release files / seeqbox-0.1.0-py3-none-any.whl

Download URL seeqbox-0.1.0-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c8363dda6fde4eb87466633c99fb73f3843b6ed468cabe40ec11e26a9cdf10f3
BLAKE2b-256 checksum
How to use checksums
d133bdf70735b1feb1bd7a831e937801531a561e3a4417ae64e9d501b2596ec3
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 log

Security for seeqbox 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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for seeqbox-0.1.0.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 log

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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