The terminal UI
The gateway console, in a terminal: every page of the web console, for a serial line, an SSH session, a Pi’s own screen, or the USB cable on a board that can be a USB device.
pulzr-tuiWhere it runs
Section titled “Where it runs”| How you get there | Sign-in | |
|---|---|---|
| Serial console | it is already there | the web console’s |
| SSH as root | pulzr-tui at the shell |
none: you are root |
SSH as pulzr |
ssh pulzr@<gateway>, as uid 1000 (auth.md); Ctrl-C disconnects |
the web console’s |
| Pulzar Cloud Console | a gateway’s page, as an organization’s admin | Pulzar Cloud’s; no shell |
| HDMI (Pi) | it is already there, when a screen was attached at boot | the web console’s |
| USB serial (Pi 4, Pi 5) | the port that appears beside the USB network | the web console’s |
From a shell there is nothing to sign in to — root can already do everything
the console can. On a port the TUI is the program, so it asks for what the
web console asks for: the local password while that is allowed, and the
offline recovery signature on an adopted gateway. A screen and a keyboard on a
gateway in a car park are physical access, and auth.md is plain
that physical access proves nothing. A port signs itself out after fifteen
minutes without a key.
From Pulzar Cloud
Section titled “From Pulzar Cloud”An organization’s admin on Pulzar Cloud gets this console on their gateway, not a shell: a root shell on PulzarOS is a copy of PulzarOS. Pulzar Cloud opens an SSH session whose only command is
pulzr-tui --remoteand, on a gateway that trusts its certificate authority, names that command
as the certificate’s force-command, so sshd runs nothing else whatever the
client asks for. In this mode there is no sign-in — the person signed in to
Pulzar Cloud, which records who opened the session — and no !. Changes are
journalled by: Pulzar Cloud; q ends the session. Pulzar staff still get a
shell from Pulzar Cloud.
Sign in with Pulzar, without a browser
Section titled “Sign in with Pulzar, without a browser”The web console’s handoff lands a token on a browser origin, and a terminal has none. So the terminal does it the way a television signs in to a streaming service:
- The gateway starts a sign-in with Pulzar Cloud and shows a code and a QR of
app.pulzr.net/gateway-access#signin=<code>. - Somebody signed in to Pulzar Cloud — on a phone, usually — opens it, sees which gateway is asking, and approves or refuses. That needs net-admin, as the browser handoff does, and is audited against them.
- The gateway polls, and collects the same fleet-signed token the browser
would have got, marked
aud: terminalwith the code in it.auth.ucaccepts that token only for the sign-in it started, and the web console accepts no token carrying an audience — so neither opens the other door.
Only the gateway can start or collect its own sign-in: both calls carry its
claim secret, as /report does. The code on the screen is an address, not a
key; seeing it lets you ask somebody to approve, and collect nothing. No token
is stored on Pulzar Cloud while a sign-in waits — it is minted when the gateway
collects it. Online only; offline, recovery is the way in. A QR that will not
scan: the code typed at app.pulzr.net/gateway-access works the same.
The gateway half is pulzr-console-signin and auth.uc; the cloud answers
the sign-in start and collect calls.
Parity, and how it is kept
Section titled “Parity, and how it is kept”Same pages, same order, same labels, notices and badge words — the React page
is the reference, and each file in tui/pages/ is that page restated in
blocks. Underneath they call the same code:
- Reads go to the console’s
lib/modules directly, the wayapi/index.uc’s GET routes do. - Changes go through
lib/actions.uc, which the API’s POST routes call too. Validation and audit records live there and nowhere else, so an action taken at a keyboard is checked and journalled exactly as one taken in a browser.
A firmware upgrade is the one control that differs: a terminal has no file
picker, so the image is a path on the gateway — the SD card, or /tmp after
copying it over SSH — and goes through the same fwtool board check,
sysupgrade -T, signature verification and journal as an upload. A file
somebody pointed at is left in place if it is refused.
Adding a page to the console means adding it here as well. tui/app.uc has
the sidebar in nav.ts’s order.
↑ ↓ (or j k, Tab) move, Enter selects, Esc goes back to the menu, r refreshes, q quits — or signs out, on a port. A field is edited in place: Enter saves, Esc cancels. PgUp and PgDn scroll a long page. Ctrl-L redraws, and asks a serial terminal its size again.
The shell
Section titled “The shell”Only for Pulzar: a TUI started from a root shell, or a session Pulzar Cloud
signed as staff’s (auth.md, “Who gets root”). Not for the local
password, an organization admin’s Pulzar or recovery sign-in, or a remote
session; a development image lets any signed-in session through. There, !
drops to a login shell on the same terminal; exit or Ctrl-D comes back
to the console, redrawn and refreshed. The TUI steps aside rather than running
beside the shell, so it is the ordinary shell — the banner, job control,
Ctrl-C — and works the same on a serial line, over SSH, on HDMI and on the USB
serial port.
On a port each one is journalled as console.shell. An idle shell on a port
logs itself out after fifteen minutes, where the shell supports TMOUT.
Terminals
Section titled “Terminals”It asks rather than assumes. A serial line has no window size, so the TUI parks the cursor in the far corner and asks where it ended up; it draws a box character and asks how far the cursor moved, to learn whether the far end is UTF-8. Without UTF-8 it draws in ASCII. Without colour it still works: a status is a word, and focus is reverse video.
A RAK’s console is 57600 baud — about 5.7KB a second, where one full 80x24 frame in colour is several KB. So only lines that changed are sent, and a page that is not live blocks on the keyboard instead of redrawing on a timer. Live pages stop refreshing after fifteen minutes without a key.
PULZR_ASCII=1 and PULZR_COLOR=0|16|256|24 override what it detects.
The mark
Section titled “The mark”The logo is drawn by pulzr-logo from /usr/share/pulzr/logo.txt: eight
rows of half-block cells, sixteen pixels high. The login banner draws it beside
the wordmark, as does the TUI’s sign-in screen, and Overview on a screen tall
enough to spare the rows.
scripts/render-logo.py makes the grid from console/public/icon.svg, the
Pulzar mark app.pulzr.net also uses. The shape is drawn by hand there — at
sixteen pixels a downsample smears the links and the orbit ring — and only the
colours come from the SVG. On the Pi’s framebuffer
console the kernel folds 256-colour codes to its own sixteen by thresholding,
which turns the whole mark cyan, so on that console the mark picks its own.
The ucode it runs on
Section titled “The ucode it runs on”OpenWrt 25.12 pins ucode 2026.01.16; this code was written against 24.10’s 2024-07-22. Three things about it shaped this code, and will bite anything else that reads a terminal. All three still hold on 2026.01.16:
- A timed-out read is sticky.
file.read(n)is a barefread(); under musl the EOF flag it sets is never cleared, so every later read on that handle returns nothing. Input is a handle on the tty that is closed and reopened at EOF — the one moment its stdio buffer is known to be empty. - A closure in a loop sees the last value.
for (let x in list)has one binding for the whole loop. Copy the variable into aconstinside the body, or usemap(). 7 / 2is3. Integer division stays integer; multiply by1.0first.
Raw mode and the window size go through stty, because 24.10’s ucode had no
fs.ioctl(); 25.12’s does. OpenWrt’s busybox has none, which is why the package depends on
coreutils-stty.
Running it on a Mac
Section titled “Running it on a Mac”UCODE=/tmp/ucode/build/ucode scripts/run-tui.shRuns the real pages against canned gateway state from
scripts/tui-fixture/api.uc. Add --console for the sign-in screens; the
fixture’s password wrong fails and initial forces a password change. --remote
is the session Pulzar Cloud opens.