Repository navigation
v3: offline-first board, setup files instead of enrollment, core/online split - #5
Conversation
setup.sh is the installer every board uses. packaging/install.sh with lib/common.sh, appliance-policy.sh and update.sh was a parallel chain for the release tarball and `make deploy`/`install-remote`, referring to a Packer image that does not exist; packaging/uninstall.sh duplicated the top-level uninstall.sh. The packaging/luks scripts claimed a caller in setup.sh that never existed. Nothing ran any of them. Gone with them: the Makefile's deploy, install-remote and tarball targets, the tarballs in the release, the LUKS line in .gitattributes, and a committed .claude/settings.local.json. uninstall.sh stays the one uninstaller. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
It needs an interactive sign-in with a Raspberry Pi ID on every board, so it could never be part of an unattended setup or handed over. setup.sh no longer installs it, enables linger for the admin user or masks wayvnc for it, and purges it from boards an earlier setup installed it on. SSH as the admin user is the maintainer's way in. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Safe mode counted starts in /var/lib/musallahboard/crash-counter and set a flag after three, which only went into telemetry.Snapshot; the heartbeat's wire format dropped it, so it never reached the backend, and nothing on the board acted on it. The self-updater's probation, not safe mode, is what handles an agent that does not stay up. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The second backend socket, /api/refresh-musallahboard, is being deleted on the backend: it dates from the hosted kiosk, was unauthenticated, and duplicated the agent WebSocket. "Content changed" moves to a frame on that WebSocket. Until then the 30-minute sync and config.refresh still bring content in; Trigger keeps folding a burst of requests into one sync. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
restorePort patched the backend URL's port into a returned WebSocket URL that had none, on the theory that the backend builds the URL from the request's Host header. It does not: AgentEnrollmentController returns the configured musallahboard.agent.websocketUrl. The URL is now saved as the backend sends it, after the same wss-on-the-backend's-host check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
No code changes, only import paths. internal/core is the offline board: packages, trust, state, the stores, the importer, the local and upload servers, the clock, USB, the self-updater, the kiosk and the release- channel update scheduler. internal/online is the optional fleet layer: enrollment, content sync, the backend WebSocket, telemetry and remote commands, and the generated API client. internal/version stays where the release build's -ldflags expect it. The Makefile's -X for the compiled-in release keys follows trust to internal/core/trust (a wrong path there is silently ignored by the linker), and CI regenerates the API client in its new directory. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The reporter that shows an agent update's outcome on the board read the updater's Outcome and status constants and nothing else of its own; the two halves of one update now live in one package (report.go beside the updater), and the cross-package import is gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Everything that touches Chromium is now internal/core/kiosk: the CDP client (cdp.go), the update screen driven over it (screen.go), and the watcher that returns the kiosk from an error page and heals a crashed or hung page (heal.go, moved out of cmd/agent with its tests). The healer's kiosk restart no longer borrows the kiosk.restart remote command's handler; both call kiosk.Restart, so the core does not depend on the online command layer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The heartbeat's telemetry was collected into telemetry.Snapshot and then copied field by field into wsclient.Telemetry, the wire shape, by TelemetryFromSnapshot. Only the heartbeat ever used it. Telemetry is now collected straight into the wire struct, in wsclient beside the frame it goes in; unread values are still nil and kioskAlive is still always sent. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The release channels are public files on GitHub, but the code that read
them lived in the content syncer, which is only built with a device key
and a safe backend config. A board that was never enrolled, or whose key
was unreadable, therefore never updated its software online ("this
board cannot reach the release channels (no device key)").
The channel loop, fetch, download and checks move unchanged from
boardsync into the update scheduler (internal/core/updates), which owns
what they find anyway. Any board with a network now follows the
channels when auto_update is on, and `update now` always checks them.
boardsync is left with content and weather; the shared HTTP client
settings move to netinfo.NewHTTPClient, and the syncer's content download
uses fsutil.CopyFileSync.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A board with no agent.toml used to sit in awaitEnrollment: no local server, no importer, no USB, only a splash with its IP address pushed over CDP, until someone enrolled it online over SSH. A board that never had internet could not show anything, even with content on a stick. Now every board runs the whole core. agent.toml is optional (missing is an unprovisioned board) and every key in it is optional; key_path is gone (the key is always /etc/musallahboard/agent.key; old configs that carry it still load). The daemon holds it as a config.Live, which the importer, local server and upload server read the board's identity from. - An unprovisioned board serves a "This board is not set up yet. Plug in its setup USB stick." page at every page path, with its hostname and address for a maintainer, the import banners, and a reload once it has an identity. The API, media and update screen work as before. - The USB helper reads sticks on an unprovisioned board, and on a board whose config it cannot read. - The online layer (content sync, weather, the WebSocket and commands) moves from cmd/agent into internal/online.Layer. It runs only when agent.toml names a device and a backend, has a WebSocket URL from an enrollment, and the device key loads and the transport check passes; it starts over when those settings change. Its state reaches /api/local/status as before. - `enroll` keeps the board's other settings, refuses only a board that is already enrolled (has a WebSocket URL) without --force, and restarts the agent so it takes effect. - One chownToDirOwner, in fsutil, for config, key and USB helper files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
setup.sh carried a copy of every systemd unit, udev rule, the sudoers
file, the modules-load list and start-kiosk.sh ("KEEP IN SYNC with
packaging/"), and the copies had drifted (start-kiosk.sh's
--password-store=basic was only in setup.sh). The RTC rule and unit
existed only inline in setup.sh.
packaging/ is now the only copy. The agent embeds it, and
`musallahboard-agent install-system [--rtc]` writes each file (atomically,
with its mode; the sudoers file only after `visudo -c` passes), removes
files earlier versions installed, reloads systemd and udev, enables the
units and loads the USB filesystem modules. It is idempotent: a file
with the right bytes and mode is left alone. setup.sh calls it, and
`setup.sh --service-port --rtc` calls it with --rtc. The RTC files move
to packaging/rtc/.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The kiosk loaded the URL in /etc/musallahboard/kiosk-url, which the agent wrote with a constant once a board was enrolled; a path unit and a reload service restarted the kiosk when it changed, and until then the kiosk showed waiting.html, into which the agent pushed the IP address over CDP. With every board served by the local server, all of that is dead weight. start-kiosk.sh now always opens starting.html#http://127.0.0.1:8080/. Gone: internal/core/kioskurl, internal/core/splash, waiting.html, `splash install` (and the updater's call to it after an update, and its write access to /usr/share/musallahboard), musallahboard-kiosk-watch.path, musallahboard-kiosk-reload.service, and config.refresh's kiosk-url rewrite. install-system removes the old units, kiosk-url and waiting.html from boards set up before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A new .mbu type, "provision" (spec C1). The manifest binds it like a content package (deviceId, sequence, createdAt) and lists exactly one file, provision.json: format 1, deviceId, displayName, sequence, issuedAt, and for a board that will be online backendUrl with a base64url 32-byte claimSecret (both or neither). It is verified against the pinned content keys only, never accepted unsigned, and provision.json must name the device and sequence of the signed manifest. The importer takes setup files first in a batch, so a setup stick's content installs in the same batch, bound to the identity just adopted: - an unprovisioned board adopts any valid setup file, unless the batch holds setup files for several devices (a USB kit), when it takes none and says "This USB stick sets up more than one board"; - a provisioned board takes a file for its own device id with a strictly newer sequence, which updates its name and, if present, its backend and claim secret (a new backend clears websocket_url, so the board claims there); same sequence is "unchanged", older "outdated"; - another device's file is skipped like another board's content. A file without a backend never removes one. The daemon writes agent.toml itself, in one atomic save under the config lock: agent.toml is already the daemon's file in the daemon's directory, so a root step would guard nothing. The setup file can carry an identity and a backend address, never keys, software or anything that runs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The console's USB kit for every board puts a setup file and a content package per board, the board app and the agent on one stick: 42 files for 20 boards. The helper took at most 16. It now takes up to 64 files, and at most 4 GiB in all (a bound it did not have, on what lands on the SD card); each board then ignores the packages for other boards and anything not newer, as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A board updated only by USB stick is visited every few months, not every few weeks; the payload is a few KB a day, so a quarter of content costs nothing on the stick or the board. mbu.MaxContentDays (the range a content package may cover) and the content_days bound for synced packages are both 92 now (spec C4). The backend and console raise their own limit to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A setup file for an online board carries the backend URL and a one-time
claim secret (spec C2). Until the board has a WebSocket URL, the online
layer claims instead of running: it makes the Ed25519 device key if
there is none (saved before it is first sent, so every retry claims the
same key; the private key never leaves the board), checks the backend
URL is https (or insecure_dev), and posts
POST /api/agent/claim
{deviceId, publicKey (base64 std), proof, agentVersion, hostname}
with proof = base64url, unpadded, of HMAC-SHA256(claim secret bytes,
deviceId + "\n" + publicKey). The reply is the enrollment reply; the
WebSocket URL must be wss on the backend's host as for enroll. The URL is
saved to agent.toml and the secret dropped, and the layer starts over
online exactly as an enrolled board's. Failures retry from one minute,
doubling to an hour (a 409, a different key already bound, waits the
hour and says to reset the board in the console); the board itself never
waits on any of it.
The daemon cannot pin keys (trust.json is root's): it warns when the
backend's content keys are not pinned. setup.sh pins the content key.
`enroll --token` stays the maintainer path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The backend now tells a board its content may have changed with a
{"type":"content_changed"} frame on /api/agent/ws, where the deleted
refresh stream used to (spec C5). The client hands it to the content
syncer's Trigger, which now syncs 10 s plus up to 20 s of jitter later
(so a fleet told at once does not sync at once) and folds every further
request before then into the same sync. config.refresh uses the same
Trigger.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
GET /api/musallah/payload already kept serving the installed bundle's last day after it ended. It now adds two top-level fields to every payload (spec C6): "lastDay" (the bundle's, YYYY-MM-DD) and "expired" (true once today, in the bundle's time zone, is past it), so the board app can show prayer times and an "out of date" note and hide what is dated, instead of last week's posters. The weather overlay goes through the same small overlay. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
internal/core/imports_test.go runs `go list` over internal/core/... and fails if any core package, its dependencies or its tests import anything under internal/online. That is the rule the layout exists for: a board without the online layer loses no board function. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A board that never goes online cannot fetch the content key, and without it accepts no content and no setup file. setup.sh now asks for it (or takes MB_CONTENT_KEY / --content-key for unattended installs), checks it is the base64 of 32 bytes, and pins it with `musallahboard-agent trust add content`, the root-only path that checks the key and trust.json again and leaves a key already trusted alone, so a re-run is safe. Its summary and header no longer end in "enroll this device": the next step is plugging in the setup USB stick exported from the console, and `enroll --token` is mentioned as the maintainer path. --service-port no longer requires an enrolled board. vm/mbvm passes MBVM_CONTENT_KEY to setup.sh and runs install-system after swapping in an agent. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
testdata/sample-provision.mbu is an online setup file made by the backend's packager (device 00000000-0000-0000-0000-000000000001, "North Musallah", https://api.example.org, signed by its test content key 65b60673d6ed884b). It is imported through the real verification and provisioning path, and the agent.toml written is checked field by field; signed by an untrusted key it is refused. The content_changed test uses the frame's real envelope (seq, sessionId). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
`enroll` moves to the administration commands as the maintainer path; the help says a board is set up by its setup file. Stale comments about enrollment being required go. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
netinfo.Info's Equal and Online served awaitEnrollment's poll loop, and keystore.PublicKeyOf only its own test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
docs/architecture.md describes the offline-first board: principles with the optional fleet layer, the board states agent.toml defines, the code layout and the core/online import rule, the provision package type, setup files and the claim (section 9.8), content up to 92 days, the payload's run-out fields, the setup screen, content_changed, release channels without a key, the USB caps, install-system and the embedded system files, and the configuration keys. The v1 history, the enrollment splash, kiosk-url and the refresh stream are gone from it. The README quickstart is now: install with setup.sh (it asks for the content signing key), then plug in the setup stick exported from the console; enroll --token is the maintainer path. vm/README follows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 365a02b11d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| setInterval(function(){fetch('/api/local/status',{cache:'no-store'}).then(function(r){return r.json()}) | ||
| .then(function(s){if(s&&s.deviceId)location.reload()}).catch(function(){})},3000) |
There was a problem hiding this comment.
Refresh the setup screen's network address after connection changes
If an unprovisioned board loads this page before receiving a DHCP address, or an operator subsequently connects ethernet, its displayed address never updates. handleApp collects network information only when rendering the page, while this polling loop reloads only after a device identity appears; /api/local/status does not supply updated network information either. This regresses the previous enrollment screen's periodic network refresh and leaves the operator without the on-screen IP needed to SSH into the board. Refresh the displayed network information while the board remains unprovisioned.
Useful? React with 👍 / 👎.
The address was collected once, when the page rendered, so a board that got its DHCP lease or an ethernet cable later kept showing no address. The page now refetches it from /api/local/where every 10 s. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The offline-first restructure. A board is fully functional without ever going online. It gets its identity from a signed setup file on a USB stick that the console exports. Fleet management (claim, WebSocket, telemetry, commands) is an optional layer on top.
Part of a four-repo change:
content_changedStructure
internal/core/*is the offline board.internal/online/*holds claim, enroll, sync, wsclient, commands and devauth.internal/core/imports_test.gofails the build if core imports online.agent.tomlhas a device id and a backend URL.New behaviour
provisiontype): signed with the content key, carrying the device id, display name and sequence, plus an optional backend URL and claim secret.enroll --tokenstill works as the maintainer path.content_changedframe: triggers a sync about 10 s later, with up to 20 s of jitter, coalescing repeats./api/musallah/payloadaddsexpiredandlastDay. Content may cover up to 92 days.MB_CONTENT_KEY) and pins it.musallahboard-agent install-systemwrites the systemd units, udev rules and sudoers files embedded in the binary. setup.sh calls it instead of keeping inline copies.Removed
kioskurland its two kiosk path/reload units.claude/settings.local.jsonShell, units and packaging went from 6,463 to 3,044 lines. Non-test Go is roughly flat (15.2k to 15.6k): about 1.7k lines were removed and about 2k added, mostly for provisioning, claim,
install-systemand the setup screen.Merged packages
agentupdateintoselfupdatecdp,updatescreenand the kiosk healer intokiosktelemetryintowsclientUpgrading enrolled boards
An existing
agent.tomlwith a device id, backend URL and WebSocket URL loads unchanged, and the online layer starts as before. Old kiosk units keep working until setup.sh is re-run, which removes them.Testing
go build ./... && go vet ./... && go test -race ./...pass.content_changedcoalescing, the run-out fields,install-systemidempotency, and the import rule.importof the setup file wroteagent.toml, the device key was generated, and the claim retried while offline.vm/mbvm(no QEMU here) and real Pi hardware.Generated by Claude Code