Aeon-Bench-Pod AGENTS.md

AGENTS.md — AEON Bench Pod operating manual for AI agents

You (an AI agent) are here to deploy the AEON Bench Pod and run a COMPLETE, VALIDATED benchmark FOR a non-technical human, then hand them the results and a live link. This file is the whole manual. It is written so you need nothing else: copy-paste command blocks, the exact Run-tab flow, the engine/recipe reference, and the trust rules that decide whether a run ranks.

Two roles ship in one image: the pod (a local benchmark appliance on the human's own hardware) and the mothership (the public leaderboard at aeon-bench.com). This manual is the pod-operator role. The judge / run-loop contract that used to live here is preserved verbatim in the Appendix at the bottom.

Humans who want screenshots: point them at docs/walkthrough/README.md (illustrated walkthrough). The copy-paste TL;DR for humans is docs/pod-quickstart.md; the narrative guide is docs/run-a-benchmark.md.

---

THE SHORT VERSION — this is the whole job

If you read nothing else, do this. Four steps. Everything after this section is reference you only need when something is unusual or breaks.

1. Start the pod. Pull first, every session.

docker pull ghcr.io/aeon-7/aeon-pod:latest && docker rm -f aeon-pod
docker run -d --name aeon-pod --network host --gpus all \
  -v /var/run/docker.sock:/var/run/docker.sock -v aeon-pod-state:/root/.aeon \
  -v "$HOME/aeon-models:/models" -e AEON_MODELS_HOST_DIR="$HOME/aeon-models" \
  -v "$HOME:/host-home:ro" -e AEON_HOST_HOME_DIR="$HOME" \
  ghcr.io/aeon-7/aeon-pod:latest

No NVIDIA GPU? Drop --gpus all and swap --network host for -p 8091:8091. Check: curl -s localhost:8091/healthz.

2. Point at the model. One question: is it already running as a server?

ALREADY RUNNING  ->  aeon_pod_scan_endpoints()          # gives hf_guess + url
                     aeon_pod_run(hf_link=<hf_guess>, serve_url=<url>, verify_endpoint=true)
                     # on another machine, add remote_host="user@host" to BOTH

NOT RUNNING      ->  aeon_pod_run(hf_link="org/Model")  # pod downloads + verifies

ON DISK ALREADY  ->  aeon_pod_scan_models()             # gives repo id + path
                     aeon_pod_run(hf_link=<repo>, local_dir=<path>)