HushSpec documentation#

Declare what an agent may do. Enforce it before a side effect. Keep evidence that another implementation can read and verify.

HushSpec v1 is a portable policy and evidence specification with a CLI and reference SDKs for Rust, TypeScript, Python and Go. Start with a small tested boundary, then expand its coverage deliberately.

Start with a working policy

01 / DECLAREPolicy
Resolve, validate and identify the rules.
02 / ENFORCEHost guard
Check before dispatch. Confirm warnings; stop denials.
03 / RECORDEvidence
Record the policy, decision and reported disposition.

The host owns actual effects. A policy or receipt alone is not a sandbox.

ONE POLICY / THREE DECISIONS

policy.yaml

hushspec: "1.0.0"
name: coding-agent-quickstart
rules:
  forbidden_paths:
    patterns: ["**/.env", "**/.ssh/**"]
  tool_access:
    allow: [read_file, search]
    block: [deploy]
    require_confirmation: [write_file]
    default: block

Allow search. Deny deploy and protected file reads. Require confirmation for write_file. The tested walkthrough explains each decision.

Download policy.yaml · Download test cases

Download the complete files and follow the Rust integration guide before running these commands.

Terminal

cargo run -- policy.yaml

Download the complete files and follow the TypeScript integration guide before running these commands.

Terminal

npm install
node main.mjs policy.yaml

Download the complete files and follow the Python integration guide before running these commands.

Terminal

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python main.py policy.yaml

Download the complete files and follow the Go integration guide before running these commands.

Terminal

go mod tidy
go run . policy.yaml

All complete language guides: Rust TypeScript Python Go

Write a policy#

Follow the quickstart, download the policy and tests, and see allow, deny and confirmation-required decisions. All twelve rule blocks cover paths, tools, egress, content, shell, desktop, browser and code-execution actions.

Integrate an agent#

Use a runtime guard immediately before dispatch. The MCP guide explains trusted mapping and the difference between checking a tool name and controlling its effects. Pick a language SDK for exact APIs and return conventions.

Inspect evidence#

Understand canonical policy identity, decision receipts, signing, logs, and bundles. Authenticity, continuity, completeness, and runtime truth are separate claims.

Implement the specification#

Read the normative library, then run a conformance corpus against a specific implementation. Use schemas and registries as machine-readable companions, not substitutes for evaluation semantics.

What v1 guarantees#

The v1 portable contract is stable under the versioning policy. Receipt/signature wire version 0.2 and log/bundle version 0.1 remain current. Strict evidence profiles, external-engine execution packets, and the trusted-invocation pilot remain experimental.

Where the boundary ends#

HushSpec evaluates descriptions of actions. The host owns authentication, dispatch, filesystem/network containment, counters and evidence delivery. A policy file alone is not a sandbox; a signed receipt is not certification. The security model makes those assumptions explicit.