Installation
HackAgent needs Python 3.10+, or nothing at all with a standalone binary.
Install
- pip
- uv
- Standalone binary
python3 -m venv .venv
source .venv/bin/activate
pip install hackagent
uv venv
source .venv/bin/activate
uv pip install hackagent
Every GitHub Release has a self-contained archive: hackagent-<version>-linux-x86_64.tar.gz, -macos-arm64.tar.gz or -windows-x86_64.zip. Extract it and run the hackagent launcher inside; keep the folder intact. The binary already includes every extra below.
Check it:
hackagent --version
hackagent --help
Optional extras
The base install has the SDK, the CLI and a local results store. Add an extra when you need what it unlocks, at any time:
| Extra | Unlocks | Needed by |
|---|---|---|
tui | Textual | The terminal UI (hackagent, hackagent tui) |
web | Flask and the dashboard bundle | hackagent web |
browser | Playwright | WEB targets that drive a live page |
rag | FAISS and NumPy | h4rm3l, the RAG attack, AutoDAN-Turbo |
vision | Pillow | The MML attack |
hf | Hugging Face datasets | 25 of the 27 dataset presets (all but agenthazard and omnisafebench) and any other Hub dataset |
For example, the terminal UI needs pip install 'hackagent[tui]'; add several at once with pip install 'hackagent[tui,rag,hf]'.
Local or remote
- Local (default)
- Remote
No account or API key. Runs and results are stored in SQLite at ~/.local/share/hackagent/hackagent.db, and hackagent web serves them at http://127.0.0.1:7860.
Select remote storage explicitly and provide its key through the environment.
hackagent web then proxies API requests to show the remote results.
export HACKAGENT_API_KEY="your_api_key"
hackagent config set --backend remote
HACKAGENT_BASE_URL (or --base-url) points at another host; the default is https://api.hackagent.dev.
hackagent init walks you through the same storage choice and saves it (never the key) to ~/.config/hackagent/config.json. hackagent config shows and changes every setting.
A campaign records its own results separately: execution.storage.backend is local unless the file names a server with remote, so being signed in changes what you can read, not where a new run is written.
Next steps
- Your first campaign: attack a local model and read the result.
- How a run works: what happens between a goal and a verdict.
- Campaign reference: every field of the campaign format, and every command.