Skip to content

Add selectable Fish/Zellij shell and session backends - #1

Draft
Pyrobrick wants to merge 10 commits into
mainfrom
concept/fish-zellij-defaults
Draft

Add selectable Fish/Zellij shell and session backends#1
Pyrobrick wants to merge 10 commits into
mainfrom
concept/fish-zellij-defaults

Conversation

@Pyrobrick

@Pyrobrick Pyrobrick commented Jun 25, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add optional shell (fish, zsh, or bash) and session_backend (zellij or tmux) selectors.
  • Preserve the existing Zsh/Bash and tmux behavior when the new selectors are omitted, so Supervisor's merged defaults do not silently migrate existing installations.
  • Keep ttyd/xterm.js for tmux-backed web terminals, but use Zellij's built-in browser client for Zellij-backed sessions.
  • Install the official web-capable Zellij 0.44.3 musl binaries for amd64 and aarch64, with pinned SHA-256 checksums.
  • Keep Zellij on loopback and expose it only through an ingress adapter that supports WebSockets, removes the iframe-blocking response header, scopes the login cookie to this app's ingress path, and only accepts Supervisor traffic.
  • Preserve Zellij's required token authentication; generate and persist a root-only home-assistant token on first startup.
  • Keep the root account on Bash for OpenSSH command compatibility and dispatch only interactive logins through the selected shell/session wrapper.
  • Add backend and ingress-config regression tests plus updated user documentation.

Compatibility behavior

  • Existing configurations keep using the legacy zsh option and tmux/ttyd.
  • Direct SSH commands such as ssh host "ha core info" run through Bash without entering a multiplexer.
  • Non-root SSH users retain the configured root handoff for both interactive and command-mode sessions.
  • Fish and Zellij are opt-in until an explicit migration mechanism can distinguish fresh installs from upgraded Supervisor configuration.
  • Mosh bootstraps through command-mode SSH and therefore starts Bash instead of the selected interactive shell or shared-session backend.
  • The selected shell wrapper now forwards command arguments instead of unconditionally replacing them with -l.

Validation

Local checks completed:

  • ssh/tests/test-terminal-backends.sh
    • legacy and explicit selector precedence
    • Fish/Zsh/Bash path selection and argument forwarding
    • Zellij/tmux session dispatch
    • native Zellij versus ttyd web dispatch
    • ingress base URL, listener, Supervisor allow-list, iframe-header removal, and cookie scoping
    • direct-command quoting and exit-status propagation
    • non-interactive multiplexer bypass
    • Bash and POSIX shell syntax checks

The dedicated regression job runs alongside the reusable app CI. The reusable workflow builds both configured architectures (amd64 and aarch64).

Remaining integration checks

  • Confirm GitHub Actions and both architecture image builds pass.
  • Smoke-test first-use token login, reconnect, WebSocket resize/input, and the direct homeassistant route through Home Assistant ingress.
  • Verify Zellij browser ↔ SSH session sharing with all three shells.
  • Regression-test tmux/ttyd, interactive SSH, direct SSH commands, Mosh, SFTP, and restart/upgrade persistence.

This remains a draft until those integration checks pass.

…default

- Pin fish to 3.7.1-r0 (latest in Alpine 3.21)
- Pin zellij to 0.40.0-r0 (latest in Alpine 3.21)
- Remove hardcoded sed that changes /bin/sh to /usr/bin/fish globally
  This allows startup scripts to handle shell selection via config

The shell selection should be determined at runtime by the startup scripts
based on the 'shell' and legacy 'zsh' configuration options, not hardcoded
in the image.
Preserve legacy defaults unless the new selectors are explicitly set, keep the root account POSIX-compatible for remote commands, and dispatch only interactive sessions through shell/backend wrappers. Add regression coverage, shell/YAML validation, and updated documentation.
@Pyrobrick Pyrobrick changed the title Concept: add fish shell and zellij session backend defaults Add selectable Fish/Zellij shell and session backends Aug 6, 2026
Use Alpine 3.24 package versions, pin the checkout action, test remote command quoting and exit statuses, make the root Bash rewrite directly testable, and clarify root/Mosh command-mode behavior.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant