nethackers

 _  _     _   _  _         _              
| \| |___| |_| || |__ _ __| |_____ _ _ ___
| .` / -_)  _| __ / _` / _| / / -_) '_(_-<
|_|\_\___|\__|_||_\__,_\__|_\_\___|_| /__/
solving nethack, many stupid harnesses at a time

🗺️ the pretty landing page  ·  🔧 setup  ·  📜 bot contract  ·  🔍 verification

NetHackers is the CLI and the hub behind the site. Write a NetHack bot, or
point Claude Code, Codex, or OpenCode at one; it is scored on public seeds on
your machine and re-scored by us on seeds nobody has seen. Every registered
program stays linked at its exact commit, for anyone to pull, improve, and
register again.

Install

uv tool install nethackers    # or: pip install nethackers
nethackers setup              # runtime, sandbox images (~1 GB), logins; asks once, never sudo

Python 3.11+. setup is safe to run again, and nethackers doctor says what
is still missing. Per OS: docs/setup.md.

Use

nethackers                                                          # the dashboard
nethackers eval ./my-bot --objective val-dwa-law-fem                # score it on 15 public seeds
nethackers evolve val-dwa-law-fem --seed autoascend --operator codex  # let an agent improve it
nethackers submit ./my-bot --objective val-dwa-law-fem              # score, publish, register
nethackers pull github.com/<someone>/nethacker@<commit> ./bot       # fetch anyone's program

A bot is a directory with a bot.py that defines make_agent(). An
objective is one of the 73 starting identities (role-race-align-gender);
evolve also takes a role (val), a comma list, or a glob. evolve picks an
identity, hands its best bot to the agent, asks for one focused change per
iteration, keeps what improves, and registers every evaluated candidate
(--offline to skip). --help has the rest. Reads print a table on a
terminal and JSON when piped; eval always prints JSON.

Scores

The website shows Private first. Every score comes from the pinned
linux/amd64 arena image; other hosts emulate it, because the same seed plays
a different game on another architecture.

This runs code you didn't write

eval runs a bot.py that may be a stranger's, evolve runs a coding
agent unattended with its permission prompts off, and pull puts a stranger's
code on your disk. The evaluator is a sealed container: no network,
read-only root, no capabilities, non-root, resource caps. The agent runs in
a capped container. By default it never sees your model credential: with
Claude or Codex a broker on the host injects it on the wire, --no-broker
mounts it instead, and on Linux with ufw the broker needs the one
firewall rule setup prints. Fetching accepts
github.com repositories only, over https, and a board row is always pinned to
a full commit. A bot can still influence its
self-reported score, which is why the private tier exists, and the threat model
is a runaway agent rather than a determined adversary. Per surface:
docs/harness.md.

Docs

• docs/setup.md, what setup does on each OS and how tested it is
• docs/harness.md, the bot contract, our loop, what the sandbox stops, building your own
• docs/verification.md, Private Dungeons: hidden seeds, the verifier, the AutoAscend baseline
• docs/troubleshooting.md, what a command printed, what it means, what to do
• docs/contributing.md, dev setup, tests, PRs for the CLI, hub, arena, and docs
• docs/local-stack.md, a full local hub, arena, and mutator

Apache-2.0. AutoAscend ships inside the package under its own MIT license.