vaultspec-core

Distribution channels

Copied from vaultspec-core's own documentation, and read against the pages written here at commit f02df874. Nothing in it needed answering differently.

Install Core with Scoop on Windows or Homebrew on macOS and Linux. Both channels install vaultspec-core and vaultspec-core-mcp.

[!IMPORTANT] The MCP server executable was previously named vaultspec-mcp and is now vaultspec-core-mcp, matching the package it ships in. Upgrading replaces the old name rather than keeping both, so a script that calls vaultspec-mcp directly needs updating. Generated MCP enrollment is unaffected: it launches the server as python -m vaultspec_core.mcp_server.app, never through the executable, and the enrolled server entry is still named vaultspec-core.

You don’t need a separate Python installation on any release, and from v0.1.74 you don’t need network access either.

v0.1.74 is the first release whose binaries carry everything they run. Each one holds its own interpreter, Vaultspec and the whole dependency tree, so a first launch on an air-gapped machine behaves like any other, and every release from v0.1.74 runs its binaries with the network taken away before publishing them - in an empty network namespace on Linux, under a sandbox profile that denies the network on macOS, and with every route to a package index blocked on Windows.

Binaries up to and including v0.1.73 install Vaultspec and its dependencies from PyPI on first launch and cannot start on a machine with no network. That is a property of those releases and does not change; later launches of one that already installed run offline.

Two consequences follow from carrying everything. The downloads are larger - roughly 45 to 70 MB depending on the platform, against 20 to 40 MB when the dependencies arrived over the network instead. And the binaries do not update themselves: upgrade through Scoop or Homebrew, which is where the version they install is decided anyway.

Coverage

Platform	Architecture	Availability
Windows	x86-64	Scoop
macOS	arm64 (Apple Silicon)	Homebrew
macOS	x86-64 (Intel)	Unavailable
Linux	x86-64	Homebrew
Linux	arm64	Homebrew

Windows with Scoop:

Command

scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap
scoop install vaultspec-core

macOS and Linux with Homebrew:

Command

brew install nevenincs/tap/vaultspec-core

One command, and the tap-qualified name is the whole of why. It taps as it installs, so no brew tap is needed first, and Homebrew records the formula as trusted on the way through.

Do not add the tap separately and install by bare name. Homebrew 7.0 refuses to load a formula from a tap outside its official set, and an explicitly added tap is outside that set whether or not you pass its URL:

Captured session

$ brew tap nevenincs/tap
$ brew install vaultspec-core
Error: Refusing to load formula nevenincs/tap/vaultspec-core from untrusted tap nevenincs/tap.

That refusal is what the tap-qualified form avoids, and it is not cleared by having installed the formula before - only brew trust nevenincs/tap, which records the whole tap in ~/.homebrew/trust.json, makes the bare name work. Prefer the one command above; reach for brew trust only if you want vaultspec-core to resolve unqualified.

Upgrading needs neither, because the formula is already trusted by then:

Command

brew upgrade vaultspec-core

Homebrew is the supported path on macOS for a second reason. brew fetches the archive itself rather than through a browser, so nothing it installs carries the com.apple.quarantine attribute and Gatekeeper never interposes. See macOS for what a direct download meets instead.

Direct release downloads

The release page publishes one archive per target. The archive name carries the product, version, and Rust target; its extracted command names do not vary by platform.

Target	Release asset
Windows x86-64	vaultspec-core-v<version>-x86_64-pc-windows-msvc.zip
macOS arm64	vaultspec-core-v<version>-aarch64-apple-darwin.tar.gz
macOS x86-64	Not published; use the Python install
Linux x86-64	vaultspec-core-v<version>-x86_64-unknown-linux-gnu.tar.gz
Linux arm64	vaultspec-core-v<version>-aarch64-unknown-linux-gnu.tar.gz

Each archive contains vaultspec-core, vaultspec-core-mcp, LICENSE, README.md, and manifest.json. On Windows the executables end in .exe. README.md is this project’s own README, shipped as-is; its images and relative links resolve against the repository rather than the archive. The manifest records the archive contract, target, runtime, platform floor, product description, and SHA-256 for each member.

Extract the asset for your target, then run the stable command name:

Command

Expand-Archive .\vaultspec-core-v<version>-x86_64-pc-windows-msvc.zip -DestinationPath .\vaultspec-core
.\vaultspec-core\vaultspec-core.exe --version

Command

tar -xzf vaultspec-core-v<version>-aarch64-apple-darwin.tar.gz
chmod +x ./vaultspec-core
./vaultspec-core --version

The target-qualified executable filenames used during the build are staging names, not the direct-download contract. Download the archive and its matching SHA256SUMS entry.

Binaries are not code-signed

Core’s binaries carry no publisher signature, and they won’t get one. Code signing needs a paid, per-year identity tied to a legal entity - a hardware-held certificate on Windows, Apple Developer Program membership on macOS. This is an open-source project and neither is being bought. That’s a settled decision, not a gap waiting to be filled: don’t wait for a signed build.

What it costs you is one warning, once, on each platform. Both are your operating system reporting that it doesn’t know who published the file - not that the file is damaged or that the download went wrong.

Windows

Running a binary you downloaded from the release page in a browser shows Windows protected your PC. Choose More info, then Run anyway. Installing with Scoop avoids it: Scoop fetches the binary itself rather than through a browser, so the download isn’t marked as having come from the internet.

macOS

Gatekeeper quarantines anything a browser downloads, and an unsigned, un-notarized binary is then refused with cannot be opened because the developer cannot be verified.

Install with Homebrew and you never meet it - brew fetches without setting the quarantine attribute. That’s the supported path on macOS and the reason to prefer it.

For an executable extracted from a bundle you downloaded directly, clear the attribute and mark it executable:

Command

xattr -d com.apple.quarantine ./vaultspec-core
chmod +x ./vaultspec-core

Verify the download first - the checks below are what tells you the file is the one this repository published, and clearing quarantine tells macOS to stop asking.

Verifying what you downloaded

Download SHA256SUMS from the same release as your bundle. Compute the archive’s SHA-256 hash with the command for your platform, replacing ./bundle with its path:

Platform	Command
Windows (PowerShell)	Get-FileHash -Algorithm SHA256 -LiteralPath './bundle'
macOS	shasum -a 256 './bundle'
Linux	sha256sum './bundle'

Compare the result with the hash beside that bundle’s filename in SHA256SUMS; letter case doesn’t matter. If they differ, don’t extract or run the bundle. Download it again from the same release and recheck.

A matching checksum confirms agreement with the release manifest. It doesn’t establish where the asset came from: whoever can replace a binary on a release page can replace the manifest beside it in the same act.

Build provenance answers that second question, and it’s the supported way to establish that an asset came from this repository’s release workflow. It’s what this project offers in place of a publisher signature, and unlike a signature it costs nothing to produce and nothing to check.

Provenance starts at v0.1.74

The wiring that mints attestations landed after v0.1.73, and nothing is minted retroactively, so v0.1.74 is the first release whose assets carry build provenance. Assets from v0.1.73 and earlier have none and never will.

Check which release you downloaded from before you check provenance. If it’s v0.1.73 or earlier there is nothing to verify: gh attestation verify fails on every asset in those releases, and that failure means the attestation was never minted - not that your download is bad. Compare the checksum above and stop there.

For v0.1.74 and later, verify an asset’s provenance with GitHub CLI:

Command

gh attestation verify <asset> --repo nevenincs/vaultspec-core

Replace <asset> with the downloaded file’s path. If verification fails on a release that should carry provenance, check the command’s error before running the asset.

To require a particular signing workflow, add --signer-workflow. For the release binaries:

Command

gh attestation verify <asset> --repo nevenincs/vaultspec-core --signer-workflow nevenincs/vaultspec-core/.github/workflows/binaries.yml

For a wheel or source distribution, use nevenincs/vaultspec-core/.github/workflows/publish.yml instead. SHA256SUMS itself has no attestation because both release workflows update it; verify the individual assets.

A build attestation is not a code signature and doesn’t act like one: it changes nothing about SmartScreen or Gatekeeper, which ask who published a file rather than where it was built. Those warnings are expected and permanent - see Binaries are not code-signed. Provenance is the integrity check this project does offer, and it needs no certificate from anybody.

For release maintenance, see updating package-manager manifests.