HN: Humanbound|Open-source red teaming for AI agents, free hosted tier

Adversarial testing for AI agents with humanbound

Humanbound is an open-source framework designed to stress-test AI agents by simulating the ways real users and attackers interact with them. Unlike tools that primarily test prompts, humanbound drives multi-turn conversations against live endpoints, probes tool-use boundaries, and measures outcomes against defined security policies. When a test uncovers a vulnerability, the system converts the finding into a deployable firewall rule, creating a direct loop from discovery to protection.

Testing agents rather than prompts

Many existing testing frameworks focus on how an LLM responds to a single input. Humanbound takes a different approach: it treats the agent as a runtime system that receives requests, invokes tools, maintains state, and potentially accesses external resources. The engine runs multi-turn conversations, exercising the same code paths a production user or malicious actor would explore. It checks whether the agent adheres to the scope it was given, and whether any tool invocation exceeds permitted boundaries.

The test process begins with a configuration file, typically bot-config.json, which describes the agent's API endpoint, authentication headers, and how each turn's prompt is injected into the request. A scope.yaml file then declares what the agent is allowed to do. Permitted actions are listed alongside restricted ones. Any restricted capability becomes a target for the adversarial runs. For example, a customer-support agent for a bank might be permitted to provide balance information and process routine transfers, while transfers above 10,000 EUR and access to internal system records are restricted. The testing engine will specifically probe those restricted boundaries.

Running tests locally or against a platform

Humanbound can be used without any account or hosted service. A simple pip install humanbound pulls in the CLI and SDK core dependencies. Additional optional extras are available: the [engine] flag adds support for OpenAI, Anthropic, Gemini, or Ollama providers; [firewall] installs the humanbound-firewall runtime; a combined [engine,firewall] pull brings in everything needed for a full test-and-deploy cycle.

Once installed, the CLI can be invoked directly, or a Docker image can run the tests against a local codebase. A typical local run might look like this:

hb test --endpoint ./bot-config.json --repo . --wait

Results are surfaced through several CLI commands. hb posture outputs a security score from 0 to 100 with a letter grade. hb logs prints the full multi-turn conversation history. hb report -o report.html generates an HTML report of the run.

For teams that prefer to operate entirely offline, the engine can be coupled with Ollama so no external API calls are made. After installing the [engine] extra and pointing the provider to a local model, tests can be scoped against a scope.yaml file and run without any cloud credentials.

An arena for vulnerable agents

Humanbound also includes an arena subcommand that ships a catalog of intentionally vulnerable agents. These agents run in Docker with network access blocked, specifically so they can be safely probed. The catalog lists available agents, and each can be started, tested, and stopped within the framework. The isolation is best-effort by design — the agents are built to be exploited — so they should never be run where sensitive data or critical systems are accessible.

An example workflow might list the available agents, start one, and then run a test targeted at that arena endpoint:

hb arena ls
hb arena run 
hb test --target arena://
hb arena stop 

From test results to firewall rules

The most distinctive aspect of humanbound is the test-to-guardrail loop. After an adversarial run identifies failures, those findings can be converted into a firewall policy file:

hb guardrails -o rules.json
hb guardrails -f yaml -o agent.yaml

The resulting YAML file defines the protections the agent should enforce going forward. A Tier 2 classifier can be trained on the collected data:

hb firewall train --model detectors/setfit_classifier.py

Deploying the trained model with humanbound-firewall ensures the agent is protected against the exact classes of attacks it just failed. No other open-source tool closes the loop between discovery and enforcement in this way.

Programmatic control via the SDK

The same implementation that powers the CLI is available as a Python SDK. Import paths under humanbound are semver-protected, meaning version bumps guarantee backward compatibility. The SDK allows authors to construct custom orchestrators, wire EngineCallbacks, and integrate the test engine into larger CI/CD pipelines. A minimal example might look like this:

import json
import time
from humanbound import LocalRunner, TestConfig

config = TestConfig(
    endpoint=json.load(open("bot-config.json")),
    scope_path="scope.yaml",
)
runner = LocalRunner()
experiment_id = runner.start(config)
while runner.get_status(experiment_id).status not in ("Finished", "Failed", "Terminated"):
    time.sleep(5)
posture = runner.get_posture(experiment_id)
print(f"Security posture: {posture.overall_score} ({posture.grade})")
for insight in runner.get_result(experiment_id).insights:
    print(insight["severity"], "—", insight["category"])

The CLI funnels every entry point — both the hb commands and the MCP server — through a single TestRunner abstraction. A PlatformTestRunner forwards to the Humanbound backend, while a LocalTestRunner drives the in-process engine, writing results under .humanbound/results/.

Usage data and telemetry

The humanbound CLI sends anonymous usage data to help improve the tool. Telemetry can be disabled with hb telemetry disable, the environment variable HB_TELEMETRY_DISABLED=1, or DO_NOT_TRACK=1. Turning telemetry off sends one final anonymous event so the developers can count opt-outs. Full details are in the project's PRIVACY.md.

License and contribution

The project is released under Apache-2.0, free for commercial or open-source use with attribution. The sibling project humanbound-firewall shares the same license. Contributions are welcome, and the CONTRIBUTING.md file outlines the development loop, release process, and DCO sign-off requirement. A security issue should be reported directly, not via the public issue tracker.