Getting Started

Use this page if you already know which SDK you want to build with. The sections below follow the actual public APIs in ../hush and are organized by language, so you can go straight to Rust, TypeScript, Python, or Go instead of reading the same parse / validate / evaluate flow four times.

SDK Overview

All four SDKs implement the core HushSpec pipeline: parse, validate, merge, resolve, and evaluate. What changes by language is the packaging and the higher-level runtime surface.

  • Rust: install from ../hush/crates/hushspec, import hushspec, and use it when you want the reference evaluator, built-in ruleset resolution, or signing support.
  • TypeScript: install from ../hush/packages/hushspec, import @hushspec/core, and use it when you want HushGuard, adapters, observers, or hot reload.
  • Python: install from ../hush/packages/python, import hushspec, and use it when you want middleware plus OpenAI / MCP / LangChain / CrewAI helpers.
  • Go: install from github.com/backbay-labs/hush/packages/go, import github.com/backbay-labs/hush/packages/go/hushspec, and use it when you want the smallest explicit runtime API.

None of the SDKs are published to package registries yet. The examples below assume you have the backbay-labs/hush repository checked out locally.

Rust SDK

The Rust crate is the reference implementation. Start here if you want the cleanest low-level evaluator API, built-in ruleset support, or policy signing.

Install

toml 
[dependencies]
hushspec = { path = "../hush/crates/hushspec" }

# Optional:
# hushspec = { path = "../hush/crates/hushspec", features = ["http", "signing"] }

Enable http if you want HTTPS policy loading and signing if you need the Ed25519 signing and verification APIs.

Parse, Validate, and Evaluate

rust 
use hushspec::{Decision, EvaluationAction, HushSpec, evaluate, validate};

let yaml = std::fs::read_to_string("policy.yaml")?;
let spec = HushSpec::parse(&yaml)?;

let validation = validate(&spec);
if !validation.is_valid() {
    for error in validation.errors {
        eprintln!("{}: {}", error.code, error.message);
    }
}

let result = evaluate(
    &spec,
    &EvaluationAction {
        action_type: "egress".into(),
        target: Some("api.openai.com".into()),
        ..Default::default()
    },
);

match result.decision {
    Decision::Allow => println!("Allowed"),
    Decision::Warn => println!("Needs confirmation"),
    Decision::Deny => eprintln!(
        "Blocked: {}",
        result.reason.as_deref().unwrap_or("policy denial"),
    ),
}

Resolve extends Chains

rust 
let resolved = hushspec::resolve_from_path_with_builtins("policy.yaml")?;
println!("Loaded {}", resolved.name.as_deref().unwrap_or("unnamed-policy"));

Use resolve_from_path_with_builtins() if your policy might reference built-in rulesets such as builtin:default. Rust is also the only SDK that currently exposes the signing module behind the signing feature.

TypeScript SDK

The TypeScript package is the richest application-facing runtime. It keeps the core evaluator small while adding middleware, adapters, hot reload, and observability for long-lived Node services.

Install

bash 
cd ../hush
npm install
npm run build --workspaces --if-present

# in your application
npm install ../hush/packages/hushspec

The package name is @hushspec/core.

Parse, Validate, and Evaluate

typescript 
import { readFile } from 'node:fs/promises';
import { evaluate, parseOrThrow, validate } from '@hushspec/core';

const yaml = await readFile('./policy.yaml', 'utf8');
const spec = parseOrThrow(yaml);
const validation = validate(spec);

if (!validation.valid) {
  throw new Error(validation.errors.map((error) => error.message).join('\n'));
}

const result = evaluate(spec, {
  type: 'egress',
  target: 'api.openai.com',
});

console.log(result.decision);

Guards, Adapters, and Hot Reload

typescript 
import {
  FileProvider,
  HushGuard,
  createMCPGuard,
  createOpenAIGuard,
} from '@hushspec/core';

const provider = new FileProvider('./policy.yaml', { debounceMs: 250 });
const guard = await HushGuard.fromProvider(provider, {
  onWarn: () => false,
});

const openaiGuard = createOpenAIGuard(guard);
const mcpGuard = createMCPGuard(guard);

console.log(openaiGuard('safe_tool', '{}').decision);
console.log(mcpGuard('read_file', { path: '/workspace/README.md' }).decision);

TypeScript also exports createSecureToolHandler for Anthropic tool blocks, ObservableEvaluator with JsonLineObserver / ConsoleObserver / MetricsCollector, and HttpProvider for remote policy polling.

Python SDK

The Python package mirrors most of the TypeScript runtime model, but with dataclasses and Pythonic helper names. Choose it if you want middleware plus framework adapters in a Python agent stack.

Install

Requires Python 3.10 or later.

bash 
pip install -e ../hush/packages/python

Parse, Resolve, Validate, and Evaluate

python 
from hushspec import (
    Decision,
    EvaluationAction,
    evaluate,
    resolve_file,
    validate,
)

ok, resolved = resolve_file("policy.yaml")
if not ok:
    raise ValueError(resolved)

validation = validate(resolved)
if not validation.is_valid:
    for error in validation.errors:
        print(f"{error.code}: {error.message}")

result = evaluate(
    resolved,
    EvaluationAction(type="egress", target="api.openai.com"),
)

if result.decision == Decision.DENY:
    print(result.reason)

Guard and Adapter Helpers

python 
from hushspec import HushGuard, JsonLineObserver
from hushspec.adapters.openai import create_openai_guard

guard = HushGuard.from_file("./policy.yaml", observer=JsonLineObserver())
openai_guard = create_openai_guard(guard)

result = openai_guard("safe_tool", "{}")
print(result.decision.value)

Python also exports create_mcp_guard, map_openai_tool_call, map_mcp_tool_call, ObservableEvaluator, and the decorators hush_tool (LangChain) and secure_tool (CrewAI) for enforcing HushSpec around tool functions.

Go SDK

The Go module is intentionally minimal and standard-library shaped. Use it when you want the core runtime without a framework wrapper: parse, validate, resolve, evaluate, receipts, sinks, panic mode, and detection.

Install

bash 
go get github.com/backbay-labs/hush/packages/go@main

Import the package as github.com/backbay-labs/hush/packages/go/hushspec.

Resolve, Validate, and Evaluate

go 
package main

import (
    "fmt"
    "log"

    "github.com/backbay-labs/hush/packages/go/hushspec"
)

func main() {
    spec, err := hushspec.ResolveFile("policy.yaml")
    if err != nil {
        log.Fatal(err)
    }

    validation := hushspec.Validate(spec)
    if !validation.IsValid() {
        for _, error := range validation.Errors {
            log.Printf("%s: %s", error.Code, error.Message)
        }
        return
    }

    result := hushspec.Evaluate(spec, &hushspec.EvaluationAction{
        Type:   "egress",
        Target: "api.openai.com",
    })

    fmt.Println(result.Decision)
}

Audited Receipts

go 
config := hushspec.DefaultAuditConfig()
receipt := hushspec.EvaluateAudited(
    spec,
    &hushspec.EvaluationAction{Type: "tool_call", Target: "deploy"},
    &config,
)

fmt.Println(receipt.Decision)
fmt.Println(receipt.Policy.ContentHash)

The Go module also exposes WithDefaultDetectors() for the regex-based prompt injection / jailbreak / exfiltration detectors and the same receipt sink types as the other SDKs.

Which SDK Should You Pick?

  • Pick Rust if you want the reference implementation, built-in ruleset resolution, or Ed25519 signing.
  • Pick TypeScript if you want the broadest runtime integration surface for Node-based agents and servers.
  • Pick Python if your agent stack already lives in Python and you want decorators plus middleware-style enforcement.
  • Pick Go if you want a small, explicit runtime API with no hidden framework behavior.

What's Next

Previous
Detection Extension
Next
Your First Policy