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
- Building and publishing releases
- Specification
- Canonical Darkbox 1.0.0 README, copied byte-for-byte to the archive root as
README.md - 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.
brew 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 . --lockedRun make release from a clean main checkout. It proposes the next software version, prepares Cargo metadata, asks which specification versions to publish, runs the checks, then confirms a release commit, annotated tag and atomic push. GitHub Actions tests and packages all three platforms, signs and notarizes macOS, builds native Arch packages for both Linux architectures, publishes the complete release, updates the Illegal Studio Homebrew tap and notifies its pacman repository. See release setup and recovery for credentials and the independent software/specification version policy.
The 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. This version of the specification is identified by darkbox.version = "1.0.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.