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",
)

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

agent.hack(attack_config=attack_config)

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

agent.hack(attack_config=attack_config)

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