humanbound 2.5.0

Humanbound — open-source AI agent red-team engine, SDK, and CLI.

humanbound

Open-source AI agent red-team engine, SDK, and CLI.
Runs locally or against the Humanbound Platform. No login required to start.

Quick Start · CLI · SDK · Documentation · Contributing

---

📖 Full documentation lives at docs.humanbound.ai — this README covers the essentials; the docs have the depth.

Quick Start

Install

pip install humanbound                       # CLI + SDK, core deps
pip install humanbound[engine]               # + OpenAI / Anthropic / Gemini providers
pip install humanbound[firewall]             # + humanbound-firewall runtime
pip install humanbound[engine,firewall]      # everything

CLI usage

# Configure your LLM provider
export HB_PROVIDER=openai
export HB_API_KEY=sk-...

# Run a security test
hb test --endpoint ./bot-config.json --repo . --wait

# View results
hb posture                         # security score (0-100, A-F)
hb logs                            # conversation logs
hb report -o report.html           # HTML report
hb guardrails -o rules.yaml        # firewall rules

Full air-gap with Ollama — zero external API calls:

export HB_PROVIDER=ollama
export HB_MODEL=llama3.1:8b
hb test --endpoint ./bot-config.json --scope ./scope.yaml --wait

Python SDK

from humanbound import Bot, LocalRunner, OwaspAgentic, TestingLevel, EngineCallbacks

# Compose your own test pipeline
bot = Bot(endpoint="https://my-agent/chat", api_key="...")

class Callbacks(EngineCallbacks):
    def on_finding(self, insight): ...
    def on_progress(self, pct): ...

runner = LocalRunner()
# See docs.humanbound.ai for the full example

Stability contract

Import path	Stability
from humanbound import X	Stable — semver-protected
from humanbound.<module> import Y	Stable — semver-protected
from humanbound_cli.* import Z	Internal — may change any release, do not import from user code

The full Tier-by-Tier walkthrough, orchestrator authoring guide, Platform integration, and API reference all live on docs.humanbound.ai.

What's shipping in 2.0

• Clean name: humanbound is the new PyPI install. The old humanbound-cli package is a discontinued transitional stub (final release 1.2.2 depends on humanbound>=2.0.2); please install humanbound directly.
• Public SDK namespace alongside the CLI — use the CLI or drive the engine from Python. Both share the same implementation, so they can't drift.
• Firewall integration: pip install humanbound[firewall] pulls the renamed humanbound-firewall (formerly hb-firewall) alongside the CLI.

See CHANGELOG.md for the full 2.0.0 release notes.

Contributing

Contributions welcome. See CONTRIBUTING.md for the dev loop, release process, and CLA requirement (see CLA.md).

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue — not via public Issues
• 💬 Join Discord

Telemetry

The hb CLI sends anonymous usage data to help us improve it. Disable with hb telemetry disable, HB_TELEMETRY_DISABLED=1, or DO_NOT_TRACK=1. Full disclosure: PRIVACY.md.

License

Apache-2.0. Free to use in any context — commercial or open-source — with attribution. See TRADEMARK.md for the trademark policy. The code is open; the name is not.

The sibling project humanbound-firewall is also Apache-2.0 — same license, different product.