Skip to content

Commit f29a927

Browse files
michael-borckmichael-borck
authored
Revise README for Kern project overview
Updated README to reflect the Kern project's vision, principles, and architecture.
1 parent 865e356 commit f29a927

1 file changed

Lines changed: 243 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 243 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,243 @@
1-
# -kern-linux.github.io
2-
Documentation and vision for the Kern project
1+
# Kern
2+
3+
**Fast, Focused, Foundational.**
4+
5+
---
6+
7+
## Vision Statement
8+
9+
To define a modern, minimalist computing environment that prioritizes speed, focus, and user control by leveraging the Linux console as a first-class citizen. Kern is a philosophy of computing that rejects the complexity and resource overhead of traditional graphical desktop environments. It combines the power of the Linux kernel, the directness of the framebuffer, and the flexibility of modern TUI (Text-based User Interface) applications to create a cohesive, powerful, and entirely keyboard-driven workspace.
10+
11+
---
12+
13+
## Core Principles
14+
15+
1. **Console First:** The primary interface is the Linux Virtual Console, not a graphical display server like X11 or Wayland. All core interactions happen in this environment.
16+
17+
2. **Text as the Universal Interface:** TUI and CLI applications are not afterthoughts; they are the primary application model. The environment is optimized for displaying and interacting with text.
18+
19+
3. **Minimalism by Default:** The system starts with a minimal base (e.g., Arch Linux or Debian Netinstall). Every component is chosen deliberately. There is no bloat.
20+
21+
4. **Keyboard Driven:** Workflows are optimized for keyboard-centric operation, minimizing reliance on the mouse to achieve maximum speed and efficiency.
22+
23+
5. **Composition over Integration:** Following the Unix philosophy, the environment is built from simple, independent tools that work together. The user composes their ideal workflow rather than accepting a monolithic, pre-integrated desktop.
24+
25+
---
26+
27+
## Why Kern? Why Not Alternatives?
28+
29+
### Why not just use a lightweight tiling window manager (i3, dwm, Sway)?
30+
31+
Tiling window managers are a layer of optimization on top of a graphical stack. **Kern eliminates the stack itself.**
32+
33+
- **No Display Server:** Kern communicates directly with the kernel's framebuffer. We bypass X11 and Wayland entirely, freeing up hundreds of megabytes of RAM
34+
- **No Dependencies:** This removes dependencies on graphics drivers, compositors, and display servers, resulting in a smaller footprint, faster boot times, and compatibility with older hardware
35+
36+
### Why not just run tmux/zellij in a regular terminal emulator?
37+
38+
- You absolutely can, and many users do—this is a valid stepping stone
39+
- But you're still dependent on a GUI desktop environment running underneath
40+
- Kern makes the console the *primary* interface, not an application running inside a desktop
41+
- You gain true persistence: your workspace survives across system reboots without needing a full desktop session
42+
43+
### Why not use an existing minimal distro like Alpine or Void?
44+
45+
- Kern isn't a distribution—it's a methodology and configuration layer
46+
- You *can* build Kern on Alpine, Void, Arch, or Debian
47+
- Think of it like "Oh My Zsh" but for your entire computing environment
48+
- The installation script handles the framebuffer setup, tool installation, and configuration regardless of base distro
49+
50+
### What about accessibility and graphics work?
51+
52+
- Kern isn't for everyone—it's optimized for text-heavy workflows (coding, writing, system administration, research)
53+
- For CAD, video editing, or graphical design work, a traditional desktop remains the better choice
54+
- However, many tasks work surprisingly well in this environment: documentation, presentations via Markdown, data visualization, and web development
55+
56+
---
57+
58+
## System Architecture
59+
60+
The Kern environment is composed of five distinct layers, building from the base hardware up to the application ecosystem.
61+
62+
### Layer 0: The Base System
63+
64+
- **Kernel:** Standard Linux Kernel
65+
- **Distribution:** A minimal installation of a flexible distribution
66+
- **Recommended:** Arch Linux (for access to the latest packages and AUR) or Debian Netinstall (for rock-solid stability)
67+
- **Also Compatible:** Alpine Linux, Void Linux
68+
- **Core Services:** Only essential system services are run. No graphical display manager, desktop services, or notification daemons are installed
69+
70+
### Layer 1: The Console Environment
71+
72+
- **Primary Interface:** A Framebuffer Terminal Emulator that runs directly on the Linux console, providing full Unicode font and color support
73+
- **MVP Component:** `fbterm` (for stability and ease of setup)
74+
- **Advanced Alternative:** `kmscon` (for more modern kernel integration)
75+
76+
### Layer 2: Session Management
77+
78+
- **"Window Manager":** A modern terminal multiplexer that provides persistent sessions, panes, tabs, and floating windows. This is the core of the user's workspace
79+
- **MVP Component:** `zellij` (for its powerful features, floating panes, and excellent out-of-the-box experience)
80+
- **Alternative:** `tmux` (for its ubiquity and extreme customizability)
81+
82+
### Layer 3: Application Ecosystem
83+
84+
- **Application Launcher:** A custom script combining a system-wide file index with `fzf` (fuzzy finder), bound to a key within `zellij` to provide a "Spotlight/Alfred-like" pop-up launcher
85+
86+
- **Core Applications:** A curated set of TUI/CLI tools to replace traditional GUI applications
87+
- **File Management:** `ranger` or `nnn`
88+
- **Text Editing:** `neovim` or `helix`
89+
- **Web Browsing:** `browsh` (for modern sites), `lynx` (for text-only)
90+
- **Productivity:** `taskwarrior` (tasks), `khal` (calendar), `neomutt` (email)
91+
- **System Monitoring:** `btop` or `bottom`
92+
- **Media Management:**
93+
- **Music:** `cmus` or `ncmpcpp` with `mpd`
94+
- **Podcast Client:** `castero` or `podboat`
95+
- **eBook Reader:** `epy` or `termpub`
96+
97+
### Layer 4: The Graphics & Multimedia Bridge
98+
99+
**Methodology:** Bypassing the terminal to render graphical content directly to the framebuffer via dedicated applications. The session is seamlessly restored upon exit.
100+
101+
**Integrated Document & Media Workflows:** Kern handles media through direct framebuffer applications and manages complex documents via a powerful command-line conversion pipeline. PDFs can be read as pure text (`pdftotext`) or viewed with full fidelity by converting pages to images (`pdftoppm` + `fbi`). Office documents and presentations are handled through `pandoc` and headless LibreOffice (`unoconv`), allowing you to stay in the console for over 90% of your workflow.
102+
103+
- **Image Viewing:** `fbi` or `fim`
104+
- **Video Playback:** `mpv` (using the `--vo=drm` output driver)
105+
- **Legacy/Emulation:** `dosbox` (using the `SDL_VIDEODRIVER=fbcon` environment variable)
106+
- **Presentations:** Markdown → HTML slides via `mdp` or export to PDF
107+
108+
---
109+
110+
## Implementation & Distribution
111+
112+
### Delivery Model
113+
114+
Kern is distributed as an installation script (similar to Omakub) that transforms a minimal Linux installation into a complete Kern environment.
115+
116+
### Installation Process
117+
118+
1. User installs a minimal base system (Arch, Debian netinstall, Alpine, etc.)
119+
2. Runs the Kern installer script: `curl -fsSL getkern.sh | bash`
120+
3. Script handles:
121+
- Framebuffer terminal installation and configuration (fbterm/kmscon)
122+
- Zellij installation and default layouts
123+
- Core TUI application installation (ranger, neovim, etc.)
124+
- fzf launcher setup with keybindings
125+
- Automatic session restoration configuration
126+
- Custom `/etc/issue` branding
127+
- Shell profile integration
128+
129+
### Configuration Philosophy
130+
131+
- **Sensible defaults** that work immediately
132+
- All configs stored in `~/.config/kern/` for easy customization
133+
- **Modular:** users can opt-out of specific components
134+
- Dotfiles managed via a simple CLI tool (`kern config`)
135+
136+
---
137+
138+
## User Experience (UX) Flow
139+
140+
1. **Boot:** The system boots in seconds to a customized, text-based TTY login screen
141+
2. **Login:** The user logs in, which automatically executes their shell profile
142+
3. **Session Start:** The profile script transparently launches `fbterm`, which in turn starts or attaches to the user's persistent `zellij` session
143+
4. **Workspace:** The user is instantly dropped into their fully configured, multi-pane workspace exactly as they left it
144+
5. **Interaction:** The user launches applications via the `fzf` pop-up, manages windows with `zellij` keybindings, and views media with framebuffer applications, all without leaving the console environment
145+
146+
---
147+
148+
## Remote Access & SSH
149+
150+
### How It Works
151+
152+
- **Local Usage:** Full framebuffer capabilities including image viewing (`fbi`) and video playback (`mpv`)
153+
- **Remote Usage (SSH):** All text-based TUI/CLI applications work seamlessly
154+
- Attach to persistent `zellij` sessions: `zellij attach`
155+
- See your exact workspace state remotely
156+
- Framebuffer applications won't work over SSH (limitation of remote access)
157+
- Audio playback requires additional PulseAudio configuration (optional advanced setup)
158+
159+
### Mirrored Environments
160+
161+
Because all core applications are text-based, you can create identical Kern environments on multiple machines and switch between them seamlessly via SSH.
162+
163+
---
164+
165+
## Resource Footprint
166+
167+
### System Requirements
168+
169+
- **RAM at Idle:** 50-100 MB (compared to 1-2 GB for traditional desktop environments)
170+
- **Boot Time:** Seconds (no display server initialization)
171+
- **CPU Usage:** Minimal (no compositor, window manager, or desktop services)
172+
173+
### Ideal Use Cases
174+
175+
- **Older Hardware:** Breathe new life into machines 10-15 years old
176+
- **Low-Power Systems:** Maximize battery life on laptops
177+
- **Servers:** Efficient local administration interface
178+
- **Resource Maximization:** Dedicate nearly 100% of system resources to actual work
179+
180+
---
181+
182+
## Future Development
183+
184+
### Roadmap
185+
186+
**Phase 1 (MVP):** Stable framebuffer environment with core TUI tools
187+
188+
**Phase 2:** Enhanced launcher with app categories and recent items
189+
190+
**Phase 3:** Sixel graphics integration for in-terminal image previews
191+
192+
**Phase 4:** Community application repository and configuration sharing
193+
194+
**Phase 5:** Remote session management tools (kern-ssh helper scripts)
195+
196+
### Community Goals
197+
198+
- If adoption grows, encourage TUI developers to optimize for framebuffer environments
199+
- Build a curated application directory (`kern-apps`)
200+
- Create pre-configured "profiles" for different workflows (developer, writer, sysadmin)
201+
- Develop GUI-to-TUI migration guides for common workflows
202+
203+
---
204+
205+
## Technical Notes
206+
207+
### Virtual Consoles (TTYs)
208+
209+
Linux provides multiple independent terminal sessions accessible via `Ctrl + Alt + F1` through `F6`. Each virtual console (`/dev/tty1`, `/dev/tty2`, etc.) can run separate login sessions, providing kernel-level multitasking without any window manager.
210+
211+
### Graphics Standards
212+
213+
- **Framebuffer (`/dev/fb0`):** Direct pixel access to display hardware
214+
- **Sixel:** Terminal graphics protocol for embedding images in text streams (future enhancement)
215+
- **DRM (Direct Rendering Manager):** Modern kernel interface used by `mpv` for video playback
216+
217+
### Login Screen Customization
218+
219+
The TTY login screen is controlled by `/etc/issue`. You can customize it with:
220+
- ASCII art (via `figlet`)
221+
- ANSI color codes
222+
- System information variables (`\n` for hostname, `\d` for date)
223+
- Centered layouts using blank lines
224+
225+
---
226+
227+
## Getting Started
228+
229+
1. Install a minimal Linux distribution (recommended: Arch Linux or Debian netinstall)
230+
2. Boot to console and log in
231+
3. Run: `curl -fsSL https://getkern.sh | bash`
232+
4. Follow the interactive setup prompts
233+
5. Log out and back in to start your Kern session
234+
235+
---
236+
237+
## Philosophy
238+
239+
Kern represents a return to computing fundamentals: direct hardware access, composable tools, and user control. It's not about rejecting graphical interfaces entirely, but about questioning whether they're necessary for every task. For text-heavy workflows—coding, writing, system administration, research—the console provides a faster, lighter, and more focused environment than any desktop.
240+
241+
By building on proven Unix principles and modern TUI applications, Kern creates a computing experience that is simultaneously retro and cutting-edge: the simplicity of 1980s terminals meets the power of 2020s tooling.
242+
243+
**Fast. Focused. Foundational.**

0 commit comments

Comments
 (0)