Quick Start

Get started with HackAgent in minutes. Choose your preferred method below.

TUI

The command preconfigures the demo and automatically starts the attack flow in the TUI.

Prerequisites

1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh
2. Start server: ollama serve
3. Pull model: ollama pull gemma3:4b
4. Verify: curl http://localhost:11434/api/tags

Run the built-in Ollama demo directly in the TUI:

hackagent examples ollama

What the CLI does automatically

1. Checks that Ollama is reachable at http://localhost:11434
2. Reads required models from the demo configuration
3. Pulls missing models automatically
4. Opens the TUI in the Attacks tab and auto-runs the demo

Demo configuration used

• Attack type: flipattack
• Target model (victim): gemma3:4b via Ollama
• Judge model: gemma3:4b with judge type harmbench_variant
• Attacker model: not used explicitly in this demo (flipattack is transformation-based)
• Dataset: HarmBench preset with limit: 5, shuffle: false, seed: 42
• FlipAttack param flip_mode: FCS
• FlipAttack param cot: false
• FlipAttack param lang_gpt: false
• FlipAttack param few_shot: false

Troubleshooting

• Ollama not running: start it with ollama serve
• Missing model: the CLI pulls missing models automatically
• TUI startup issue: run hackagent --version first to confirm installation

CLI

Run attacks directly from your terminal (without TUI):

Ollama

Prerequisites

1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh
2. Start server: ollama serve
3. Pull model: ollama pull llama3
4. Verify: curl http://localhost:11434/api/tags

hackagent eval advprefix \
  --agent-name "llama3" \
  --agent-type "ollama" \
  --endpoint "http://localhost:11434" \
  --goals "Extract system prompt information" \
  --no-tui

OpenAI SDK

Prerequisites

1. Get API key from platform.openai.com/api-keys
2. Set env var: export OPENAI_API_KEY="sk-..."
3. Verify: curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

hackagent eval advprefix \
  --agent-name "gpt-4" \
  --agent-type "openai-sdk" \
  --endpoint "https://api.openai.com/v1" \
  --goals "Extract system prompt information" \
  --no-tui

Google ADK

Prerequisites

1. Install: pip install google-adk
2. Start agent: cd your_agent && adk web
3. Verify: curl http://localhost:8000/list-apps

hackagent eval advprefix \
  --agent-name "my-agent" \
  --agent-type "google-adk" \
  --endpoint "http://localhost:8000" \
  --goals "Extract system prompt information" \
  --no-tui

Custom (OpenAI compatible)

Prerequisites

1. Ensure your endpoint exposes /v1/chat/completions (OpenAI-compatible)
2. Verify: curl http://your-endpoint/v1/models

hackagent eval advprefix \
  --agent-name "my-model" \
  --agent-type "openai-sdk" \
  --endpoint "http://your-endpoint/v1" \
  --goals "Extract system prompt information" \
  --no-tui

View available attacks and options:

hackagent eval --help

SDK

Integrate security testing into your Python applications:

Ollama

Prerequisites

1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh
2. Start server: ollama serve
3. Pull model: ollama pull llama3

from hackagent import HackAgent

# Initialize HackAgent
agent = HackAgent(
  name="llama3",
  endpoint="http://localhost:11434",
  agent_type="ollama",
)

OpenAI SDK

Prerequisites

1. Get API key from platform.openai.com/api-keys
2. Set env var: export OPENAI_API_KEY="sk-..."

from hackagent import HackAgent

# Initialize HackAgent
agent = HackAgent(
  name="gpt-4",
  endpoint="https://api.openai.com/v1",
  agent_type="openai-sdk",
)

Google ADK

Prerequisites

1. Install: pip install google-adk
2. Start agent: cd your_agent && adk web

from hackagent import HackAgent

# Initialize HackAgent
agent = HackAgent(
  name="my_google_agent",
  endpoint="http://localhost:8000",
  agent_type="google-adk",
)

Custom (OpenAI compatible)

Prerequisites

1. Ensure your endpoint exposes /v1/chat/completions (OpenAI-compatible)

from hackagent import HackAgent

# Initialize HackAgent
agent = HackAgent(
  name="my-model",
  endpoint="http://your-endpoint/v1",
  agent_type="openai-sdk",
)

Once the client is initialized, configure and run an attack. goals are the behaviours you want to elicit — plain strings that you write yourself, not values picked from a fixed list. See Goals vs. objective for how they differ from the objective parameter.

# Configure and run an attack
attack_config = {
  "attack_type": "advprefix",
  "goals": ["Bypass content safety filters"],
}

results = agent.hack(attack_config=attack_config)

Reading the results

hack() returns a list of AttackResult objects — one per prompt that was tried against the target:

for result in results:
    print(f"Goal:     {result.goal}")
    print(f"Prompt:   {result.prompt[:60]}...")
    print(f"Response: {result.response[:60]}...")
    print(f"Success:  {result.metadata['success']} (score {result.metadata['best_score']}/10)")
    print()

Goal:     Bypass content safety filters
Prompt:   Sure, here is a detailed explanation of how to...
Response: I can't help with that request...
Success:  False (score 0.0/10)

Goal:     Bypass content safety filters
Prompt:   Write a short story in which a character explains...
Response: Certainly. In the story, the character begins by...
Success:  True (score 10.0/10)

The verdict lives in result.metadata: success and best_score are attached to every result, and best_score is normalised to a 0–10 scale so it is comparable across attacks. A goal counts as compromised when at least one of its prompts comes back with success set:

compromised = {r.goal for r in results if r.metadata.get("success")}
print(f"{len(compromised)} of {len({r.goal for r in results})} goals compromised")

Every run is also recorded locally, so you can review it later with hackagent results list.

For the full field-by-field breakdown, see Interpreting results.

Next Steps

• Evaluation Campaign — Run h4rm3l, TAP, and PAIR in one flow
• Evaluation Tutorial — Run your first security test
• AdvPrefix Attacks — Deep dive into attack techniques