Hooks and Terminal

Hooks and Terminal

Hooks

Hooks brings services into Helix without pretending Helix owns their data or complete API. The built-in catalog currently knows about:

• Plex Media Server;
• AMP;
• Tailscale;
• Pterodactyl Wings;
• Jellyfin;
• Docker, including every container on the host; and
• Portainer, when Helix finds that container and a UI port (9443, then 9000).

The protected broker configuration decides which exact systemd units are controllable. Installed services report running, start-after-boot state, and cgroup memory plus one short CPU sample when systemd exposes them. The Docker card lists containers from docker ps. Live CPU and memory for those containers still come from engine stats when you open the Docker panel. Supported buttons issue only start, stop, restart, enable, or disable for that exact unit and verify the result. AMP uses its separate loopback API adapter. Docker start/stop/restart uses the typed container-action route and refuses Helix dashboard/gateway names.

When a service is absent, Helix runs a read-only host preflight first. On a Debian-family APT host (Debian, Ubuntu, Mint Ubuntu edition, Pop!_OS, LMDE, and similar), Tailscale and Jellyfin have one-click installers. Fedora, openSUSE, and Arch get an honest blocked/guided result instead of a fake APT path. Each installer accepts only one built-in hook ID, downloads repository material from the publisher's exact HTTPS host, validates the repository definition, adds the exact signed APT source, installs the exact allowlisted package, enables the exact systemd service, and verifies that it is active. Hook installs and System Updates share one package-operation lock. The preflight lists the exact files Helix will write. Missing installer directories are created as root with a tight mode; group-writable ones are tightened to 0755 or 0700 before a repository file lands there. A symlink or a directory not owned by root still blocks, and the error names the path.

Helix never runs a downloaded root script and the browser cannot supply a package, repository, unit, executable, or shell command. If repository setup or APT fails before package installation, prior repository files are restored. There is no general package rollback claim after APT has changed the host.

Tailscale account login is deliberately separate. After the package and tailscaled.service are ready, the owner runs tailscale up in Terminal and approves the one-time link in the intended tailnet. Helix neither stores those credentials nor chooses tailnet policy. Jellyfin likewise leaves its first-run owner and media-library wizard inside Jellyfin Web.

Pterodactyl Wings is guided instead of falsely labeled one-click. Helix checks the supported Linux release, architecture, Docker, systemd, and command prerequisites, then identifies the remaining owner steps. The node must first exist in a Pterodactyl Panel because that panel generates the node-specific config.yml and credentials.

Open-service buttons use the local Helix hostname with the known panel port. Deep library, account, network, or application-specific settings remain in the upstream interface unless a future typed adapter can validate them safely.

Host terminal

Terminal is optional and has a stronger warning because it is a real Linux PTY. It runs as one configured non-root Linux user, not as helix-privd. Normal host policy still applies; sudo may ask for that Linux user's password and may grant root only if the account is already authorized.

Each new connection requires the current Helix dashboard password. The proof creates a random 30-second, single-use, session-bound HttpOnly ticket. The browser then opens one exact WebSocket protocol. The host service uses a group separate from the privileged broker and Linux peer credentials restrict socket clients to the pinned dashboard UID.

The PTY is an interactive login bash, so profile, ~, and Tab completion work like a normal SSH session. Helix forwards Tab into the shell instead of moving browser focus. Copy/paste use Ctrl/Cmd+Shift+C and Ctrl/Cmd+Shift+V (plain Ctrl+C still interrupts). The Copy button reads Copied after a successful copy. Ctrl+F searches the local scrollback. Ctrl+/− and Ctrl+wheel change font size. http(s) links in output open in a new tab. Mouse reporting is forwarded so programs like htop can use it. Helix does not add scp, extra SSH hops, or a second file completer of its own.

Helix audits password rejection and session opened/closed/failed lifecycle. It does not store commands, keystrokes, output, or environment values. The browser keeps 10,000 lines of local scrollback only for that page. Disconnecting or closing the page kills the PTY; use tmux or a system service for work that must survive a browser disconnect.

The quick-check buttons send ordinary read-only commands into the same PTY. Output remains terminal-native so ANSI colors, wrapping, prompts, columns, and interactive programs behave like an SSH terminal rather than a reformatted log viewer.

If the page says unavailable, verify the optional helix-terminald@USER service, its separate socket group, /run/helix/terminal/terminal.sock, the dashboard's pinned UID/GID mapping, and the exact gateway WebSocket route. Do not solve it by adding the terminal user to the privileged broker group.