# APESS 2026 Workshop — Laptop Prerequisites **"Design the Agent Your Building Deserves" · 27 July · a 5-hour build session.** Do these **before you arrive** so we spend the session building, not installing. > Companion docs: [`WORKSHOP-FLOW.md`](./WORKSHOP-FLOW.md) (what you'll do) · > [`ONBOARDING.md`](./ONBOARDING.md) (how the board comes up). --- ## How it runs (so the prerequisites make sense) Each team runs the **whole platform on its own laptop** — a small Docker stack (web + API) that comes up with **one command**. Your **Arduino Uno Q** plugs into that same laptop over **USB**. Everything on your **laptop** is **localhost**: the browser, the API, and the board all talk on your machine. Once the stack is up and the board is plugged in, it **auto-connects to your team — no codes, no accounts.** The one thing that leaves the box: the **board** reaches its **AI cloud brain over the venue WiFi** — but *we* pre-join each board to that network before you get it, so there's nothing for you to set up. > **Most teams are on Windows 11** (a few Macs). Both work the same way; the only difference is the > command you run to attach the board — see the Windows / macOS notes below. So each team needs **one "board laptop"** with a few things pre-installed. Extra teammates just need a browser pointed at that laptop. --- ## TL;DR - **Board laptop:** install **Docker**, **adb**, and **git**; pull the workshop bundle ahead of time. - **Everyone else:** a modern browser is enough. - **No accounts, no API keys** — the AI cloud access is baked into the board app. --- ## What the workshop provides (do NOT install) - **Arduino Uno Q (4 GB)** board + **USB-C cable** — one per team. - **ADXL355 accelerometer(s)** + wiring — the FabLab kit. - **Cloud AI access** — baked into the board app. **No Anthropic/Claude account needed.** - **Boards pre-joined to the venue WiFi** — the board uses it only to reach the AI cloud; you don't configure any network. - The **web app** itself (you run it locally from the bundle below). --- ## The team "board laptop" — pre-install these (large downloads, do them at home) 1. **Docker** — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux). Verify: `docker run hello-world` succeeds. 2. **adb** (Android platform-tools) — the USB bridge to the board. Verify: `adb version` prints a version. (macOS: `brew install android-platform-tools`.) 3. **git** — to fetch the workshop bundle. Verify: `git --version`. 4. **~10 GB free disk** — Docker images (web + API) + the board's App Lab base image (~0.9 GB). 5. **The workshop bundle, pre-fetched** so you're not downloading on the WiFi at 14:00: ```sh git clone # [instructor: final repo/bundle URL] cd /deploy/lan docker compose up -d --build # pre-build the images once, at home docker compose down # then stop until the day ``` (Also pre-pull the App Lab base image on the board — it's fetched on first Run.) ### On Windows 11 (most teams) - **Docker Desktop** with the **WSL2 backend** (enable it in the installer). `docker run hello-world`. - **adb** — download **Android SDK platform-tools for Windows**, unzip it, and add the folder to your **PATH** (so `adb version` works in a new terminal). *Run adb on Windows itself — not inside WSL.* - **Git for Windows** — gives you `git` + `curl` (used by the stack). - **Uno Q USB driver** — plug the board in; Windows usually installs a driver automatically. It's working when **`adb devices`** lists the board as `device` (see the check below). If it shows nothing or `unauthorized`, reinstall the driver / re-plug and accept any prompt on the board. - To attach the board you'll run **`connect-board.bat`** (double-click) or **`connect-board.ps1`** — both live in `deploy\lan\`. ### On macOS (a few teams) - Docker Desktop, `brew install android-platform-tools` (adb), `git`. Attach with `./deploy/lan/connect-board.sh`. ### First check: does adb see your board? The #1 thing to get right up front. Plug the Uno Q in over USB and run: ``` adb devices ``` You want a line ending in **`device`**, e.g. `65301572 device`. If it's empty, `offline`, or `unauthorized`: re-plug, try a different USB port/cable, and on Windows reinstall the USB driver. **Get this working before the day** — everything else assumes adb sees the board. ## Everyone else on the team - A **current browser** (Chrome/Edge recommended; Firefox works). That's it — you'll open the board laptop's local URL. --- ## What you'll do on the day (no accounts, no claim codes) 1. **Bring the stack up:** `cd deploy/lan && docker compose up -d` → open **`http://localhost:8090/`**. 2. **Get the board app:** in Team Registration, click **Download the board app** (served by your own stack), then on the Uno Q: **App Lab → Import an app → pick the zip → Run.** `[instructor: confirm the App Lab access flow for the room]` 3. **Attach the board:** plug the Uno Q into the board laptop over USB, then: - **Windows:** double-click **`deploy\lan\connect-board.bat`** (or run `.\connect-board.ps1 -Watch` to keep it auto-attaching on re-plug). - **macOS:** run **`./deploy/lan/connect-board.sh`** (or `--watch`). 4. **It just connects:** type your team name and the board **auto-binds to your team** — no code. Unplug/replug is handled automatically; a **Disconnect / Reconnect** control is there if you need it. 5. **Build:** walk Modules 1–3, submit your Agent Design Document. --- ## Pre-flight self-check (before you travel) - [ ] **(Board laptop)** `docker run hello-world` works. - [ ] **(Board laptop)** `adb version` and `git --version` work. - [ ] **(Board laptop)** Ran `docker compose up -d --build` once (images built) and opened `localhost:8090`. - [ ] Laptop charged + charger packed (5-hour session). - [ ] A current browser. --- ## No accounts to create - ❌ No Anthropic / Claude account or API key — the cloud key is baked into the board app. - ❌ No claim codes — in this local USB setup the board auto-connects. - ✅ Everything is localhost; nothing depends on the room WiFi. --- ## Notes for the curious (why these specific tools) - **Docker** runs the web + API stack in one command, identically on every laptop. - **adb** carries the board over USB; the API (in a container) reaches it via `host.docker.internal`. - The web runs on **`:8090`** (not `:8080`) because `:8080` is the board's own port, forwarded over adb. --- ## Instructor checklist (finalize before publishing to students) - [ ] **The workshop bundle URL** (git repo or a downloadable archive) students clone/pull. - [ ] **Pre-built image distribution** — consider publishing `apess-web`/`apess-api` to a registry (or a USB `docker load` bundle) so teams `docker compose up` without a source build on the day. - [ ] **Exact Arduino App Lab access** on the Uno Q for the room (and whether it needs any login). - [ ] **Pre-seed** the ~0.9 GB App Lab base image locally so 9 teams don't each pull it live. - [ ] Decide whether `connect-board.sh --watch` runs via a small launchd/systemd unit (hands-free re-plug).