Files

T

Omar SobhandClaude Opus 4.8 838a0ba334 feat(onboard): distributable "APESS Onboard" App Lab app + packaging

Close the last onboarding gap: one shareable App Lab app a student imports
and Runs, no adb / no host install.

- package-onboard-app.sh: assemble a self-contained bundle — ZeroClaw binary
  (matrix_text + i2c_scan), single-agent config, skills, responder sketch, and
  the BAKED cloud token. Ships without .secret_key (each board mints its own)
  or a team Telegram token; dist/ is gitignored.
- onboard-app/config.toml: the canonical packaged config (proven anthropic.max
  single 'default' agent, matrix + i2c_scan allowlisted, Telegram-ready,
  secrets stripped).
- ONBOARDING.md: the full flow — instructor packages once, student imports +
  Runs, then the wizard. Notes APESS_URL (mDNS/per-team) + LAN reachability.

Validated on-hardware: a freshly-imported bundle mints its key, boots the
cloud agent, and runs the matrix + i2c_scan prompts in-container.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

2026-07-22 13:23:12 -07:00

3.1 KiB

Raw Blame History

APESS onboarding — fully containerized

A team needs two things running: the APESS stack on their laptop and the ZeroClaw node on their Uno Q. Both are containers. Nothing installs to a host.

LAPTOP:  docker compose up  →  apess-api + apess-web        (deploy/lan)
BOARD :  App Lab → Run       →  ONE container = daemon + relay + responder

Everything a team does — say-hi, the module chat, Refine, Telegram, the LED matrix, the I2C scan — runs through this. The board never needs the Zephyr flash toolchain or Linux /dev/i2c: the matrix is driven by a resident responder and I2C is scanned on the MCU (Wire), both over the RouterBridge relay.

1. Instructor — build the distributable app (once)

Bake the cloud token + all assets into a shareable App Lab app:

export ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-…        # baked into the bundle
./deploy/uno-q/package-onboard-app.sh              # → deploy/uno-q/dist/apess-onboard

The bundle contains: the ZeroClaw binary (matrix_text + i2c_scan), the single-default-agent config (matrix + i2c_scan allowlisted, Telegram-ready), the skills, the responder sketch, and the baked token. It ships without a .secret_key (each board mints its own on first Run) and without any team's Telegram token. The dist/ output is gitignored (it holds the token).

Import it once to smoke-test, or share it to students:

arduino-app-cli app new --from-app deploy/uno-q/dist/apess-onboard   # instructor test
# then in App Lab: open the app → Share → QR

2. Student — bring up their board (fresh OR pre-existing)

Open App Lab on the Uno Q (it ships with the board).
Import the "APESS Onboard" app (scan the QR).
Click Run. The node comes up in one container: it flashes the resident responder, launches the cloud agent, mints its .secret_key, self-registers to the team's APESS laptop, and scrolls a claim code on the LED matrix.

Fresh or pre-existing board is identical — Run is idempotent; it just (re)starts the node.

3. Student — the wizard (laptop)

Open http://<laptop>/ → Start the workshop.
Phase 1: team name + members → type the claim code the matrix is scrolling → board bound (state persists in localStorage; a Disconnect button is the only thing that drops it).
Say hi to the agent, optionally set up Telegram (writes the token to the node and reloads it), toggle Voice.
Phase 2: open the node, name the domain. Then the modules.

`APESS_URL` — how the board finds the laptop

The board self-registers to APESS_URL (default http://apess-api.local:3000). Options, easiest first:

mDNS: have the deploy/lan box advertise apess-api.local (zero-config for students).
Per-team: set APESS_URL in the app's .zeroclaw/apess-node.env, or pass APESS_URL=http://<laptop-ip>:3000 when packaging.

Reachability

The laptop's API must reach the board over the workshop WiFi. Verify the AP allows client-to-client traffic (many guest networks isolate clients). See deploy/lan/README.md.

3.1 KiB Raw Blame History