The post-apocalyptic file format.
ZIP container · SQLite databases · JSON manifest · Included documentation
A universal specification and an offline verification tool for project files, designed to keep your work understandable and accessible even when the application that created it is no longer available.
The common specification governs packaging and metadata. Application profiles define their own database schemas, resource conventions, data versions and migrations. Applications keep their own filename extensions. Darkbox does not require applications to share a data model.
Darkbox was conceived by Vincenzo Petrucci as a common project-file format for software developed by Illegal Studio. It is a universal specification that other applications can also adopt.
A person's work should remain accessible beyond the lifetime of the software used to create it. Darkbox aims to make project files understandable and recoverable with documented, widely available tools, even when the original application is no longer available. Documentation travels with each file to help preserve the knowledge needed to interpret its contents.
Closed, undocumented formats can make people dependent on a particular application or vendor to access their own work, limiting their freedom to inspect, preserve, move and reuse what they have created. Darkbox is built on the principle that users' rights over their own creations should not depend on the continued existence of the software used to make them.
Preserving data also means preserving how to decode it. Every archive carries three levels of documentation: the Darkbox README for the container, the original SQLite file-format reference for the database's physical bytes, and the application profile for the meaning of its tables, records and resources. That knowledge travels with the project so it can remain useful beyond the software and websites that originally explained it.
- Rust CLI: installation, commands and reports
- Rust SDK: reading, editing, SQLite, protection and atomic saving
- Low-level library: verification, extension registration and progressive creation
- Offline causal synchronization
- Specification
- Canonical Darkbox 1.5.0 README, copied byte-for-byte to the archive root as
README.md - Selective protection extension 1.0.0, with its schema and interoperable test vectors
- Original SQLite file-format reference, included with its source and distribution notes
- Manifest JSON Schema, using JSON Schema Draft 2020-12
- Canonical bundle catalog schema
- Example manifests for two fictional application profiles
- Application profile guidance
The darkbox binary verifies and inspects archives offline. SQLite and all supported Darkbox references are included; the original application is not required.
darkbox verify example.project
darkbox inspect example.project
darkbox verify example.project --json
darkbox versionsVerification checks common container rules, the exact canonical documentation and SQLite snapshots offline. It reports application-profile semantics as unchecked; passing these common checks does not certify full application conformance. Inspection reports metadata without certifying conformance. See the CLI documentation for reports, exit codes, resource limits and binary packages.
Darkbox 1.1.0 supports selective AES-256-GCM encryption of individual attachments and BLOB values in ordinary SQLite databases. Its official required protection extension signs the exact manifest with Ed25519 and inventories every payload file with SHA-256. Public information remains readable. Applications supply trusted signer keys and decryption keys; missing decryption keys leave protected content locked without marking it corrupt. Earlier published versions remain supported with their unchanged canonical bundles.
Darkbox 1.2.0 also supports quiescent directory libraries and incremental backup
transfers. pack and unpack preserve every file byte; delta, verify --base
and merge bind exact base and target editions. Optional unsigned inventories,
--limits large, explicit staging storage and seekable STORE media access support
large libraries. See the CLI workflows
and Rust APIs.
Darkbox 1.3.0 defines an interoperable live-directory lock and a distinct
not_quiescent outcome. The Rust SDK initializes and seals libraries directly,
backs up active SQLite connections, and creates deltas without a complete target
ZIP. Application-trusted immutable-resource digests are explicit in reports.
See live storage.
Darkbox 1.4.0 adds HotCapture: snapshot databases, metadata and the resource
listing under a short application write barrier, then stream a backup or delta
while the application resumes work. Captured resources remain retained and
immutable until completion. See short capture barriers.
Software 1.4.2 creates new ZIP exports without persistent sibling lock files. Existing ZIP replacements and live directory libraries retain writer coordination; see SDK publication and locks.
Darkbox 1.5.0 adds the required-when-present synchronization extension 1.0.0. Applications keep local live libraries and exchange immutable causal transactions, resources and complete checkpoints through a separate cloud folder. Concurrent field alternatives, set changes, deletions and ordering have explicit merge rules. The SDK supplies transactional queues, replay, scanning, compact checkpoints and membership-free bounded retention with application-owned projection adapters. Old installations preserve unpublished edits in private recovery packages before rebase. See synchronization for integration, plaintext security mode and retention limits.
Software 1.6.0 adds owning sync sessions, receipt without rereading applied media, and explicit bounded verification reuse for private immutable object stores. It retains common specification 1.5.0 and sync protocol 1.0.0 unchanged.
Software 1.6.1 supports sync publication on Unix mounts without hard links or no-replace rename when directory advisory locking and atomic rename are available. See sync filesystem requirements.
Add the published darkbox crate to your project:
[dependencies]
darkbox = { version = "1.6.2", default-features = false }This selects the SDK without the CLI or extended JSON precision. Enable
exact-numbers explicitly if the application needs arbitrary JSON numbers;
otherwise unsupported precision is reported instead of silently rounding values.
See embedding the SDK for features, SQLite and integration examples.
To compile and install the CLI through Cargo, with Rust 1.88 or later and a C compiler:
cargo install darkbox --lockedbrew install illegalstudio/tap/darkboxEnable the Illegal Studio pacman repository by adding this section to /etc/pacman.conf:
[illegalstudio]
SigLevel = Optional TrustAll
Server = https://illegalstudio.github.io/pacman/$archThen install Darkbox together with a full system update:
sudo pacman -Syu darkboxThe repository serves x86-64 and ARM64 packages. Packages follow its existing unsigned distribution policy and preserve Darkbox's dependency notices.
mise use -g github:illegalstudio/darkboxTo pin a software version, use mise use -g github:illegalstudio/darkbox@1.0.0.
Download the package for your platform from GitHub Releases, together with its .sha256 file. Replace <version> with the CLI software version.
| Platform | Package |
|---|---|
| Linux x86-64 | darkbox_<version>_linux_amd64.tar.gz |
| Linux ARM64 | darkbox_<version>_linux_arm64.tar.gz |
| macOS ARM64 (Apple Silicon) | darkbox_<version>_darwin_arm64.zip |
Check the download with sha256sum -c <package>.sha256 on Linux or shasum -a 256 -c <package>.sha256 on macOS. Extract the package and put its darkbox executable in a directory on your PATH. Linux packages require glibc 2.35 or later; macOS packages target macOS 11 or later. Packages include documentation and dependency license notices.
With Rust 1.88 or later and a C compiler:
cargo install --path . --lockedThe entire archive/<darkbox.version>/ directory is the canonical documentation bundle for that version. Copy all its contents into the ZIP root, preserving every relative path and file's bytes. Do not add an enclosing archive/ or version directory inside the ZIP. Then add the manifest, application profile documentation, databases and resources at their declared paths.
For version 1.0.0, the bundle contains the canonical README, its SHA-256 catalog, and the captured SQLite documentation under docs/sqlite/, including its local presentation assets and upstream public-domain notice. Select the directory matching the declared version, rather than automatically using the newest bundle or fetching current SQLite pages while saving a project.
Published version directories are retained unchanged. Each release provides the matching specification and manifest schema together with its complete canonical bundle. Darkbox-authored text uses LF; .gitattributes protects both its line endings and the exact captured upstream bytes from checkout conversion.
Versioned specifications are retained in specification/<version>.md and manifest schemas in schema/<version>/. The main documentation links show the current version; the CLI selects references by the exact declared version.
example.project
├── manifest.json
├── README.md
├── docs/
│ ├── profile.md
│ ├── darkbox/bundle.json
│ └── sqlite/ # complete canonical SQLite reference bundle
└── data/
└── project.sqlite
Darkbox fixes its root metadata names and canonical bundle paths. Other database and folder paths are declared in the manifest. Required application.profilePath locates the included application data-format documentation; docs/profile.md is a recommended path. Attachments may remain database BLOBs or become separate files, as defined by a profile.
The specification version, application data-format version and optional creator-software version are independent. The current specification is identified by darkbox.version = "1.5.0". Application profiles define their own data-format versions.
The Rust implementation, specification, schema, Darkbox-authored documentation, examples and Darkbox logo assets are licensed under the MIT License. The original SQLite materials retain their upstream terms, recorded in the included SQLite copyright notice and source notes. The license does not change ownership or licensing of project data packaged by applications. The canonical README includes the full MIT notice so it travels with distributed files. Permission to modify Darkbox materials does not alter conformance requirements, including the exact canonical bundle.