htbctl

Python library and CLI for HackTheBox machine lifecycle automation.

spawn → wait for IP → attack → stop

Requires Python 3.9+. Works with free and VIP HTB accounts.

Install

pip install htbctl

Setup

1. Go to https://app.hackthebox.com/profile/settings → App Tokens → Create App Token
2. Save the token in any of these locations (checked in order):

# Option A — dedicated config (recommended)
mkdir -p ~/.config/htbctl
echo "HTB_TOKEN=eyJ..." > ~/.config/htbctl/.env

# Option B — .env in current directory
echo "HTB_TOKEN=eyJ..." > .env

# Option C — environment variable
export HTB_TOKEN=eyJ...

Or pass the token directly in Python:

htb = HTBIntegration(token="eyJ...")
htb = HTBIntegration(env_path="path/to/.env")

3. Make sure HTB VPN is connected — spawned machines are only reachable through VPN.

Python API

from htbctl import HTBIntegration

# Reads: ~/.config/htbctl/.env → .env → HTB_TOKEN env var
with HTBIntegration() as htb:
    machine = htb.spawn("Cap")
    print(machine.ip)   # 10.10.11.xx
    # ... run your exploit here ...
# machine is stopped automatically

Explicit token:

htb = HTBIntegration(token="eyJ...")
machine = htb.spawn("Precious")
htb.stop("Precious")

CLI

htbctl login                        # verify token
htbctl list                         # list all retired machines
htbctl list cap                     # filter by name

htbctl spawn Precious               # spawn a machine, print IP
htbctl spawn Precious --force       # stop active machine first, then spawn

htbctl stop Precious                # stop by name
htbctl stop --active                # stop whatever is running

SpawnedMachine

machine = htb.spawn("Cap")
machine.name        # "Cap"
machine.ip          # "10.10.11.xx"
machine.os          # "Linux"
machine.difficulty  # "Easy"
machine.machine_id  # 351

Exceptions

from htbctl import HTBError, HTBAuthError, HTBMachineNotFoundError, HTBSpawnError, HTBRateLimitError

Logging

The library is silent by default. To see what's happening:

import logging
logging.getLogger("htbctl").addHandler(logging.StreamHandler())
logging.getLogger("htbctl").setLevel(logging.DEBUG)

The CLI enables logging automatically with [htbctl] prefix.

Credits & Alternatives

This project was inspired by pyhackthebox by @clubby789.

Why htbctl exists:

• pyhackthebox is a general-purpose client (last update: 2022)
• htbctl is focused on automation: spawn → attack → stop
• App Token auth only (no email/password/OTP)
• Context manager with auto-stop

If you need full HTB API coverage (challenges, leaderboards, user profiles) — use pyhackthebox. If you need to automate machine attacks — use htbctl.