eDEX-UI User Guide

eDEX-UI is a fullscreen, cross-platform terminal emulator and system monitor that looks and feels like a science-fiction computer interface. It wraps a fully functional shell in a TRON-inspired heads-up display: live CPU, memory, network, and process panels surround your terminal, a touch-friendly on-screen keyboard sits below it, and a directory browser tracks wherever your shell navigates. It runs a real terminal — bash, zsh, PowerShell, or anything else you point it at — so everything you already do in a console works here, just wrapped in a cinematic UI.

This guide covers installing eDEX-UI, using every panel and feature, customizing it with themes and keyboard layouts, configuring its behavior, and troubleshooting the issues users hit most often.

Note

eDEX-UI was archived by its author on October 18, 2021 at version 2.2.8. It is no longer actively developed, but the released binaries remain fully usable. This guide documents version 2.2.8.

1. Quick Start

1. Download the build for your operating system from the Releases page:
   • Windows — eDEX-UI-Windows.exe
   • macOS — eDEX-UI-macOS.dmg
   • Linux — eDEX-UI-Linux-x86_64.AppImage (or the arm64 build)
2. Install or launch it (see Installation for per-platform details).
3. Watch the boot animation, then start typing. The center panel is a normal terminal — run any command you like:

neofetch

        eDEX-UI 2.2.8
        ----------------
        OS: your operating system
        Shell: bash / powershell
        Terminal: eDEX-UI

4. Navigate your filesystem in the terminal (for example cd ~/Documents) and watch the FILESYSTEM panel on the left follow you automatically.

Tip

Press Ctrl+Shift+S at any time to open the settings editor, where you can change your shell, theme, on-screen keyboard layout, and more. Press Ctrl+Shift+K to see every keyboard shortcut.

That is the whole idea: a working terminal, dressed up, surrounded by live system telemetry.

2. Installation

eDEX-UI ships as a self-contained desktop application for Windows, macOS, and Linux. You do not need Node.js, npm, or any developer tooling to run a release build — those are only needed if you build from source.

Important

Public release binaries are not code-signed. Windows SmartScreen and macOS Gatekeeper will warn you the first time you run eDEX-UI. This is expected for this project; you will need to explicitly allow it to run.

Windows

1. Download eDEX-UI-Windows.exe from the Releases page.
2. Run the installer. It is an NSIS installer, so you can choose the installation directory.
3. If SmartScreen appears, click More info → Run anyway.
4. Launch eDEX-UI from the Start menu.

macOS

1. Download eDEX-UI-macOS.dmg from the Releases page.
2. Open the .dmg and drag eDEX-UI into your Applications folder.
3. The first launch is blocked by Gatekeeper because the app is unsigned. Right-click the app and choose Open, then confirm.

Linux (AppImage)

1. Download eDEX-UI-Linux-x86_64.AppImage (or the arm64 build for ARM devices) from the Releases page.
2. Make it executable and run it:

chmod +x eDEX-UI-Linux-x86_64.AppImage
./eDEX-UI-Linux-x86_64.AppImage

Package managers

eDEX-UI is also distributed through several community repositories:

# Arch Linux (AUR)
yay -S edex-ui

# macOS (Homebrew)
brew install --cask edex-ui

See repology.org for the full list of packaging sources.

Supported platforms

Note

On Linux, the file browser tracks your shell's current directory correctly. The same tracking works on macOS. On Windows it is technically impossible, so the file browser runs in a "detached" mode — see The file browser says "Tracking Failed".

3. The Interface at a Glance

When eDEX-UI finishes booting, the screen is divided into a fixed layout. Nothing here is draggable or resizable except modal pop-up windows — the layout is deliberately a fixed "command console."

+-----------------+-------------------------------+-----------------+
|  PANEL SYSTEM   |          TERMINAL             |  PANEL NETWORK  |
| (left column)   |        (main shell)           | (right column)  |
|                 |                               |                 |
|  Clock          |   [ MAIN SHELL | tabs... ]    |  Network status |
|  System info    |                               |  World globe    |
|  Hardware       |   your live terminal here     |  Net traffic    |
|  CPU usage      |                               |                 |
|  Memory         +-------------------------------+                 |
|  Top processes  |        FILESYSTEM             |                 |
|                 +-------------------------------+                 |
|                 |     ON-SCREEN KEYBOARD        |                 |
+-----------------+-------------------------------+-----------------+

The rest of this guide walks through each of these in turn.

4. Using the Terminal

The center panel is a complete terminal emulator powered by xterm.js. It supports colors, mouse events, and full-screen TUI programs such as vim, htop, ranger, cmatrix, and anything else that uses curses.

Running commands

Just type. Your keystrokes go straight to the shell configured in your settings (bash on Linux/macOS, powershell.exe on Windows by default). Output streams back into the terminal in real time, accompanied by subtle sound effects unless you disable audio.

ls -la

total 24
drwxr-xr-x  5 user user 4096 Jan  1 12:00 .
drwxr-xr-x 20 user user 4096 Jan  1 12:00 ..
-rw-r--r--  1 user user  220 Jan  1 12:00 .bashrc

Scrolling

• Mouse wheel — scroll the terminal buffer up and down.
• Touch — swipe vertically on a touchscreen.

The scrollback buffer holds 1,500 lines.

Copy and paste

Select text with the mouse, then press Ctrl+Shift+C. Paste with Ctrl+Shift+V. These deliberately differ from the plain Ctrl+C / Ctrl+V so that Ctrl+C still sends an interrupt signal to running programs.

Working with tabs

eDEX-UI supports up to five terminal tabs, labelled MAIN SHELL and tabs 2–5. Each tab is an independent shell process.

Empty tabs show EMPTY. Clicking one spawns a fresh shell in the current working directory of the active tab, so a new tab starts wherever you already were.

Note

The tab header shows the name of the foreground process running in that tab (for example MAIN - vim), so you can see at a glance what each tab is doing. This live process name is detected on Linux and macOS.

Warning

Reloading the UI (Ctrl+Shift+F5) while several tabs are open has been reported to occasionally crash the interface (issue #630). If you rely on multiple tabs, reload sparingly.

5. The Filesystem Browser

Directly below the terminal is the FILESYSTEM panel. It shows the contents of your terminal's current working directory as a grid of icons and follows your shell automatically: when you cd somewhere in the terminal, the browser updates to match.

Navigating

Viewing files inside eDEX-UI

Clicking certain file types opens a built-in viewer in a draggable modal window instead of inserting a path:

Tip

The browser highlights eDEX-UI's own configuration files with special icons. If you navigate into eDEX's config directory, clicking a theme file applies that theme instantly, clicking a keyboard layout file switches your on-screen keyboard, and clicking settings.json or shortcuts.json opens the matching editor.

Hidden files and view modes

A bar at the bottom of the panel shows how full the current disk/mount is.

Fuzzy file search

Press Ctrl+Shift+F to open the fuzzy cwd file search. Start typing part of a filename in the current directory; matching results appear instantly. Use the arrow keys to move the selection, then press Enter (or click Select) to insert the chosen file's full path into the terminal.

Search file in cwd...  > report
  report-2021.pdf      <- selected
  reporting-notes.txt
  ...

6. The On-Screen Keyboard

Below the filesystem is a full on-screen keyboard, designed for touchscreen use but also usable with a mouse. As you type on your physical keyboard, the matching on-screen keys light up in sync.

• Tap or click keys to send them to the terminal.
• Hold a key to auto-repeat.
• Multi-touch is supported — you can hold modifiers (Shift, Ctrl, Alt) with one finger while tapping letters with another.
• Dead keys / accents — the keyboard supports composing accented characters (circumflex, umlaut/trema, acute, grave, caron, tilde, cedilla, and more), so layouts for many languages work correctly.

Password Mode

Press Ctrl+Shift+P to toggle Password Mode. While it is on, the keyboard suppresses its visual and audio feedback so that sensitive input (passwords, secrets) is not revealed to anyone watching your screen or a recording.

Caution

On macOS, an older bug caused keystrokes to still be revealed in Password Mode (issue #1160). If you handle sensitive credentials on macOS, verify the behavior on your version before relying on it.

Switching keyboard layouts

eDEX-UI ships with 19 keyboard layouts, including:

Change your layout in the settings editor (Ctrl+Shift+S → keyboard) or by clicking a layout file in the filesystem browser.

7. The System Monitor Panels

The two side columns are live system monitors. They update automatically on their own timers — there is nothing to configure to make them work, though some can be customized.

Left column — system

Tip

Click the Top Processes panel to open a full, sortable process list in a modal window. Click any column header (PID, Name, User, CPU, Memory, State, Started, Runtime) to sort by it; click again to reverse, and a third time to clear sorting.

Note

On Windows, the CPU panel shows the core count in place of temperature, because per-core temperature readings are not reliably available there.

Right column — network

The network panels need an internet connection to populate. When offline, they display OFFLINE and the globe dims.

Note

eDEX-UI determines your external IP by contacting myexternalip.com, and resolves it to a map location using a locally downloaded GeoLite2 database. If your network blocks these, the IP and globe location will not appear — this is a common cause of an empty globe (see Troubleshooting).

8. Customizing eDEX-UI

Themes

eDEX-UI includes 20 built-in themes. Switch themes in the settings editor (Ctrl+Shift+S → theme) or by clicking a theme file in the filesystem browser — the change applies after a quick UI reload.

Tip

Want to hide the on-screen keyboard or the filesystem panel? You can't disable them outright, but the tron-notype theme (and other -notype variants) hides them for a cleaner look.

Themes can also define custom fonts, terminal color schemes, color filters, and injected CSS. Advanced theme authoring is covered in the project wiki and in the Admin Guide.

Custom keyboard shortcuts

Press Ctrl+Shift+K to open the shortcuts viewer. It lists two kinds of shortcut:

• Emulator shortcuts — built-in actions like copy, paste, switch tab, open settings (see the full table in section 9).
• Custom command shortcuts — key combinations you define to run a terminal command. For example, the default (disabled) shortcut Ctrl+Shift+Alt+Space runs neofetch.

Click Open Shortcuts File to edit shortcuts.json directly and add your own command shortcuts. A custom shortcut can optionally append a line break, so it runs the command immediately rather than just typing it.

Settings

Press Ctrl+Shift+S to open the in-app settings editor — a table of every option with a description and an editable value. After changing values, use one of the buttons at the bottom:

The most useful settings:

Important

The experimentalFeatures setting enables Chrome's experimental web features and is labelled DANGEROUS in the app. Leave it off unless you have a specific reason and understand the risk of instability.

Note

Setting your shell to something that isn't installed, or a cwd that doesn't exist, will prevent eDEX from starting. See Troubleshooting.

9. Keyboard Shortcuts Reference

All shortcuts work from both the on-screen keyboard and a physical keyboard. They can be customized in shortcuts.json (open it via Ctrl+Shift+K → Open Shortcuts File).

Note

By default, eDEX runs fullscreen and intercepts keys like F11, Alt, Ctrl+A, and Ctrl+D so they reach your terminal or are blocked from exiting the app. To allow F11 to toggle windowed mode, enable the allowWindowed setting.

10. Troubleshooting

eDEX-UI surfaces errors in on-screen modal windows. The most common issues, drawn from community bug reports, are below.

Error: eDEX gets stuck on "Settings loaded!" and never opens

Cause: The shell configured in settings.json could not be resolved, or your configured cwd (starting directory) does not exist. eDEX waits on the shell path during startup (issue #1168).

Solution: Edit settings.json (see section 11 for its location) and confirm shell points to an installed program and cwd is a real directory. On Windows the default shell is powershell.exe; on Linux/macOS it is bash.

Prevention: Only change shell/cwd to values you know exist, and use the settings editor's external-editor button so you edit the right file.

Error: Configured cwd path does not exist.

Cause: The cwd value in settings.json points to a folder that has been moved or deleted.

Solution: Set cwd to a valid directory (for example your home folder), then restart eDEX.

Error: "Tracking Failed" (Windows only)

Cause: This is expected behavior on Windows, not a bug. On Linux and macOS, eDEX watches your shell's current directory to keep the file browser in sync. Windows does not expose this information, so the browser switches to a detached mode and shows FILESYSTEM - TRACKING FAILED, RUNNING DETACHED FROM TTY.

Solution: In detached mode you can still browse files and folders by clicking them, and click a file to insert its path into the terminal — it just no longer auto-follows your cd commands.

Error: The world globe is empty / IP and location don't show

Cause: eDEX looks up your external IP via myexternalip.com and resolves the location with a GeoIP database. Network restrictions, offline status, or the service being unreachable prevents this (issues #964, #1135).

Solution: Ensure you have an active internet connection and that outbound HTTPS to myexternalip.com is allowed. The globe also requires the GeoLite2 database to finish downloading on first run.

Error: Error: unable to verify the first certificate

Cause: A TLS certificate chain could not be validated, typically on networks behind a corporate proxy or with intercepting middleboxes (issue #1103).

Solution: eDEX does not currently support custom proxy configuration for its internal lookups (issue #1050). On restricted networks, the network/globe features may stay blank while the terminal itself continues to work normally.

Problem: eDEX uses a lot of CPU

Cause: The live graphs, globe animation, and system polling are continuous. On lower-powered machines this is noticeable (issue #1169).

Solution: Use a -notype or simpler theme, disable experimentalGlobeFeatures, and avoid leaving many tabs open. The globe and graphics are the heaviest components.

Problem: Panels overlap on ultrawide / unusual aspect ratios

Cause: eDEX's fixed layout assumes common aspect ratios; very wide (e.g. 21:9) or unusual displays can cause overlap (issues #832, #1162).

Solution: Try the extra_ratios styling, a different theme, or running on your primary 16:9 display via the monitor setting. Some aspect ratios remain unsupported.

Problem: A black screen appears when eDEX opens

Cause: A graphics/GPU rendering issue, sometimes related to hardware acceleration (issue #1148). On macOS, framebuffer errors were reported on some versions (issue #1047).

Solution: Update your graphics drivers. If the problem persists, try a different release version.

Problem: "Another instance of eDEX is already running"

Cause: eDEX enforces a single running instance. A second launch exits immediately.

Solution: Switch to the already-open eDEX window, or fully quit the existing instance before launching again.

Problem: A folder whose name ends in a file extension is treated as a file

Cause: A known classification quirk in the file browser (issue #1167).

Solution: Navigate into such folders using cd in the terminal instead of clicking them in the browser.

11. Where eDEX Keeps Its Files

eDEX-UI stores all of its configuration and customization in a per-user data directory:

Inside it you will find:

Tip

You can drop your own theme or keyboard-layout JSON files into themes/ and keyboards/, then select them from the settings editor. eDEX refreshes its copies of the built-in files each time it launches, so keep custom files under different names.

12. Frequently Asked Questions

Q: Is eDEX-UI a real terminal, or just a visual effect? It is a real, fully functional terminal emulator. It runs an actual shell process and supports interactive programs, colors, and mouse events. The sci-fi UI is wrapped around a genuine console.

Q: Can I use it as my everyday terminal? Yes — that is an explicit goal of the project. It runs vim, ranger, htop, tmux, and other tools normally. Be aware it is fullscreen and resource-heavy compared to a plain terminal.

Q: Can I disable the on-screen keyboard or the file browser? You cannot remove them, but you can hide them with the tron-notype theme (or other -notype variants).

Q: Why are downloads flagged as unsigned / untrusted? The author chose not to code-sign the public binaries. You will need to bypass SmartScreen (Windows) or Gatekeeper (macOS) on first launch.

Q: Does it run on a Raspberry Pi or other ARM devices? Prebuilt arm64 AppImages are provided. Other ARM platforms may require building from source.

Q: How do I change the shell to zsh / fish / a custom one? Open settings (Ctrl+Shift+S), set shell to the program name or full path, save, and restart eDEX.

Q: How do I run eDEX as a fullscreen kiosk display? Keep forceFullscreen on, set nocursor to true to hide the mouse pointer, and optionally launch with the --nointro and --nocursor flags. The nointro setting skips the boot animation on every launch.

Q: How do I exit fullscreen? By default you can't — F11 is intercepted. Set allowWindowed to true in settings to enable F11 toggling.

Q: Is the project still maintained? No. After a roughly three-year run, eDEX-UI was archived on October 18, 2021 at version 2.2.8. The released binaries still work, but no new versions are planned.

Q: How do I report a bug or request a feature? The repository is archived, so new issues are generally not accepted. Search the existing Issues — many problems already have explanations or workarounds documented there.

Q: Can I build my own version from source? Yes. See the Admin Guide for build-from-source instructions, the architecture overview, and theme/keyboard-layout authoring details.