SSH: a terminal client App #2

New Issue

2026-10-05T09:32:07Z

twisla commented

2026-10-05 09:32:07 +00:00

Idea

An App that opens an SSH session to a host and gives you a terminal: a shell on a server, a router or a Raspberry Pi, typed on the Cardputer's keyboard.

Why

The device already has a keyboard, Wi-Fi and TLS, so a pocket terminal for quick admin work is a natural fit.

What's known

Library.
- The two realistic options are wolfSSH (with wolfSSL, which has ESP-IDF support) and LibSSH-ESP32 (a libssh port on mbedTLS).
- Our TLS already runs on mbedTLS (ADR 0006, custom_sdkconfig), which favours libssh.
- wolfSSH is smaller but would bring a second crypto library into flash.
- We need to measure both: flash size (firmware is 1.71 MB of 3.3 MB) and heap during key exchange and a live session.
Memory is the main risk.
- With IRC connected, about 68 KB is free, and a TLS connection took about 45 KB.
- An SSH session needs a key exchange (curve25519 and the host key check) plus channel windows and buffers. We should expect a cost in the same range as TLS and measure it on the device.
- The floors from Q86 (start, steady, transient) apply here as well.
Terminal emulation.
- We need a parser for the VT100/xterm escape codes: cursor movement, erasing, colours and the alternate screen.
- With the current font, the 240×135 screen gives about 40×16 characters. ls and tail work at that size; htop and vim will look cramped. A smaller font, or scrolling sideways, is a design question.
- The screen grid costs about 2 bytes per cell, and scrollback costs more.
Keys. Ctrl, Esc, Tab and the arrows have to map onto the Cardputer's keyboard (fn and the ctrl/alt/opt keys).
Host keys. Trust on first use, like the Gemini certificate pins: store a fingerprint per host in NVS, and if it changes, show both fingerprints and ask, as Gemini does.

Questions for the design round

Which library: libssh on mbedTLS, or wolfSSH? Measure both first.
Which authentication methods: password only, or also a key? If a key, should it be an Ed25519 key generated on the device (show the public key to copy to the server), or loaded from the SD card? Where does the private key live, and is it protected by a passphrase?
How much terminal emulation: enough for a shell and less, or also full-screen programs like vim and htop?
Which font and grid size, and should lines wrap or scroll sideways?
Should the session keep running when you leave the App, like IRC does, or close?
How does it share memory with IRC: refuse to connect below a floor, or offer to close IRC?
Should there be saved hosts (user@host:port), stored in NVS or as a file on the card?
Port forwarding, agent forwarding and SFTP are out of scope for a first version. Agreed?

## Idea An App that opens an SSH session to a host and gives you a terminal: a shell on a server, a router or a Raspberry Pi, typed on the Cardputer's keyboard. ## Why The device already has a keyboard, Wi-Fi and TLS, so a pocket terminal for quick admin work is a natural fit. ## What's known - **Library.** - The two realistic options are wolfSSH (with wolfSSL, which has ESP-IDF support) and LibSSH-ESP32 (a libssh port on mbedTLS). - Our TLS already runs on mbedTLS (ADR 0006, custom_sdkconfig), which favours libssh. - wolfSSH is smaller but would bring a second crypto library into flash. - We need to measure both: flash size (firmware is 1.71 MB of 3.3 MB) and heap during key exchange and a live session. - **Memory is the main risk.** - With IRC connected, about 68 KB is free, and a TLS connection took about 45 KB. - An SSH session needs a key exchange (curve25519 and the host key check) plus channel windows and buffers. We should expect a cost in the same range as TLS and measure it on the device. - The floors from Q86 (start, steady, transient) apply here as well. - **Terminal emulation.** - We need a parser for the VT100/xterm escape codes: cursor movement, erasing, colours and the alternate screen. - With the current font, the 240×135 screen gives about 40×16 characters. `ls` and `tail` work at that size; `htop` and `vim` will look cramped. A smaller font, or scrolling sideways, is a design question. - The screen grid costs about 2 bytes per cell, and scrollback costs more. - **Keys.** Ctrl, Esc, Tab and the arrows have to map onto the Cardputer's keyboard (fn and the ctrl/alt/opt keys). - **Host keys.** Trust on first use, like the Gemini certificate pins: store a fingerprint per host in NVS, and if it changes, show both fingerprints and ask, as Gemini does. ## Questions for the design round 1. Which library: libssh on mbedTLS, or wolfSSH? Measure both first. 2. Which authentication methods: password only, or also a key? If a key, should it be an Ed25519 key generated on the device (show the public key to copy to the server), or loaded from the SD card? Where does the private key live, and is it protected by a passphrase? 3. How much terminal emulation: enough for a shell and `less`, or also full-screen programs like `vim` and `htop`? 4. Which font and grid size, and should lines wrap or scroll sideways? 5. Should the session keep running when you leave the App, like IRC does, or close? 6. How does it share memory with IRC: refuse to connect below a floor, or offer to close IRC? 7. Should there be saved hosts (user@host:port), stored in NVS or as a file on the card? 8. Port forwarding, agent forwarding and SFTP are out of scope for a first version. Agreed? ## Related `src/services/gemini_service.cpp` (TOFU pins), `docs/adr` 0006 (TLS buffers), `docs/milestones/G1.md` (Q86 memory floors).

twisla added the

concern/memory concern/security area/ssh labels 2026-10-05 09:32:07 +00:00

twisla referenced this issue

2026-10-05 09:46:05 +00:00

VPN: a WireGuard tunnel #8