Skip to content
SPEED DEMON

KICKSTART the starting pack

Your first run, in five steps

The template is a working entry for all four tracks: the organisers' naive reference, packaged exactly the way the live board builds and runs it. Clone it, check it end to end, then replace the reference with your own code and watch the board move.

Use the template ↗ See the board →

01 five steps

From zero to on the board

  1. 01

    Use the template

    Open speed-demon-starter and press Use this template to make your own repo. It can stay private until code freeze.

  2. 02

    Install the board app

    Install the Speed Demon Board app on that repo. It gets read-only access to the repos you pick and nothing else.

  3. 03

    Register your team

    Fill the submission form with your repo URL and the tracks you are entering. One form per team.

  4. 04

    Push to speed-demon

    The speed-demon branch is the default, so a plain git push does it. The board builds every track-* folder and runs it once on the full public dataset. Your result appears on the board within minutes.

  5. 05

    Make it fast

    Log every step in the track's PERF.md with the board run ID that measured it. At code freeze (Nov 2, 15:00 UTC) make the repo public under an OSI licence.

One repo per team holds all your tracks, as track-a to track-d. Delete the folders of the tracks you are not entering. A folder you leave unchanged is the reference itself, so the board reports it as unchanged and does not run it.

02 your repo

What a track folder holds

Each track is built and scored on its own folder. Your other tracks never count toward it, and code shared between tracks is copied into each folder that uses it and counts in each.

file what it is
Dockerfile Builds the folder offline, from an allowlisted image pinned by digest
.speed-demon.toml Track, team, language, dependency count; set team
PERF.md Your optimisation log, worth 8% of your total
README.md Your approach, your dependencies, your next 24 hours
your code Replace the reference with your own; one output file to /out

03 how it runs

The contract your program meets

Your program reads its inputs from /data (read-only) and writes exactly one file to /out, then exits 0. TRACK is set to a, b, c or d. There is no network at build or run time, so commit your dependencies.

limit value
CPU 12 threads · 6 P-cores · turbo off
Memory 8 GB · no swap
Processes 512
Scratch /tmp · 1 GB tmpfs
Network none · build and run
Filesystem read-only · /data is ro · write one file to /out
Board time cap 3x the reference
Final time cap 10x the reference

Your output must match the reference's byte for byte: the correctness gate is a SHA-256 of the one file you write. The output names are summary.txt (A), results.txt (B), aggregates.txt (C) and distances.txt (D).

04 before you push

Check it locally first

check.py builds a track offline and runs it under the board's sandbox, then prints the output's hash. Run it once on the unchanged folder to learn the right answer, then pass that hash back so the check fails on a wrong answer.

# generate data with the public generators (seed 1, 10% sample)
git clone https://github.com/hackathon-raptors/speed-demon-2026
python3.13 speed-demon-2026/generators/a_ingest.py --seed 1 --scale sample --out data/a

# build a track the way the board does, then compare the output hash
python3 check.py a --data data/a
python3 check.py a --data data/a --expected <sha256>

The full datasets and their hashes are published at kickoff, Oct 30, 15:00 UTC, linked from this site. On Colima, keep the repo and the data under your home folder so Docker can mount them.

05 your own language

Bring any allowlisted toolchain

Replace the folder's contents with your code and a Dockerfile that builds it offline. A two-stage build keeps the image small. Every allowlisted image and its digest is in allowlist.json.

FROM rust:1-slim-trixie@sha256:1a939748a7cbab172de91a014e3804a97af1394a8c844faa67fce9401c4e40fb AS build
WORKDIR /src
COPY . .
RUN cargo build --release --offline

FROM debian:13-slim@sha256:62bd423aeee912639ca8ee681c2b762cb3e25137e0a92b20be455898a9f034ad
COPY --from=build /src/target/release/solution /app/solution
ENTRYPOINT ["/app/solution"]

Here solution is the package name in your Cargo.toml. Each direct runtime dependency costs a little on the D axis, so count them in .speed-demon.toml. See the full list at /allowlist.json.

06 guardrails

What the board refuses before it builds

  • A FROM that is not on the allowlist, or not pinned by digest.
  • ADD of a URL or a git repo, and COPY --from an image (an earlier stage is fine).
  • A # syntax= line; cache, secret or ssh mounts; RUN --network, --security or --device; ONBUILD.
  • A build over 10 minutes, or an image over 2 GB.

07 common questions

Two things teams ask

Is source size counted across all my tracks?

No. Each track is scored on its own folder: track-a/ is Track A's build context and everything its source-size count covers, so your other track folders never count toward it. Code shared between tracks is copied into each folder that uses it, and counts in each.

One repository or several?

One repository per team, with your tracks as track-a to track-d on the speed-demon branch. Everything else about scoring and the gates is on the main page.

Use the template ↗ Ask on Discord ↗