htb-sdk

Unofficial, typed Python SDK for Hack The Box — reverse-engineered from the live labs.hackthebox.com API.

pip install htb-sdk

from htb import HTBClient, Difficulty

htb = HTBClient(token="...")          # or set HTB_TOKEN

htb.user.me()
box = htb.machines.list(per_page=1)[0]
htb.machines.spawn(box["id"])
htb.machines.submit_flag(box["id"], "HTB{...}", Difficulty.MEDIUM)
htb.machines.terminate(box["id"])

htb.get("/api/v4/season/list")        # raw access to any endpoint

Get an App Token at Profile → Settings → App Tokens on app.hackthebox.com.

17 typed resource namespaces — machines, challenges, sherlocks, fortresses, prolabs, endgames, tracks, seasons, teams, universities, rankings, user, connection, pwnbox, tokens, walkthroughs, platform. Full map: docs/ENDPOINTS.md.

CLI & MCP

Both are auto-generated from the SDK — every method is a command and a tool.

Both ship in the base install — no extras needed.

htb machines list --per-page 5           # Rich table
htb machines spawn 351                   # write ops too
htb machines list --json | jq .          # raw JSON for scripting
htb raw GET /api/v4/season/list          # any endpoint

htb-mcp                                   # FastMCP server (stdio), reads HTB_TOKEN

Docs & examples

Runnable scripts in examples/; full CLI reference in docs/cli.md. Browse the typed API interactively:

uv sync --group docs && uv run mkdocs serve   # http://127.0.0.1:8000

Develop

uv sync --all-groups
uv run pytest            # add --e2e for live tests (needs HTB_TOKEN)

The API map is reverse-engineered from real browser traffic + frontend JS; re-run the pipeline in capture/ when HTB changes their API.

License

MIT