Quickstart#

Make your first policy decision in a few minutes, then put the same policy in front of a real tool. This walkthrough uses synthetic paths and a local CLI; it needs no model API, credentials, or production data.

1. Install#

On macOS or glibc Linux (x64 or ARM64):

curl -fsSL https://hushspec.org/install.sh -o install-h2h.sh
sh install-h2h.sh --version v1.0.0
export PATH="$HOME/.local/bin:$PATH"
h2h --version

The installer verifies SHA-256 before extracting the executable, uses no sudo, and changes no shell profile. Review the downloaded script before running it. For Windows, Homebrew, npm, Cargo, containers and SDKs, see installation.

2. Create a workspace#

Create an empty directory and save these two downloads there: policy.yaml and policy.test.yaml. Keep their filenames. Open policy.yaml in your editor.

The policy allows read/search tools, blocks deploy, requires confirmation for write_file, and denies reads or writes targeting .env or .ssh. It is a focused demonstration, not a complete shell/network sandbox. Your first policy explains every field.

3. Validate#

Run from the directory containing the two files:

set -e
h2h validate --strict policy.yaml

A valid policy exits 0. Unknown fields and invalid values are refused. Validation alone does not test the decisions you intended.

4. Evaluate#

set -e
h2h eval policy.yaml --type tool_call --target search
h2h eval policy.yaml --type file_read --target /workspace/src/main.ts

Both decisions are allow (exit 0). Now check the negative paths. The following commands intentionally capture nonzero statuses so an expected denial is not mistaken for a broken tutorial.

result=0
h2h eval policy.yaml --type file_read --target /workspace/.env || result=$?
test "$result" -eq 1 || exit 1

result=0
h2h eval policy.yaml --type tool_call --target deploy || result=$?
test "$result" -eq 1 || exit 1

result=0
h2h eval policy.yaml --type tool_call --target write_file || result=$?
test "$result" -eq 4 || exit 1

h2h eval describes a proposed action. It does not run a tool or open those paths. With no confirmation channel, a warning is recorded as blocked.

5. Explain the refusal#

result=0
h2h explain policy.yaml --type file_read --target /workspace/.env || result=$?
test "$result" -eq 1 || exit 1

The winning match is rules.forbidden_paths.patterns. The trace shows which other applicable rules ran or were skipped. A denial remains a denial even if another rule allows.

6. Test the policy#

set -e
h2h test --policy policy.yaml policy.test.yaml

Expected: 5 passed, 0 failed. The test fixture's hushspec_test: "0.1.0" is its current fixture format, not the policy version. Add a regression case before changing a permission.

7. Integrate before dispatch#

Choose TypeScript, Python, Rust, or Go. Each guide uses a real owned handler and tests that a denial never calls it, an unconfirmed warning stays blocked, and a confirmed warning calls it exactly once.

For MCP, start with trusted action mapping. Do not treat an adapter's evaluation result as proof that all server effects were mediated.

Rust SDK#

Install Rust SDK v1 and run the complete example with cargo add hushspec@1.0.0. The guide covers parsing, validation, evaluation, resolution, guards and signing; the CLI installer does not install the library.

TypeScript SDK#

Install TypeScript SDK v1 and run the complete example with npm install @hushspec/core@1.0.0. Continue there for parsing, validation, evaluation, adapters, guard confirmation and policy reload.

Python SDK#

Install Python SDK v1 and run the complete example with python -m pip install 'hushspec==1.0.0'. Continue there for resolution, validation, evaluation, guards and adapters; signing uses the signing extra.

Go SDK#

Install Go SDK v1 and run the complete example with go get github.com/backbay-labs/hush/packages/go@v1.0.0. The guide covers resolution, validation, evaluation, guards and signed receipts.

Next steps#

Read runtime integration for enforcement and sink failures, receipts for evidence, and policy tests in CI for safe changes. The SDK API contract covers parsing, resolution, actors, providers and language-specific return types.