# Lios
Lios is a gorgeous, fast, real Linux terminal by Knott Dynamics and Trevor Knott. It uses GTK4 and VTE for correct terminal behavior, then layers on the parts that make a terminal feel premium every day: live themes, glass backgrounds, session-only Bash prompt profiles, Sixel images, same-directory windows, and safe GPU controls.
If you want a terminal that looks custom without becoming fragile, Lios is built for that. It does not fake terminal behavior, does not edit your shell startup files for prompt experiments, and does not hide risky renderer choices behind defaults. It gives you a reliable VTE core with a strong visual system and fast live controls.
## Why Lios
- Real terminal behavior from VTE, not a toy parser.
- Premium visuals built in: curated themes, glass opacity, background images, accent tint, cursor profiles, and live preferences.
- Session-only Bash prompt profiles that can be tried from the UI without touching `.bashrc` or persisted config.
- Same-directory new windows for smooth shell workflows.
- Sixel rendering, when provided by the system VTE build, and terminal identity exports for modern CLI image workflows.
- Reliable Cairo rendering by default, with explicit opt-in GTK auto/OpenGL/Vulkan modes when you want GPU acceleration.
- Small, local, and boring where it matters: no telemetry, no background downloads, no secret storage.
## Features
- GTK4 window with a VTE terminal widget.
- Spawns `$SHELL`, with common Unix shell fallbacks.
- Optional `-- COMMAND ...` and `--command "..."` launch modes.
- Dark readable defaults: white-on-black palette, opaque dark backing layer, `Monospace 12`, block cursor, 1,000 lines of scrollback.
- Built-in themes plus strict named custom themes authored in TOML and available everywhere themes can be selected. The Bronco preset combines Ember colors, the Lightbar Bash prompt, and a cyan accent.
- Slider-based master/full-window opacity plus nested image, terminal shade, and accent opacity controls.
- Background image support with `~` path expansion, fixed color tint, or per-launch random accent tint.
- Packaged default background image for first launch on new machines.
- Explicit visible mouse pointer over the terminal instead of VTE's dark text cursor shape.
- GPU acceleration toggle: reliable `cairo` by default, with opt-in safe auto/OpenGL (`auto` or `gl`) or explicit Vulkan (`vulkan`) through `GSK_RENDERER` before GTK starts.
- Child shells get `TERM=xterm-256color`, `COLORTERM=truecolor`, and `TERM_PROGRAM=lios`; Sixel rendering is enabled when the system VTE build supports it.
- Bash prompt profiles are session-local: `shell-default` leaves shell prompts untouched, while `lightbar`, `timebar`, `fibonnaci`, `fano-plane`, `alice-bob`, and `akira` set Lios-only prompt variables in the current terminal shell without writing startup files.
- Desktop launcher install with `lios --install` or `lios ---install`.
- App icon installed from `assets/logo.png`.
- Optional window decoration/topbar removal.
- Slim topbar with a collapsible in-window preferences drawer for common live theme/background changes.
- Compact keyboard-first, literal case-sensitive scrollback search with wraparound and retained per-window queries.
- `Ctrl+Shift+N` and `New Window` open a borderless terminal in the active terminal directory.
- Right-click appearance submenus for background images, terminal glass, accent presets, random tint, and themes.
- Right-click diagnostics for active windows, RSS, scrollback, terminal identity, image protocol, theme, background, and config path.
- Terminal-driven config commands for theming from a shell or script.
- Clipboard/context actions for copy, copy as HTML, paste, select all, and `Find...`.
- Guarded terminal clipboard paste: ordinary single-line text pastes directly, while line breaks, disallowed control characters, and text over 4,096 UTF-8 bytes require native confirmation.
- `http`, `https`, and `file` text is highlighted by VTE's regex matcher. Link opening is disabled in the broad VTE 0.68 compatibility build because that runtime has no safe public pointer hit-test API.
- Fixed cursor color profiles for `XFCE Red`, `Violet`, `Cyan`, `Emerald`, `Amber`, and `Rose`, plus persistent cursor-to-accent matching.
- Keyboard shortcuts for `Ctrl+Shift+C`, `Ctrl+Shift+V`, `Ctrl+Shift+A`, `Ctrl+Shift+F`, `Ctrl+Shift+N`, `Ctrl+Shift+Q`, `Ctrl+Shift+,`, `Ctrl++`, `Ctrl+-`, and `Ctrl+0`. In search, `Enter` finds next, `Shift+Enter` finds previous, and `Esc` closes search before preferences; otherwise `Esc` reaches the terminal.
## Links
- [Source repository](https://github.com/Tknott95/KnottTerminal)
- [crates.io package](https://crates.io/crates/lios)
- [docs.rs package page](https://docs.rs/lios)
- [GTK4 project](https://www.gtk.org/)
- [VTE terminal widget](https://gitlab.gnome.org/GNOME/vte)
## System Dependencies
Lios requires Rust 1.85 or newer, GTK 4.6 or newer (including Jetson's GTK 4.6.9), and VTE for GTK4 0.68 or newer. Newer GTK and VTE releases remain supported. The Rust crates compile with the exact `gtk4` `v4_6` and `vte4` `v0_66` feature gates so generated bindings do not use newer symbols; `build.rs` separately enforces the actual VTE 0.68 floor required by guarded bracketed paste.
Debian/Ubuntu systems whose configured repositories provide GTK4 VTE development packages:
```sh
sudo apt update
sudo apt install pkg-config libgtk-4-dev libvte-2.91-gtk4-dev
```
Stock Ubuntu 22.04 repositories do not provide the GTK4 VTE development package even though they provide GTK4. On Jetson, use an NVIDIA/vendor repository that provides VTE GTK4 0.68+, or build VTE 0.68+ with its GTK4 frontend before installing Lios. Verify the exact build inputs first:
```sh
pkg-config --atleast-version=4.6 gtk4
pkg-config --atleast-version=0.68 vte-2.91-gtk4
pkg-config --modversion gtk4 vte-2.91-gtk4
```
Install a current Rust toolchain with [rustup](https://rustup.rs/) if the distribution `rustc` is older than 1.85. Core Lios is supported on Jetson Orin `aarch64`; LiosBridge is a separate, optional x86-64-only component and is not required to build or run Lios.
Arch names:
```sh
sudo pacman -S rust pkgconf gtk4 vte4
```
## Run
Install from crates.io:
```sh
cargo install lios
lios
```
Run from source:
```sh
cargo run
cargo run -- --working-directory "$HOME"
cargo run -- -- htop
cargo run -- --command "ls -la"
cargo run -- --theme solarized-dark
cargo run -- --gpu
cargo run -- --gpu-mode vulkan
cargo run -- --renderer gl
cargo run -- --opacity 0.88
cargo run -- --background-image ~/Pictures/wallpaper.jpg --background-opacity 0.50 --random-overlay
cargo run -- --hide-titlebar
cargo run -- config init
cargo run -- config set gpu on
cargo run -- config set gpu_mode gl
cargo run -- config set theme solarized-dark
cargo run -- config set renderer gl
cargo run -- config set background.image ~/Pictures/wallpaper.jpg
cargo run -- config set topbar false
```
## Clipboard Safety
Context-menu `Paste` and `Ctrl+Shift+V` use guarded terminal paste. `Shift+Insert` uses the same guard only while the terminal owns focus, so paste in search and preference text fields stays local to those fields. Middle-click primary-selection paste remains VTE behavior and is intentionally not intercepted.
Empty clipboard text is a no-op, and normal single-line text (including tabs) pastes immediately. Clipboard text requires confirmation when it contains LF, CR, or CRLF line breaks, disallowed C0/C1 controls, or more than 4,096 UTF-8 bytes. The confirmation shows only reason and count metadata, never the clipboard contents.
## Optional Plugins
Core Lios stays small. Optional helpers use separate `lios-*` packages.
The standalone `LiosSSH` plugin launches OpenSSH inside Lios without storing
hosts, passwords, keys, or SSH config. Its source and package files are not
bundled with core Lios:
```sh
cargo install --locked --path ../LiosSSH
lios-ssh user@example.com
lios-ssh -p 2222 user@example.com
lios-ssh --theme solarized-dark -- -J jump.example.com user@example.com
```
The helper wraps `lios -- ssh ...` using argv. OpenSSH still handles `~/.ssh/config`, SSH agent, known hosts, keys, jump hosts, and verification.
## Configuration
Lios reads `~/.config/lios/config.toml` by default when it exists. Use `--config path/to/config.toml` to load another file.
```toml
[window]
title = "Lios"
width = 960
height = 640
decorated = false # set true to show the topbar/window decorations
renderer = "cairo" # cairo disables GPU; auto/gl use OpenGL, vulkan explicitly tries Vulkan
opacity = 1.00 # master/full-window opacity
[terminal]
font = "Monospace 12"
scrollback_lines = 1000 # max 100000
[[custom_theme]]
name = "midnight-copper"
base = "default"
foreground = "#f4e7d3"
background = "#100c0a"
cursor_background = "#d97745"
cursor_foreground = "#100c0a"
palette = ["#100c0a", "#c65f46", "#7f9f5f", "#d4a656", "#6688aa", "#a8759b", "#5f9f9a", "#d8c8b8", "#5b504a", "#e07a5f", "#9fbd78", "#f2cc72", "#82a7c9", "#c394b7", "#7fc2ba", "#fff4e6"]
[theme]
name = "midnight-copper"
# Optional custom overrides:
# foreground = "#ffffff"
# background = "#000000"
# Optional XFCE Red cursor preset values:
# cursor_background = "#e6192e"
# cursor_foreground = "#a51d2d"
# cursor = "#e6192e" # legacy alias for cursor_background
# cursor_match_overlay = false # cursor follows an existing effective accent
# unified_accent = false # enables a visible accent and matches the cursor
# palette = ["#000000", "#aa0000", "#00aa00", "#aa5500", "#0000aa", "#aa00aa", "#00aaaa", "#aaaaaa", "#555555", "#ff5555", "#55ff55", "#ffff55", "#5555ff", "#ff55ff", "#55ffff", "#ffffff"]
[[theme_profile]]
name = "Copper Glass"
theme = "midnight-copper"
font = "Monospace 12"
window_opacity = 0.95
terminal_opacity = 0.50
overlay_color = "#d97745"
overlay_opacity = 0.12
random_overlay = false
[background]
image = "/home/example/Pictures/wallpaper.jpg"
image_opacity = 1.00
terminal_opacity = 0.50
# Use lower values for more glass/desktop transparency.
# overlay_color = "#7c3aed"
overlay_opacity = 0.00
random_overlay = true
```
CLI flags override the config file for one run. Use `--gpu` for safe GTK GL rendering, `--gpu-mode gl` to force OpenGL, `--gpu-mode vulkan` to explicitly try Vulkan, and `--no-gpu` to force the reliable Cairo renderer. The text config stores this as `window.renderer` so older configs remain valid.
### Custom Themes
Each `[[custom_theme]]` defines one reusable terminal color theme. Its `name` must be a unique lowercase slug such as `midnight-copper`; names cannot collide with a built-in name or alias, including legacy aliases such as `xfce`, `xterm`, and `dracula`. `base` defaults to `default` and must resolve directly to a built-in theme. Custom themes cannot inherit from other custom themes.
The optional `foreground`, `background`, `cursor_background`, `cursor_foreground`, and `palette` fields override the built-in base. Colors must be valid GTK color strings and `palette`, when present, must contain exactly 16 valid colors. An omitted cursor field inherits the base cursor; an empty cursor string explicitly clears it. Unknown fields, duplicate names, invalid slugs, unknown bases, invalid colors, and incorrectly sized palettes make configuration loading fail without replacing the existing config during a save.
Select a custom theme with `[theme].name`, `lios --theme midnight-copper`, or `lios config set theme midnight-copper`. Config-file custom themes are also listed once after the public built-ins in Preferences and the right-click `Theme` menu. Theme matching is case-insensitive, while the stored effective name is canonical. Selecting a named theme deliberately removes active `[theme]` foreground/background/palette/cursor overrides; saving unrelated preferences preserves those overrides, custom-theme tables and comments, and unrelated TOML sections.
Use `lios config themes` to inspect the active theme and every selectable built-in or configured name without launching GTK or installing assets. `lios config validate` preflights the complete default config without changing it, including strict known-section fields, custom themes, and appearance profiles; legacy `terminal.prompt_profile` remains accepted and preserved but ignored because prompts are runtime-only. `lios config theme-template quiet-night --base solarized-dark` prints a valid inheriting `[[custom_theme]]` block whose optional color fields can be uncommented before adding it to the config.
Appearance profiles and custom themes are different. A custom theme is an authored reusable color scheme; a `[[theme_profile]]` is a saved complete appearance containing a theme reference plus font, opacity, background, accent, cursor, and window choices. Profile names are unique case-insensitively so updates and authored comments always belong to one unambiguous table. Profiles may reference custom theme names and can be saved or applied from Preferences. Duplicate names and invalid profile theme references fail clearly during config loading.
Theme cursor colors can be configured as a pair with `theme.cursor_background` and `theme.cursor_foreground`; leaving both unset keeps the theme's inherited cursor. Existing `theme.cursor_match_overlay` configurations retain their cursor-only behavior, while `theme.unified_accent = true` enables the coordinated overlay and cursor mode for the current terminal and newly opened windows. The red XFCE-style pair shown above is available as a fixed `XFCE Red` profile, alongside `Violet`, `Cyan`, `Emerald`, `Amber`, and `Rose` cursor profiles. Existing configs that use `theme.cursor` still work as a cursor-background alias. Preferences include cursor and accent color pickers, fixed presets, an `Inherit` control that removes active cursor overrides, and compact saved appearance profiles backed by `[[theme_profile]]` tables. An explicitly empty cursor string in TOML remains available when a theme's own cursor should be disabled rather than inherited.
Unified Accent is the master visual-match toggle. It keeps the cursor on the effective overlay color and guarantees that an accent is visible: an existing fixed accent is preserved, otherwise random accent mode is enabled, and zero accent opacity is raised to the normal default. Selecting a fixed cursor profile, clearing cursor colors, clearing the accent, or reducing accent opacity to zero turns Unified Accent off.
Bash prompt profiles are runtime-only UI actions. `shell-default` restores the saved original prompt when available. `lightbar`, `timebar`, `fibonnaci`, `fano-plane`, `alice-bob`, and `akira` apply immediately through a short private source script with terminal cleanup, preserving previous prompt values in `LIOS_ORIGINAL_PS1`, `LIOS_ORIGINAL_PS2`, and `LIOS_ORIGINAL_PS3`. Lios does not edit config or shell startup files for prompt profiles, so the prompt resets with the session.
Use `window.opacity` or `--opacity` as the main full-window opacity. This affects the whole terminal UI and is the primary control for app transparency.
Background images are rendered against the theme background and composited below a transparent VTE terminal. `image_opacity` controls how strongly the image blends into the theme-colored base. `terminal_opacity` is the nested terminal shade layer over that image; lower values show more image while preserving readable text. Without an image, use the master opacity for reliable transparent-terminal behavior, then use `terminal_opacity` only as the inner shade. If an older config has an image with `terminal_opacity = 1.00`, Lios uses the image shade at runtime so the image is not hidden by a fully opaque terminal background.
On a new machine with no existing Lios config, the packaged default background is written to the user data directory and used automatically. Existing config files are respected.
The topbar is hidden by default. `Ctrl+Shift+F` opens the compact search bar, selects its retained query, and searches literal case-sensitive text across scrollback with wraparound. `Enter` finds next, `Shift+Enter` finds previous, and `Esc` closes search. `Ctrl+Shift+,` opens the compact in-window preferences drawer, and the right-click menu includes both `Find...` and `Open Preferences...`. Search and preferences close one another; hiding preferences preserves unsaved controls. `Ctrl+Shift+N` opens another borderless terminal window in the active terminal directory using the current live settings. `Ctrl+Shift+Q` closes the current window. A top quick bar holds `Unified Accent` and the glowing `Live Edit` toggle. The drawer can change GPU acceleration mode, built-in or custom theme, Bash prompt profile, cursor colors, font, topbar visibility, background image path, layered opacity, accent color, and random overlay. Accent and cursor colors have clickable swatches. The `Profiles` card accepts a name and saves with Enter or `Add / Update`, then shows small apply buttons for saved looks. Background `Browse` and `Clear` actions apply immediately. Other edits enable `Apply and Save` plus `Revert`, and `Esc` closes the drawer. Live Edit starts off whenever the drawer opens, applies and saves valid edits after the 120 ms debounce while lit, and turns itself off when the drawer closes. Bash prompt profile changes apply locally to the current shell only; renderer changes are saved and apply on the next launch. Changes are written back to `~/.config/lios/config.toml` when a config path is available.
Right-click inside the terminal for quick actions. `New Window` opens a borderless terminal in the active terminal directory. `Close Window` manages terminal windows. `Diagnostics` prints resource state into the terminal. `Reset to Dark Default` returns the current window to the plain dark default look. The `Opacity` submenu starts with master/full-window opacity controls, then nests terminal shade controls under `Terminal Shade`. The `Background` submenu changes/clears images, adjusts image brightness, or resets the whole background. `Cursor` applies fixed cursor profiles (`XFCE Red`, `Violet`, `Cyan`, `Emerald`, `Amber`, `Rose`), enables Unified Accent, or restores the inherited default. `Bash Prompt` switches between `Shell Default`, `Lightbar`, `Timebar`, `Fibonnaci`, `Fano Plane`, `Alice & Bob`, and `Akira` using session-local prompt export commands. `Accent` switches fixed accent presets (`Violet`, `Cyan`, `Emerald`, `Amber`, `Rose`), toggles random accent tint, and adjusts accent strength. The `Theme` submenu switches public built-ins and configured custom themes. These actions apply live and persist to the active config path when one is available.
## Desktop Launcher
Install or build the binary first, then run `lios --install` to add Lios to the desktop app menu without launching it from another terminal. `lios ---install` is also accepted.
```sh
cargo install --path .
lios --install
```
The command writes `dev.lios.Terminal.desktop` under `$XDG_DATA_HOME/applications` or `~/.local/share/applications` with `Terminal=false` and `Exec` pointing at the exact binary that ran the command. It also installs the app icon from `assets/logo.png` as `dev.lios.Terminal` under the user icon theme and requests a desktop/icon cache refresh when the standard desktop tools are available. Normal GUI startup also makes the packaged icon available to GTK so direct `cargo run` launches can resolve the same icon name. Running `cargo run -- --install` creates a launcher for `target/debug/lios`; use the installed `lios --install` command for a stable app-menu entry. Use `lios --uninstall` or `lios ---uninstall` to remove that launcher and icon.
## Resource Policy
- Terminal scrollback is bounded. `scrollback_lines` must be between `0` and `100000`; the default is `1000`.
- Runtime diagnostics show active windows, process RSS, scrollback limit, renderer, terminal identity, image protocol, theme, background image, opacity, overlay state, and config path.
- GTK callbacks that can outlive their parent window use weak window references to avoid reference cycles during repeated open/close cycles.
- Segmented preference controls store weak button references internally, avoiding self-cycles between buttons and their click closures.
- No Tokio tasks or channels are used; child processes are owned by VTE and tied to the terminal widget/window lifecycle.
- VTE Sixel rendering is enabled when the installed VTE build supports it. Diagnostics report the effective VTE Sixel setting, but Lios does not export a false image-protocol claim to child processes. Image tools still need to run outside tmux or inside tmux configured to pass image protocols through.
- Internal bridge launchers can set `LIOS_BRIDGE_CONTAINED=1` to keep terminal children in the bridge cgroup. This marker coordinates launch behavior; it is not a security token or trust boundary.
Rust `1.88.0` can ICE while compiling generated GTK binding crates with heavy debug or optimization settings. `Cargo.toml` keeps the workaround scoped to the affected GTK crates. If `cargo install` still crashes while compiling GTK dependencies with a rustc stack trace, retry with a larger compiler stack:
```sh
RUST_MIN_STACK=16777216 cargo install --path .
```
Terminal config commands:
```sh
lios config path
lios config sample
lios config init
lios config init --force
lios config show
lios config themes
lios config validate
lios config theme-template quiet-night --base solarized-dark
lios config set gpu on
lios config set gpu_mode vulkan
lios config set renderer gl
lios config set theme solarized-dark
lios config set opacity 0.88
lios config set background_opacity 0.80
lios config set overlay_color '#7c3aed'
lios config set overlay_opacity 0.18
lios config set random_overlay true
lios config set cursor_match_overlay true
lios config set unified_accent true
lios config set topbar false
lios --install
lios ---install
lios --uninstall
```
Useful keys include `gpu`, `gpu_mode`, `renderer`, `theme`, `font`, `cursor_match_overlay`, `unified_accent`, `opacity`, `background.image`, `background_opacity`, `background_image_opacity`, `overlay_color`, `overlay_opacity`, `random_overlay`, and `topbar`.
## Package
The Cargo package is named `lios` and includes crate metadata for packaging. `Cargo.toml` uses an explicit package include list, so workspace notes such as `.notes.MD` are not part of the published crate.
```sh
cargo publish --dry-run
cargo publish
```