veil

v2.0.0 Status: stable by viewerofall GitHub

Wayland Compositor for Terminals & TTYs. Run GUI apps (Chromium, Firefox, Nautilus) in your terminal or directly on bare TTY with Dwindle tiling, full input support, and clipboard integration. Renders via Kitty Graphics Protocol, Unicode halfblocks, or ASCII — whatever your terminal supports.

install from aur

yay -S veil-host-bin velogin-bin

What is Veil?
Features
Install
Usage
Abyss (Login Manager)
Architecture
Keybinds
Compatibility
Roadmap

What is Veil?

Veil is a Wayland compositor that can run:

Nested in your terminal: Any terminal with Kitty graphics, halfblock Unicode, or ASCII support
Standalone on bare TTY: Direct DRM/KMS framebuffer output, no parent compositor or terminal needed

It's built on Smithay (Rust Wayland compositor framework) and supports: Multi-window tiling (dwindle layout, 4-window max), full keyboard + mouse input, clipboard sync, and GPU/CPU encoding pipelines.

Perfect for: Embedded systems, headless servers, SSH sessions, Wayland development, and anyone who wants a compositor in their terminal.

Features

Dwindle Tiling

4-window max, dynamic 2×2 grid layout. Resize, swap, rotate splits with Super keybinds.

Kitty Graphics

Full pixel-perfect rendering via Kitty Graphics Protocol. Best quality on kitty/WezTerm.

Halfblock Unicode

▀ + 24-bit truecolor. 2× vertical resolution. Works in any modern terminal.

ASCII Rendering

Luma mapping or edge detection. Works in dumb/restricted terminals.

IPC Daemon

Run veil append app to add apps to a running instance. Socket-based coordination.

Lua Config

Keybind customization + render mode selection via ~/.config/veil/config.lua

Multi-Compositor Nesting

Run Niri AND Hyprland simultaneously as separate windows. Input routed intelligently.

DRM/KMS Output

Bare TTY rendering (v2.0): Direct framebuffer access, no terminal emulator needed.

Full Input Support

Keyboard (with repeat), mouse (click/drag/scroll), clipboard (bidirectional).

GPU Encoding

wgpu Vulkan compute shaders for halfblock/luma. Offloads encoding to GPU.

Install

AUR (Arch Linux)

yay -S veil-host-bin        # Compositor
yay -S velogin-bin          # Login manager (optional)

Curl Install (Recommended)

Veil Compositor:

curl -fsSL https://viewerofall.pages.dev/install/veil/install.sh | bash

Abyss (Velogin) Login Manager:

curl -fsSL https://raw.githubusercontent.com/viewerofall/veilTDC/main/veil-login/dist/install.sh | sudo bash

Manual Download

Download from GitHub Releases:

curl -fsSL https://github.com/viewerofall/veil/releases/download/v2.0.0/veil-host-x86_64.tar.gz | tar xz
sudo install -m755 veil-host /usr/local/bin/

Build from Source

Requires Rust 1.78+:

git clone https://github.com/viewerofall/veil.git
cd veil
cargo build --release -p veil-host
sudo install -m755 target/release/veil-host /usr/local/bin/

Usage

Basic: Run an app

veil-host run firefox
veil-host run nautilus
veil-host run helium-browser

Launches the compositor, opens your app in a fullscreen (or tiled if multiple) window.

Advanced: Append to running instance

# Terminal 1: Start daemon with first app
veil-host run firefox

# Terminal 2: Append another app to the same compositor
veil-host append nautilus

# Add a third
veil-host append kitty

# Override: kill daemon, start fresh
veil-host append chromium -O

Keybinds (V2.0)

Keys	Action
`Super+H / J / K / L`	Focus window (left/down/up/right)
`Super+= / -`	Resize focused window (grow/shrink)
`Super+S`	Swap focused with adjacent
`Super+R`	Rotate split direction
`Super+Q`	Exit Veil
`Ctrl+C`	Kill focused app

Note: All keybinds use Super key (Windows key) to avoid conflicts with in-app shortcuts.

Flags

Flag	Description
`-m, --mode <mode>`	Render mode: kitty, halfblock, ascii (auto-detects by default)
`--gpu`	Enable GPU compute encoding (default: on)
`--debug`	Write logs to /tmp/veil.log
`--stats`	Show FPS and resolution in status bar
`-O, --override`	Kill existing daemon, start fresh

Abyss — Login Manager

Abyss (package name: velogin) is a graphical TTY login manager. Runs on bare TTY with DRM/KMS, handles PAM authentication, session selection, avatar loading, and login cooldown.

Install Abyss

From AUR:

yay -S velogin-bin

Curl install (recommended):

curl -fsSL https://raw.githubusercontent.com/viewerofall/veilTDC/main/veil-login/dist/install.sh | sudo bash

Configure for Boot

sudo systemctl enable --now seatd.service
sudo systemctl disable getty@tty1.service
sudo systemctl enable abyss.service

On next boot, you'll see Abyss on tty1 instead of a text login prompt. Select your session and login. Veil will launch automatically if selected.

Architecture

App (Firefox, Nautilus, etc.)
  ↓ Wayland protocol
veil-host (Smithay compositor)
  ├─ Dwindle layout engine
  ├─ libinput input handling
  ├─ Compositor globals (xdg-shell, wl_seat, wl_shm, etc.)
  ├─ Software compositing (blit surfaces into RGBA)
  ├─ GPU encoding (wgpu compute shaders) or CPU fallback
  └─ Output backends:
     ├─ Terminal (Kitty/halfblock/ASCII escape codes)
     └─ DRM/KMS (direct framebuffer on bare TTY)
    ↓
Terminal / Framebuffer

Protocols Supported

Protocol	Status
wl_compositor / wl_subcompositor	✓ full
xdg_shell (toplevel + popup)	✓ full
wl_seat (keyboard, pointer, touch)	✓ full
wl_shm (shared memory buffers)	✓ full
wl_data_device (clipboard)	✓ full
wl_output + xdg_output	✓ full
zwp_linux_dmabuf_v1 (GPU buffers)	✓ optional (SHM fallback)
xwayland (X11 apps)	✓ full

Config: Keybinds & Rendering

Create ~/.config/veil/config.lua:

keybinds = {
  mod_key = "super",
  
  focus_left  = "h",      -- Super+H
  focus_right = "l",      -- Super+L
  focus_up    = "k",      -- Super+K
  focus_down  = "j",      -- Super+J
  
  resize_grow   = "equal",  -- Super+=
  resize_shrink = "minus",  -- Super+-
  
  swap_windows  = "s",    -- Super+S
  rotate_split  = "r",    -- Super+R
  
  quit = "q",             -- Super+Q
}

render_mode = "auto"  -- auto, kitty, halfblock, ascii
gpu_encode = true

Compatibility

Tested and working: Helium (Chromium), Firefox, Nautilus, Thunar, foot terminal, kitty terminal, Niri (nested), Hyprland (nested).

Requirements:

Nested mode: Any Wayland compositor (GNOME, KDE, Niri, Hyprland, Sway)
Bare TTY: GPU with DRM support, libseat (systemd-logind), Linux 5.4+

Terminals (nested mode): Kitty, WezTerm, xterm (with sixel). Generic xterm via sixel. Anything else via halfblock/ASCII.

Roadmap

V2.0 ✓ Shipped

done Dwindle tiling (4-window max, 2×2 grid)
done DRM/KMS framebuffer output (bare TTY)
done libinput + libseat (full input, VT switching)
done IPC daemon + socket (veil append)
done Lua config (keybinds, render mode)
done Multi-compositor nesting (Niri + Hyprland together)
done GPU compute encoding (wgpu Vulkan)
done Abyss login manager (graphical TTY auth)

V3.0 — Terminal Compositor (6-8 weeks, TBA)

planned Floating windows (moveable, resizable with mouse)
planned Shell integration (interactive $ prompt in bottom region)
planned Multi-PTY (Super+T spawns new shell window)
planned Font rendering (fontdue)
planned TUI apps in shell (vim, htop, lazygit)
planned Scrollback buffer + history
planned App launcher (Super+Space → fuzzy search)
planned Sidebar (clock, stats, user menu)

Post-V3.0: Void Ecosystem

planned Rebrand to VoidWM (V3.0 ship + Void Suite consolidation)
planned VoidManager (cluster orchestration web panel, V4.0)
planned VoidOS (Artix Linux fork, init freedom + Void philosophy)

by viewerofall — github · releases · issues