_ _ _ _ _ _ | \| |___| |_| || |__ _ __| |_____ _ _ ___ | .` / -_) _| __ / _` / _| / / -_) '_(_-< |_|\_\___|\__|_||_\__,_\__|_\_\___|_| /__/ 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
| Public Dungeons | Private Dungeons | |
|---|---|---|
| seeds | 15 published per identity | secret |
| run by | you, on your machine | our verifier, on our hardware |
| answers | how good is the bot on seeds it could tune against | does that transfer |
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, whatsetupdoes on each OS and how tested it isdocs/harness.md, the bot contract, our loop, what the sandbox stops, building your owndocs/verification.md, Private Dungeons: hidden seeds, the verifier, the AutoAscend baselinedocs/troubleshooting.md, what a command printed, what it means, what to dodocs/contributing.md, dev setup, tests, PRs for the CLI, hub, arena, and docsdocs/local-stack.md, a full local hub, arena, and mutator
Apache-2.0. AutoAscend ships inside the package under its own MIT license.
1 maintainer
Metadata
1 maintainer
Release files for nethackers 0.37.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nethackers-0.37.3.tar.gz | 4.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nethackers-0.37.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.4 MB
Release files / nethackers-0.37.3.tar.gz
| Download URL | nethackers-0.37.3.tar.gz |
|---|---|
| Size | 4.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f90847320e25ab8f0a0ef98d6f2703c1d914ea5d4344e12ce4f63e1a76c3ec46
|
|
BLAKE2b-256 checksum How to use checksums |
61589a6ac6ad298d4053bd0c9778484ab9d1d6b9907b89ce73dbe9b5cfde5443
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / nethackers-0.37.3-py3-none-any.whl
| Download URL | nethackers-0.37.3-py3-none-any.whl |
|---|---|
| Size | 715.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9638c00b8fec257b23ae476f4d3a93d6f34586d26f77b66577ac5532c7eded79
|
|
BLAKE2b-256 checksum How to use checksums |
1ecf6576681ee7dd456bc58dad1c14cee2a3aa7a2e9102c4c4907f38acb86776
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
