Installation¶
The current release is Assay 6.19.1 (v6.19.1). Choose a CLI installation route below and follow the applicable prerequisites and verification instructions.
CLI¶
Unix installer¶
Homebrew¶
On macOS (arm64, x86_64) and Linux (arm64, x86_64):
The formula in Rul1an/homebrew-tap installs the prebuilt release archive, pinned by the release's published sha256. brew upgrade assay picks up later releases.
Cargo¶
The crate is assay-cli; the installed binary is assay. Releases starting with 3.36.0 declare Rust 1.89 as their MSRV. Repository development currently uses Rust 1.96.
GitHub release assets¶
Download the asset for v6.19.1, verify its published checksum, and place the binary on PATH.
CLI archives produced by this release workflow contain assay-mcp-server beside assay (assay-mcp-server.exe beside assay.exe in the Windows zip). The agent plugin's mcp.json uses the bare command assay-mcp-server. Make the extracted directory available on the agent host process's PATH, or configure the host with the server executable's absolute path; archive co-location alone does not configure command lookup. For older releases, inspect the selected archive for the companion executable before configuring the host.
Releases v6.6.2 and later publish a signed checksums.txt. When cosign is on PATH and reports v3.1.3 or later (v2.6.5 on the 2.x line), scripts/install.sh verifies that manifest against the release workflow identity at the tag before it trusts any per-file hash. When cosign is present but older or unparsable, the installer refuses that signature check and stops (GHSA-fx35-mq7g-6g98). When cosign is absent, the installer prints verification=signed_manifest_skipped reason=cosign_not_installed and continues with the per-file .sha256 sidecar. It never skips that check silently.
To verify a published archive yourself over a connected network (replace vX.Y.Z with the tag you downloaded). This recipe uses curl and cosign's default trust material; it is not network-isolated. For TrustedRoot under network isolation, use the canonical recipe in release.md — Network-isolated consumer (TrustedRoot):
set -euo pipefail
VERSION=vX.Y.Z
ARCHIVE=assay-${VERSION}-x86_64-unknown-linux-gnu.tar.gz
curl -fsSLO "https://github.com/Rul1an/assay/releases/download/${VERSION}/${ARCHIVE}"
curl -fsSLO "https://github.com/Rul1an/assay/releases/download/${VERSION}/checksums.txt"
curl -fsSLO "https://github.com/Rul1an/assay/releases/download/${VERSION}/checksums.txt.sigstore.json"
cosign verify-blob \
--bundle checksums.txt.sigstore.json \
--certificate-identity "https://github.com/Rul1an/assay/.github/workflows/release.yml@refs/tags/${VERSION}" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
LINE=$(awk -v archive="$ARCHIVE" '$2 == archive { print; found=1 } END { exit !found }' checksums.txt) || {
echo "checksums.txt does not name ${ARCHIVE}" >&2
exit 1
}
printf '%s\n' "$LINE" | sha256sum -c -
Use cosign v3.1.3 or later (v2.6.5 on the 2.x line). Earlier versions are affected by GHSA-fx35-mq7g-6g98 (verification bypass via public key in a legacy bundle).
The signed manifest names every published payload. This recipe verifies the selected archive after the signature check; it does not download the rest of the set. Success prints Verified OK, then one OK line for that archive. A bad signature prints a cosign Error: and stops. A checksums.txt that does not name the archive fails with checksums.txt does not name and that file. A missing or tampered archive prints FAILED from sha256sum. Pin exactly that certificate identity and issuer; do not accept a signature bound to a branch ref.
For stable tags up to v6.6.1, the current installer permits a missing checksums.txt; it does not promise that every historical release has the archive and .sha256 sidecar it requires. After those assets are downloaded, if cosign is present but checksums.txt cannot be fetched, it reports verification=signed_manifest_unavailable reason=checksums.txt_not_published and continues to sidecar verification. If a manifest is fetched, its signature must verify. Check the selected historical release’s assets before using this route; the version cutoff is an installer rule, not a guarantee about all older releases.
See release.md for the operator checklist and the network-isolated consumer recipe. CI runs that isolated helper against the release candidate and as a published-assets replay; the connected recipe above is unchanged.
Windows x86-64 uses:
Assay documents the container image below as a verified release channel. Scoop remains unsupported.
Container image (assay-mcp-server)¶
The v6.19.1 image index is ghcr.io/rul1an/assay-mcp-server@sha256:0b0f3288cade6d6ec8098116b25c7ef8f7f8ce9d42cea0a13a8afcbf5a81d85e (tags such as v6.19.1, 6.19, and latest are convenience aliases; the digest is the pinned reference).
Pull and run the multi-arch assay-mcp-server image by index digest:
docker run --rm ghcr.io/rul1an/assay-mcp-server@sha256:0b0f3288cade6d6ec8098116b25c7ef8f7f8ce9d42cea0a13a8afcbf5a81d85e --version
The image runs as uid:gid 65532:65532 (non-root) on a minimal base, and the index contains both linux/amd64 and linux/arm64 images.
Verify SLSA provenance and CycloneDX SBOM attestations:
gh attestation verify oci://ghcr.io/rul1an/assay-mcp-server@sha256:0b0f3288cade6d6ec8098116b25c7ef8f7f8ce9d42cea0a13a8afcbf5a81d85e -R Rul1an/assay --predicate-type https://slsa.dev/provenance/v1
gh attestation verify oci://ghcr.io/rul1an/assay-mcp-server@sha256:0b0f3288cade6d6ec8098116b25c7ef8f7f8ce9d42cea0a13a8afcbf5a81d85e -R Rul1an/assay --predicate-type https://cyclonedx.org/bom
For producer-side image verification results, see release run 41288086186. Verify the selected digest with the commands above; the link is not independent verification.
Python SDK and pytest plugin¶
CPython 3.12, 3.13, and 3.14 on macOS x86_64/arm64 and Linux x86_64; other interpreters and platforms are not claimed.
assay-it installs the Python SDK and pytest plugin. It does not install the assay CLI. The package named assay on PyPI is unrelated to this project.
Verify the CLI¶
Expected output:
The generated agent golden path additionally uses assay version, whose release-pinned output is 6.19.1.
Verify an evidence bundle offline¶
For a bundle containing this release's proxy-produced denial observations, select profile v1 explicitly. Follow the installed-release journey to acquire the companion server and example, produce records, import a bundle and verify that same bundle on Unix or Windows. Verification requires no network access:
Both outcomes emit a JSON document adhering to the assay.privileged_mcp_action.verify.report.v0 report schema:
- Valid (exit code
0):bundle_integrity: passandverdict: valid. - Integrity failure or invalid verdict (exit code
2): on integrity failure,bundle_integrity: fail,reason_code: E_EVIDENCE_INTEGRITY, and theverdictkey is omitted; on an invalid verdict with integrity pass,bundle_integrity: passandverdict: invalid.
The report is experimental v0; verification recomputes the carried bytes only. The report schema version is distinct from the selected evidence profile. The CLI default remains profile v0 for compatible records. For compatible v0 bundles only:
A bundle carrying assay.denied_call_observation.v1 is refused by that default with E_EVIDENCE_PROFILE_INVALID; use explicit v1 for those observations as shown above.
Development build¶
Behavior merged after v6.19.1 is Unreleased and is not part of the release claim above.
git clone https://github.com/Rul1an/assay.git
cd assay
cargo build --release
./target/release/assay --version
CI¶
For source installation in CI:
The GitHub Action is available as Rul1an/assay-action@v3; follow the CI integration guide for the repository's current permissions and pinning policy.
Uninstall¶
For an installer-script or release-asset installation, remove the installed binary from the location reported by your shell's command -v assay.
Next step¶
Continue with the release-pinned agent golden path or the shorter quick start.