Home

superterm 4.2.1

Project site: www.superterm.org

One live terminal workspace. Every SSH-capable screen.

superterm is a persistent, shared, multi-client terminal workspace for GNU/Linux and macOS, written in Free Pascal. It puts up to 16 real PTY-backed terminals inside a Turbo Vision-style desktop, then keeps that desktop alive in a session daemon so you can detach, reconnect, move to another screen, or work in it together.

If a device has an SSH client, it already has a SuperTerm client. Release 4.2.1 can publish the workspace through a separate instance of the host's OpenSSH server. Nothing SuperTerm-specific is installed on the viewing device:

ssh -p 8022 user@server

OpenSSH supplies encrypted TCP, Unix-account authentication and the outer PTY; the authenticated viewer then attaches to the same private session engine as a local client. Detach, closing the terminal or a network loss removes the viewer, not the live panes. See SSH for setup, authentication and the exact security boundary.

The whole workspace can also be driven from another shell, script or automation tool with the bilingual CLI: type into panes, capture scrollback, open or close windows and organize the shared desktop while users remain attached.

Two clients attached to the same session; the Python output was injected from a third shell with superterm send. One capture per feature on the Screenshots page.

The screenshot shows one workspace divided into four terminal panes. Each pane has its own process, terminal state, size and scrollback; the session has one focus shared by every attached viewer.

What's New

The newest release is always at releases/latest, with x86_64 packages for Arch, Debian/Ubuntu, Fedora/RHEL and a portable tarball.

4.2.1

Standard SSH clients can open SuperTerm over encrypted TCP. A normal interactive client uses the normal command shown above. The dedicated listener has its own service, addresses, PID, host identity and configuration under /etc/superterm/sshd; it neither modifies nor restarts the ordinary host SSH service, so both can run together.

The entry is intentionally a forced interactive SuperTerm UI. Remote commands, SCP/SFTP, forwarding, X11, agent forwarding and sessions without a PTY remain the job of the ordinary SSH service. The generated default listens only on loopback; publishing it on a network requires an explicit address. The full procedure is on SSH.

The built-in help is now a navigable bilingual reference, including dedicated topics for a standard SSH client and for administering the separate OpenSSH service. Sessions and profiles can be created safely at runtime, reconnecting SSH users return to their last live session by default, and client/process backpressure and lifecycle handling have been hardened.

Fullscreen moved to the prefix chord (Ctrl-Q f by default), leaving physical F5 available to the focused terminal application. The legacy goody.art slot now contains original GPLv3 alien-hacker artwork while preserving the existing configuration identifier.

Desktop artwork

The desktop, and the ground everything is drawn on.

The pictures are drawn for the screen they live on: at 1024x768 with the classic 8x16 cell the desktop is 128x46 characters, and that is the size they are now. Two come from checked-in source artwork: the 7kas phoenix from the brand's own vector file, and SuperTerm's original GPLv3 alien hacker in the legacy goody.art compatibility slot.

Every generated scene uses the full-cell token and the space where there is nothing. The renderer sends a filled cell as a space with an exact RGB background, so the terminal paints the complete rectangle instead of relying on a font's idea of █ or ▓. That removes horizontal and vertical seams even when the font is stretched. The three hand-built tile patterns retain their deliberate half-block detail.

Pick one from Options > Desktop background, and the desktop follows:

The desktop's colour is a choice. Options > Desktop colour... opens a picker over the sixteen text-mode colours. Black stays the default, and the colour fills the desktop and the empty cells of a picture alike:

A picture keeps its colours in every palette, monochrome included: what shows between the windows is the picture you chose.

Menus and dialogs cast a real shadow. FreeVision casts one by keeping the character underneath and changing its attribute, which used to drop the cell to its CP437 fallback: the shadow of a menu over a picture came out as the picture's own block characters in dark grey. It is a shadow now, over a picture and over a pane's own truecolor output alike.

The ground is ours to paint. A cell whose background is the palette's black used to go out as "colour 0", which a themed terminal paints as whatever it calls black, and a pane cell whose background was the terminal default went out with no background at all -- a hole straight through superterm on a terminal with a transparent background. Every background is explicit now; only black is forced, so a themed terminal keeps its own blue and cyan, and the text colour is never touched. Options > Solid background turns it off for anyone who wants that transparency.

Also repaired: menu labels longer than the 31 characters a FreeVision menu item holds were cut in silence, and the generated pictures were losing their first column to a missing space after the row marker.

3.4

Opening a window never touches the ones already open. It appears centred, at the size its class asks for -- classes gain cols and rows -- on top of whatever is there. F2/F3 included. Tiling is on demand: Windows -> Tile, or prefix + t.

The history is reachable. Every window carries a scrollbar in its right frame column, costing the pane no column; the mouse wheel scrolls three lines a notch, and on the alternate screen it sends arrow keys instead, which is what makes it work in less, man and vim. Alt-PgUp/PgDn/Home/End, with Ctrl- and Shift- aliases, and plain PgUp/PgDn where nothing else wants them. The view stays where you are reading while output keeps arriving.

The arrow keys work in top and htop. Every curses program puts the terminal in application cursor keys mode and expects ESC O A; superterm was sending the other form, so the arrows did nothing.

superterm inside a superterm pane. Nesting is refused by identity rather than by presence: only the sessions this pane already lives inside are rejected, at any depth. A new session, or a different one, is as safe from a pane as from any terminal. The mouse reaches the application inside a pane -- clicks, drags and the wheel, at pane coordinates -- while the frame, title bar, menu and status line stay superterm's, so a nested superterm's own window manager works. Ctrl-Q Ctrl-Q f toggles fullscreen in the inner one; physical F5 remains normal pane input.

Also repaired: superterm could hang at startup before its first line ran, on a terminal the runtime does not recognise; the console had no mouse at all; a client could lose visible content when another client resized a pane; and Restore all left the restored windows behind.

See the release notes for the full list.

Desktop backgrounds

A picture on the desktop, behind the windows. The desktop can show ASCII art instead of the plain pattern, in real RGB colour rather than the 16-colour grid.

Pictures are plain text files read at run time, not compiled in: drop one into ~/.superterm/backgrounds/ and it shows up in the Options menu without rebuilding. A file is a palette plus a row of glyphs and a row of colour indexes per line of the picture. Generated scenes use filled RGB cells and spaces; custom files and the three bundled patterns may also use the documented half-block and shade tokens.

Nine ship with it. Six are pictures:

and three are seamless patterns made for the tiled layout, which repeat across the desktop with no visible join:

The layout can be centred, tiled, stretched or fitted, and a picture may name the layout it was designed for. With background=none the whole thing short-circuits and costs exactly what it did before the feature existed.

Upgrading an existing checkout: run ./configure again before make install, or just make -- the Makefile regenerates itself when its template changes.

What's New in 3.2

Every pane now renders in full fidelity, not just the maximized one. 3.1 gave a maximized pane the whole terminal so a rich TUI could render untouched; 3.2 does the same for panes that are tiled or windowed. Truecolor, 256-colour palette indexes, real UTF-8 glyphs, emoji at their true two-column width, faint and concealed text all reach the terminal from a normal window. A pane is no longer flattened to one CP437 byte and 16 colours per cell. The vendored FreeVision is not modified: its grid is still drawn and decides what is visible.

Alongside it: attributes no longer leak out of a full-screen application, reset clears the screen again, the alternate screen stays out of the scrollback, and window drags stopped resending the whole screen -- 13926 to 1810 bytes per drag step, with frames coalesced when input is already waiting.

Two new per-profile display options in the Options menu:

• Show contents while dragging (default on). With it off you get a wireframe drag: only the window outline moves and everything behind it stays visible, so each step sends just the strip the outline vacates plus the one it takes.
• Zoom transition (default off). A short expanding and contracting outline when Ctrl-Q f enters or leaves fullscreen.

Below, four windows share the desktop -- a log tailer, a watch on disk usage, top in the centre, and a fourth minimized to a title bar at the bottom. Ctrl-Q f gives the focused pane the whole terminal, so top reflows into the full screen; the same chord brings the desktop back with every window where it was. The expanding outline is the optional transition.

See the 4.2.1 changelog for every change. The current session protocol is exact and versioned; a client and incompatible live daemon refuse each other explicitly. Close live sessions before replacing the binary because detach deliberately keeps them running.

What It Provides

• Vertical and horizontal pane splits with focus navigation and mouse support.
• Resize, maximize, minimize, restore, and close operations; up to 16 panes in one visible layout.
• Window classes ([class.*]): reusable named pane definitions for local commands and structured SSH connections (host, user, port, key, optional sshpass password), or a free connect command, with optional cmd, postconnect, shell, cwd, scrollback, and a default window title.
• Profiles ([profile.*]): named workspaces of windows and pane layouts whose panes reference window classes.
• Always-server sessions (3.0): every launch starts a session server and the visible terminal attaches as its first client, so the control CLI works from the very first second. [session] server=detach restores the classic detach-only flow.
• A bilingual control CLI (3.0): list/listar, send/enviar, capture/capturar, kill/matar plus full window management (new/nueva, close/cerrar, focus/foco, rename/renombrar, resize/tamano, minimize/minimizar, restore/restaurar, zoom/ampliar, organize/organizar). See CLI.
• True multi-user sessions: up to 8 clients share one daemon-owned canonical desktop, including pane geometry and focus. A differently sized terminal clips or pads that desktop until an explicit resize changes the shared geometry; bounded flow control prevents a stalled client blocking the rest.
• Encrypted TCP access (4.2.1) through a dedicated instance of the system's OpenSSH server. A standard interactive ssh client reaches the same live session engine without installing SuperTerm on the viewing device. See SSH.
• Named detachable sessions live under ~/.superterm/sessions/ from launch. Detach leaves the existing daemon and PTYs running; reattach with superterm --attach, the Ctrl-Q s picker, or the startup picker. superterm --list-sessions prints them.
• A configurable tmux-style prefix key ([keymap] prefix, default Ctrl-Q) so a remote tmux keeps Ctrl-B untouched; prefix + f enters or leaves fullscreen while physical F5 remains available to the pane.
• A custom keyboard driver: a lone Esc reaches the pane (timeout-based, not held as an Alt prefix), with CSI/SS3 decoding and X10/SGR mouse support.
• Editable, persistent window titles, saved in sessions and profiles.
• A color palette selector (color, black-and-white, monochrome) for the window manager itself, and, since 3.2, full-fidelity pane rendering: 256-color and truecolor sequences, UTF-8 glyphs and emoji are passed through to the terminal exactly as the application sent them, in any pane.
• English and Spanish application interfaces, switchable at runtime.
• A quick session wizard for one to four ad-hoc panes.

Start Here

• Installation: prebuilt packages, dependencies, configure, build, and tests.
• Usage: learn the controls, wizard, profiles, and session lifecycle.
• SSH: connect from a standard SSH client and configure the isolated OpenSSH entry safely.
• Screenshots: view the English workspace, menu, and wizard captures.
• Configuration: define window classes, profiles, and detachable sessions.
• Architecture: understand the PTY, screen, layout, and FreeVision layers.
• Development: work on the source tree and run the regression suite.
• Troubleshooting: diagnose build, configuration, SSH, and terminal issues.

Current Scope

The supported native platforms are GNU/Linux and macOS (Apple Silicon and Intel), both POSIX systems built from the same source tree. The program uses POSIX PTYs, fork/exec, poll, and the bundled FreeVision text UI. The PTY/process layer (src/st_pty.pas, selected with {$IFDEF DARWIN}) uses /proc on GNU/Linux and libproc/sysctl on macOS. The optional dedicated SSH service uses systemd on GNU/Linux and launchd on macOS. Windows would require a ConPTY backend plus Windows-specific process, resize and service code; WSL is the practical way to run the GNU/Linux build on Windows.

Detached sessions are owned by a per-user session server, so leaving the FreeVision client does not close local shells or remote SSH connections.

Security Notes

• Prefer SSH keys or an SSH agent over passwords.
• The application creates ~/.superterm mode 700 and writes its files mode 600, because they may contain credentials.
• Do not put passwords in command lines or debug logs.
• Treat postconnect and local command fields as shell commands under the configured login shell.