htb-admin v1.0.0: Five Months of Constant Small Fixes

When I joined the HTB team and started competing seriously, I got tired of the friction. Spinning up a machine, manually editing /etc/hosts, keeping track of the IP, waiting for release with a timer open. It was all small stuff, but it added up. So I built a tool to handle it.

That was November 8, 2025. Today, five months and a lot of commits later, I’m releasing htb-admin v1.0.0.

What It Does

htb-admin is a CLI for Hack The Box that handles the overhead you don’t want to think about when you’re trying to compete.

# Spawn a machine and get straight to hacking
htb-admin machine start sau

# Auto-manages /etc/hosts - the IP is there before you even ask
htb-admin machine info

# Submit your flag when you pop it
htb-admin machine submit <flag> --difficulty 7

# Wait for release night automatically, then spawn immediately
htb-admin machine start --release

It also covers challenges, Sherlocks, ProLabs, VPN management, and user and team stats. Setup is one command (htb-admin init) and your API token lives in your system keyring, not a plaintext config file.

There’s also a hook system for automation. You can configure commands to fire at lifecycle events (after spawn, before stop, after flag submission) or use --run for a one-off command on a single start:

sudo htb-admin machine start Lame --run "rustscan -a \$HTB_MACHINE_IP -- -sV"

The hook fires after /etc/hosts is updated, so the hostname is already resolving when your command runs. This is new in v1.0.0 and I’m still putting it through its paces, but the core behaviour is there.

Five Months of Small Issues

Here’s what maintaining a personal tool actually looks like: you use it, something breaks, you fix it. You use it again, something slightly different breaks, you fix that too. You look at the history months later and realise you’ve been doing this on a loop since November.

Some of the bugs are embarrassing in retrospect. The /etc/hosts writer wasn’t atomic, so a crash mid-write could corrupt the file. The flag submission was sniffing for a congratulations string in the response body instead of reading the HTTP status. URL parameters were being built with raw f-strings, so special characters in machine names would silently fail.

None of it was catastrophic. It was exactly the kind of thing that only surfaces when you’re actually using the tool at 2am on release night, trying to move fast. The kind of bug you never catch in development.

I’d find one, fix it, go back to using the tool. Find another. Fix that. Repeat. That’s basically the whole development story between then and now.

What v1.0.0 Actually Means

It means it’s been “Coming Soon” for 6 months and it’s in a state where it mostly works. The interface is stable. The fragile parts have been hardened. It handles real-world edge cases I’ve personally hit (race conditions on spawn, VPN server mismatches, timezone bugs in the release countdown) because those weren’t hypothetical scenarios I planned for. They happened to me while I was trying to compete, and I fixed them.

If you hate trying to start a machine on release when the HTB website does not load, here is a semi-decent tool to help. It’s made my own workflow significantly cleaner and it’s been running in my daily toolkit since day one.

The source is on GitLab. You can install it with:

uv tool install git+https://gitlab.com/lowercasenumbers/htb-admin.git

Issues and contributions are welcome. I built this for myself, but if other people find it useful, that’s the whole point.