Web SSH console¶

What this is¶

Optional in-browser SSH terminal to a managed host. The private key stays on PiHerder; the browser only shows a terminal (xterm.js) over an authenticated WebSocket.

Default: off. Enable with PIHERDER_SSH_CONSOLE=true and restart web.

Train: v1.2 Stream W · security bar is intentionally high.

Not GNU screen / tmux by default. Each console is a direct SSH PTY. Soft resume parks on the herder, not on the host. You can still run screen/tmux yourself if installed. Optional product default mux is a later, low-priority idea (PLAN_v1.3.0 W-mux).

Why it exists¶

Operators on a tablet or locked-down PC need a shell without exporting the herder private key.

Who can use it¶

Connect as… (v1.3)¶

Each host has a fleet identity (jobs + default shell) and may add a privileged identity (break-glass console and Files).

Host: lab-core
  ├─ fleet        user=piherder         ← jobs + default console
  └─ privileged   user=piherder-admin   ← Connect as… only

• Picker is on the same bar as Passkey/TOTP (and + Shell after unlock).
• Pick Privileged · user, complete 2FA if the bar still shows it, then + Shell. Optional reason appears next to the picker until that shell opens (then it hides; it is stored on the audit row).
• After 2FA the Passkey/TOTP controls hide. They only return if the short privileged proof expired (~90s).
• The shell tab is labeled username · priv.
• Jobs, Docker, backups, and host-deps always stay on fleet. Privileged is never the default console identity. Files defaults to fleet and can Connect as… privileged (same 2FA grant cookie).
• Demo: simulated fleet shell only — privileged mint is refused.
• Leave privileged unset if you do not need break-glass. XSS on the herder origin is already shell-equivalent; a privileged key makes it root-equivalent. Keep PIHERDER_SSH_CONSOLE off when unused.

Add / rotate / test privileged under SSH access on the server page. That panel shows Fleet public key and Privileged public key as separate boxes — copy the privileged line into piherder-admin’s authorized_keys (or use Setup script). Download the setup script and run it on the host (PiHerder will not auto-provision a root-capable user). HAOS: skip.

Who may elevate: Settings → Console → Who may open a privileged console (admin default, or operator). Env lock: PIHERDER_SSH_CONSOLE_PRIVILEGED_ROLE.

Command audit (v1.3)¶

Optional. Default off. Settings → Console:

Require on every session records commands on all live shells even if Off is selected (treated as commands). A shell that cannot start recording is refused. Demo still never stores transcripts.

When recording, the console chrome shows command audit on. If audit is off and you pick privileged Connect as…, a warning notes that the break-glass session will not record commands (it still opens).

After the shell ends: Audit → the close event → timeline, or Open full at /audit/console/{id} and download .txt. operator+ only. Viewers see that a transcript existed, not the body. Search does not index the shell text.

Redaction strips common Password: prompts and some token/PEM patterns. It is heuristic and imperfect — never treat a transcript as secret-free. read -s, editors, sudo, and secrets pasted as arguments can still land in the log. Not video, not script(1), not dual-control. Interactive programs (vim, htop, tmux) will not look like a clean command list. Leave audit off unless you accept that residual.

Retention (default 14 days) drops the encrypted body and keeps counts. Full herder DR (Postgres + master key) holds bodies; JSON config-only backups skip them.

Env locks: PIHERDER_SSH_CONSOLE_AUDIT_MODE, PIHERDER_SSH_CONSOLE_AUDIT_REQUIRED, PIHERDER_SSH_CONSOLE_AUDIT_RETENTION_DAYS. Compose does not inject defaults.

Public demo (PIHERDER_DEMO_MODE)¶

The public demo enables Console for the shared viewer account as a simulated shell only: same xterm UI, no live SSH, no network, no real keys, no 2FA step-up. Banner text says demo / simulated. Your self-hosted install is unchanged (flag off by default; operator+ + 2FA when enabled).

How it opens¶

Chrome is a single compact row after unlock: + Shell, shell tabs, Aa, optional Lock. Status is hidden by default (gate ··· to show). Soft-key strip stays one row and scrolls sideways on mobile.

Typing exit, idle timeout, or session max ends that shell (no resume-retry spam). Explicit close (shell tab ×, shell ✕, or popup ✕) still ends the session (bye). Switching apps or backgrounding the tab does not end the PTY.

Multiple hosts (/console)¶

Known issues¶

KI-console-mobile-soft-tab (improved in 1.2 QA)¶

Status: Soft-key v13 — PTY completion is correct; v13 hides the leftover IME overlay (docker/doc on screen while Enter already uses docker/).
Surface: Soft Tab key on mobile browsers (Android Chrome / iOS Safari).
Works: Physical keyboard Tab; soft Tab on desktop; mobile soft Tab flushes the IME token, rewrites cd.do / cd .do, drops a matching PTY echo, and clears xterm’s composition overlay so the line matches what Enter will run.

Path completion still depends on the remote SSH user’s home (least-priv piherder may have no ~/docker).

Not a demo-shell bug: public demo uses a simulated PTY with toy paths; self-hosted live SSH uses real bash completion for that host’s login user.

End-to-end¶

1. Set env (below) and recreate web.
2. Enroll passkey (preferred) and/or TOTP on Account.
3. Host must already have SSH credentials (key preferred).
4. Open a console one of these ways:
5. Server detail → Console (popup), or
6. Servers → host ⋯ → Console, or
7. Select hosts → Console (multi-host workspace).
8. Step-up if asked → + Shell.
9. Optional: add more hosts (+ Host / bulk select); switch host tabs freely — other hosts keep their shells.
10. Maximize for more terminal; switch apps safely (soft resume).
11. Close with in-app confirm: shell tab ×, host tab ×, popup ✕, or workspace Exit.

Security model¶

Residual risk: XSS on the PiHerder origin can act as the logged-in user — and is shell-equivalent when this flag is on. Prefer HTTPS; leave the flag off when unused. Host SSH uses the pinned host key (same TOFU as Test connection).

Soft resume (app switch)¶

When the browser suspends the tab or drops the WebSocket:

1. Server keeps the SSH session (slot still counted).
2. Output while away is buffered (~256 KB).
3. On return, the client sends {"type":"resume","resume":"…"} and reattaches.
4. Resume is not attempted while a multi-host iframe is the inactive tab (avoids burning the resume token).
5. Still ends on idle / max session / explicit close / logout.

Optional hard cap on park window: Settings → Console → Park hold (default 0 = until idle/max only). Env PIHERDER_SSH_CONSOLE_HOLD_SEC locks the same knob when set.

2FA recommendations¶

Tune in Settings → Security (prefer / require passkey, every-new-shell 2FA, backup codes). Set the matching PIHERDER_SSH_CONSOLE_* env only to lock a value.

Multi-shell (same host)¶

Default max 4 shells per user (Settings → Console, or PIHERDER_SSH_CONSOLE_MAX_PER_USER if set), shared across all hosts.

Settings vs environment¶

Settings → Console (admin) owns idle timeout, max session, concurrency, ticket TTL, park hold, bind IP/device, revalidate interval, and scrollback. Settings → Security owns the grant window and which 2FA factors count.

Env wins when a variable is set and non-empty (air-gap lock). The field shows as read-only (“Locked by environment”). Blank env does not lock.

Master enable stays env-only: PIHERDER_SSH_CONSOLE (default off). Public demo does not expose these knobs as a writable multi-tenant shell farm (Settings writes 403).

Lowering concurrency does not kick open or parked shells — the next new shell is denied.

Also: keep CSP on in production (PIHERDER_CSP=true). Tailwind is compiled CSS — no Play CDN / no unsafe-eval.

# Enable console (example)
PIHERDER_SSH_CONSOLE=true
docker compose up -d web

Full catalog: Environment reference · sample: console-and-backup.env.example.

Related¶

• 2FA & force 2FA
• Roles
• Environment reference
• SECURITY.md
• Add a server (SSH key first)
• Reports — console sessions, privileged opens, duration (from Audit)