Working with Nix

Getting started gave you commands that just work. This chapter is for making them nicer — shorter, pinned for a paper, or pointed at a local checkout. None of it is required.

The command forms

The same run has several spellings. They differ only in ceremony, not in what they do — and condition identity always uses the resolved git revision the runner records, never the ref you typed, so the pretty and pinned forms bucket identically.

Making them shorter: the flake registry

Registering adb once lets you write adb#… instead of the full GitHub URL — the same way nixpkgs is already registered for you:

nix registry add adb github:antimemetics-institute/agentdatabank

The registry ref floats to the latest commit, which is fine: the runner records the resolved revision, so your run is still exactly identified.

Always fetching the latest

Nix caches downloads: once it has fetched main (as a tarball or a flake ref), it reuses that copy for a while rather than asking GitHub again — so a rerun can silently execute code that’s a few commits behind. The “always fetch latest” checkbox in the ⚙ command settings (on by default, GitHub source only) makes every command re-check: --tarball-ttl 0 on nix-build, --refresh on nix run, --option tarball-ttl 0 on nix-run. If nothing changed upstream, the check is a cheap no-op — nothing is re-downloaded or rebuilt. Untick it to save the round-trip, or when you’re running from a local checkout (where there’s no download to go stale and the checkbox doesn’t apply). Pinned …/<rev> commands don’t need it either — a pin resolves the same way every time.

The experimental-features flag

nix run needs two experimental features, nix-command and flakes. The commands in this guide opt in explicitly, per command — nothing global to configure, works on a stock install:

nix run github:antimemetics-institute/agentdatabank#adb-web --extra-experimental-features 'nix-command flakes'

(The flag rides with the nix run invocation, before the -- that separates the experiment’s own arguments.)

If you use flakes regularly you can enable the features permanently and drop the flag. How depends on your setup — a NixOS or nix-darwin configuration, Home Manager, or a plain nix.conf — see the official wiki’s Flakes page for each. Once enabled, tick “flakes enabled globally” in the ⚙ command settings and every command in the guide sheds the flag.

Running without flakes

If you’d rather not enable flakes at all, the repo’s default.nix is a plain classic entrypoint — no flakes anywhere in the path, pinned to the same nixpkgs, building exactly the closure the flake builds. Two ways to run through it, each a “running with” tab in the ⚙ command settings: pick nix-run or nix-build and every command in the guide rewrites to that form.

Via nix-run (in nixpkgs) — a classic-Nix runner that, like nix run, resolves a package’s meta.mainProgram and passes program arguments after --. Point it at a tarball of the repo (or . inside a checkout):

nix-run https://github.com/antimemetics-institute/agentdatabank/archive/main.tar.gz \
    -A experiment-inspect-hello -- \
  --set model=mockllm/model \
  --set limit=0 \
  --set epochs=1 \
  --set 'generate_args={}'

Experiments are -A experiment-<name>; the tools are -A adb-runner and -A adb-web. Don’t have nix-run installed? Run it from a throwaway shell — wrap the whole command (the nix-run tab’s “installed globally” checkbox picks between these):

nix-shell -p nix-run --run "nix-run … -A experiment-inspect-hello -- …"

Via stock nix-build — nothing installed beyond Nix itself. The exec.<name> attributes (bare app names, same names nix run uses) have outputs that are the executables, resolved through meta.mainProgram, so it’s a one-liner with no ./result litter and no binary-name knowledge:

$(nix-build --no-out-link https://github.com/antimemetics-institute/agentdatabank/archive/main.tar.gz \
    -A exec.inspect-hello) \
  --set model=mockllm/model \
  --set limit=0 \
  --set epochs=1 \
  --set 'generate_args={}'

One honest caveat for both: classic Nix has no evaluation cache, so every flakeless invocation re-evaluates the whole tree (tens of seconds) where flake commands are instant after the first run. Flakes are the happy path; this door exists so nobody is locked out.