terminux 0.7.2

A cross-platform desktop terminal with workspaces and tabs

terminux

A fast, reliable, cross-platform terminal, organized the way you actually work.

Workspaces on the left. Tabbed terminals in the middle. Everything where you left it.

---

Why terminux?

You don't have one project. You have six. Each one is a different directory, a different mental context, a different set of running shells. terminux gives each of them a home (a workspace) and keeps them alive and arranged exactly how you left them, even across restarts.

It's the workspace UX of cmux on a clean, auditable two-process architecture inspired by terax. Rebuilt in Python for reliability over features. No accounts. No telemetry. No AI. Just a terminal that respects your flow.

uv sync && make frontend
uv run terminux

That's it. You're in.

✨ What you get

• Workspaces sidebar: a persistent list of named workspaces. Names track the first tab's working directory automatically (until you pin one).
• Tabbed terminals: every workspace has its own tabs, each a real PTY shell. Switch freely; background tabs keep streaming, no jank.
• Survives restarts: workspaces, tabs, window geometry, font size, each shell's working directory, and the visible scrollback of every tab all come back. Fresh shells, same layout, same view you left.
• Remote access: run the backend on a server, connect from your laptop with --connect. Shells and long-running builds survive lid-closes, network hops, and device switches. See Remote access.
• Keyboard-first: sidebar shows a keycap on each of the first nine workspaces; jump straight there with Ctrl+Shift+1..9 on Linux (Cmd+1..9 on macOS). Plus a fuzzy quick-switcher, find-in-terminal, font zoom, and more.
• Platform-respecting shortcuts: Linux uses Ctrl+Shift+<key> for app shortcuts (matching GNOME Terminal, Konsole, Alacritty, Ghostty, kitty), so raw Ctrl+P / Ctrl+B / Ctrl+F flow straight to your shell. macOS uses Cmd for the same job; raw Ctrl is left alone.
• Clickable URLs & iTerm2-style copy: modifier-click opens links; optional auto-copy on selection, persisted, off by default.
• Working vs ready: a two-color sidebar dot reads like a CI traffic light — amber while a foreground task is actively working (idle TUIs and parked prompts don't count), green once it finishes. Works out of the box; opt-in shell integration makes it more precise. Plain output by itself never falsely promotes to green.
• Drag & drop: reorder workspaces and tabs with live drop feedback. Drop a file to paste its shell-quoted path.
• Local-first & hardened: loopback-only by default, per-session auth token, CSP and security headers, atomic versioned persistence.

_{The fuzzy quick switcher (Ctrl+Shift+P on Linux, Cmd+P on macOS): jump to any workspace or tab.}

Run

uv sync
make frontend                # build the web UI (needs Node; first run only)
uv run terminux              # desktop window (pywebview)
uv run terminux --no-window  # server only; open the printed URL in a browser
uv run terminux --debug      # verbose logs + slow-op warnings
uv run terminux --trace      # extreme: log every save/load/cwd lookup

--no-window serves the same UI to any browser — handy for development and for running terminux where no display is available. --debug and --trace are diagnostics flags; see Debugging knobs.

Remote mode

Run terminux on a headless server and connect from your laptop:

# on the server
uv run terminux --server --port 8443
# prints: terminux server listening — connect with:
#           http://127.0.0.1:8443/?t=abc-def-ghi

# on the laptop (one shell)
ssh -L 8443:localhost:8443 server.example.com

# on the laptop (another shell)
uv run terminux --connect http://localhost:8443/?t=abc-def-ghi

Shells, workspaces, and scrollback live on the server: disconnect, sleep the laptop, reconnect later, everything's where you left it. See Remote access for the full recipe (multi-client, firewall guidance, systemd service).

Install / package

terminux ships as a self-contained desktop app; no Python or Node required to run the bundle.

make build-linux  # Linux bundle (built in Docker) → dist/linux/terminux/terminux
make docker-run   # run headless web mode on :8000
make build-macos  # macOS .app → dist/terminux.app

Full platform notes (signing, Gatekeeper, X11, architectures) live in the documentation.

Documentation

Docs are built with Zensical and live in docs/.

make docs-serve    # live preview at http://127.0.0.1:8000
make docs          # static site → site/

Start with docs/index.md. The original vision, functional spec, and technical spec are in notes/.

Develop

make frontend        # build TS/Vite UI → src/terminux/web/static
make frontend-dev    # live Vite dev server against a --no-window backend
make frontend-test   # vitest unit tests (pure TS logic)
make test            # pytest: unit, integration, e2e (Playwright)
make lint            # ruff + ty + pyrefly + mypy
make format

The e2e tier drives the served UI with a real browser (no pywebview); install it once with uv run playwright install chromium.

Status: 0.7 preview

Works today: workspaces sidebar (create / rename / reorder / close, working/ready dot), tabs with multiple live terminals, real PTY shells streaming in the background, layout and scrollback restored across restarts (always with fresh shells), remote mode (--server / --connect), self-diagnosing freeze watchdog, macOS & Linux bundles.

Not yet: split panes, Windows PTY, multi-user.

Architecture in one breath

A Vite/TypeScript xterm.js web UI runs in a sandboxed pywebview window and talks to a loopback Starlette/uvicorn backend that owns the PTYs and streams raw bytes over per-terminal WebSockets. The frontend build output is committed to src/terminux/web/static/, so the Python package runs with no Node toolchain.

_{Built for people who keep too many terminals open. abilian/terminux}