boothstrap.sh

A terminal portal for MLH booths: short AI agent challenges, then a clean slate.

A station is a MacBook at an MLH booth running boothstrap.sh, a terminal portal. An attendee walks up and plays 5–15 minute challenges, each teaching one AI or technology skill with an AI agent as their guide (Pi today). When they leave, the station wipes itself for the next person.

v0.0.1 (MVP), macOS only.

Rendered from the real screens by node bin/readme-gif.ts; the agent's replies are scripted.

How it works

1. 👋 Walk up and enter a name on the Welcome screen.
2. 🎯 Pick a challenge from the portal.
3. 🤖 Play it with the agent in the station's pane as each step checks off.
4. ⭐ Earn points, and optionally save an email to keep them.
5. 🧹 Leave, and the station resets for the next person.

Run a station

A station is a Mac running Terminal.app, with Node ≥ 26.4, Google Chrome in /Applications, fd and ripgrep for Pi (brew install fd ripgrep), and a user name of at most 14 characters. Install boothstrap, prepare the station once, check it before doors open, then start the station in Terminal:

npm install -g @mlhacks/boothstrap
boothstrap setup
boothstrap doctor
boothstrap

npm's warning that it skipped dependency install scripts is expected; none are needed.

Contributors run a clone instead: after npm ci, node src/index.ts takes the same commands. Updates and rollback are pending in #168. Setup checks the macOS Automation permission that tiling needs. Station setup, doctor, and clean covers each step and check.

Write a challenge

A challenge is a package in the MLH challenges monorepo, in the format the challenge spec defines. The same package runs in plain Pi, so you can iterate without a station. Authoring challenges walks through both.

Contribute

Development also runs on Linux; TypeScript runs on Node with no build step. Only the npm package is compiled; see releasing.

npm ci
npm test       # unit and integration tests
npm run lint   # Biome, tsc, and markdownlint
npm run demo   # the real station on a Mac, against local stand-ins

npm test also needs Agent Vault and a hosts line; local development covers them and the demo. package.json lists every script.

Documentation

For staff running stations:

• Station setup, doctor, and clean
• Event config: the JSON each event publishes.
• Booth API contract: the HTTP API stations call.
• Identity encryption: sealing and decrypting participant emails.
• Releasing: building and publishing the npm package.

For challenge authors:

• Authoring challenges
• Challenge spec: the package format.
• Challenge packages: how a station installs them.

For contributors:

• Local development and cloud agents: setting up a laptop or a cloud VM.
• Development style, with guides for TypeScript, testing, and Markdown.
• AGENTS.md: working rules for coding agents.
• App wiring: startup, the flow's effects, and the TUI feed.
• Agent launch: how boothstrap launches and restarts Pi.
• Browser session: Chrome for browser challenges.
• TUI: frames, screens, and the app shell.
• Vault client: Agent Vault tokens and the vault tests.

Design and specs:

• MVP design: flows, requirements, telemetry, and the reset model.
• Research: dated spikes, mockups, and audits; snapshots, not current rules.

License

boothstrap.sh is released under the MIT License.