getting started · 01

Introduction.

Odyssey Linux is a Void Linux derivative built around three additions: a tuned kernel, a graphical installer, and a set of graphical tools for managing the system. Everything else is upstream Void — same packages, same repositories, same keys.

This documentation assumes you are comfortable with Linux. Odyssey is not a beginner distribution. It is aimed at intermediate and advanced users who want the Unix philosophy without giving up graphical tooling.

what odyssey adds to void

  • linux-odyssey — kernel with BORE scheduling, compiled for x86-64-v3
  • Calamares installer — patched for runit, with DE chooser
  • Graphical tools — xbps-gui, runit-gui, Odyssey Control Center

what odyssey does not change

  • All packages come from official Void Linux repositories
  • runit is the init system — no systemd, no compatibility layer
  • xbps is the package manager — unmodified
  • You can switch back to stock Void by removing three packages

getting started · 02

Installation.

Download the ISO, write it to a USB drive, boot it. The live environment runs KDE Plasma by default. Launch Calamares from the desktop to begin installation.

writing the iso

# Linux
$ dd if=odyssey-1.0-x86_64.iso of=/dev/sdX bs=4M status=progress
 
# or use any graphical tool: Ventoy, Etcher, etc.

installer steps

  • Select language and locale
  • Select keyboard layout
  • Partition the disk — automatic or manual, LUKS encryption optional
  • Choose your desktop environment — KDE, XFCE, Cinnamon, niri+Noctalia
  • Create your user
  • Review and install

requirements

  • x86-64-v3 compatible CPU (most CPUs from 2015 onward)
  • 4GB RAM minimum — 8GB recommended
  • 20GB disk space minimum
  • UEFI or BIOS boot

getting started · 03

First boot.

After installation the system boots directly into your chosen desktop environment. The Odyssey repository is pre-configured. linux-odyssey is already running.

first things to do

# update the system
$ sudo xbps-install -Su
 
# verify the kernel
$ uname -r
6.12.82-odyssey
 
# verify BORE is active
$ cat /sys/kernel/sched/bore
1

The Odyssey Control Center is available in the application menu. Use it to configure repositories, tune the kernel, manage services, and set up privacy tools.

the system · 01

Kernel linux-odyssey.

linux-odyssey is the CachyOS BORE patchset applied to the Linux LTS kernel, compiled for x86-64-v3 and packaged for Void Linux via xbps. It registers as a virtual provider of the linux package so xbps dependency resolution works transparently.

installed patches

  • BORE scheduler — burst-oriented response enhancer, replaces CFS
  • BBR3 — TCP congestion control
  • PREEMPT — HZ_1000 tick rate
  • zstd module compression
  • Transparent Huge Pages, zswap, Kyber I/O scheduler

keeping the kernel safe from void updates

The file /etc/xbps.d/10-odyssey-kernel.conf contains:

ignorepkg=linux,linux-headers
virtualpkg=linux:linux-odyssey

This prevents xbps-install -Su from replacing linux-odyssey with the stock Void kernel.

updating the kernel

$ sudo xbps-install -Su linux-odyssey linux-odyssey-headers

the system · 02

Package management xbps.

xbps is the Void Linux package manager. Odyssey does not modify it. All commands work exactly as documented in the Void Linux handbook. A graphical frontend (xbps-gui) is available for users who prefer it.

common commands

# install a package
$ sudo xbps-install -S firefox
 
# update the system
$ sudo xbps-install -Su
 
# remove a package
$ sudo xbps-remove firefox
 
# search for a package
$ xbps-query -Rs firefox

odyssey repository

The Odyssey supplementary repository is configured at /etc/xbps.d/10-odyssey-repo.conf. It contains only three packages: linux-odyssey, linux-odyssey-headers, and odyssey-tools.

the system · 03

Service management runit.

runit is the init system and service supervisor. PID 1 is a ~40KB binary with no side effects. Services live in /etc/sv/ and are enabled by symlinking to /var/service/.

common commands

# enable a service
$ sudo ln -s /etc/sv/sshd /var/service/
 
# start / stop / restart
$ sudo sv start sshd
$ sudo sv stop sshd
$ sudo sv restart sshd
 
# check status
$ sudo sv status sshd
 
# list enabled services
$ ls /var/service/

The runit-gui module in the Control Center handles all of the above graphically.

control center · 01

Control Center overview.

The Odyssey Control Center is a launcher for nine independent modules. Each module is a separate Python/Qt6 program that launches on demand. There is no shared state and no persistent background process.

  • Kernel tuning — sysctl profiles, graphical editor
  • Memory & swap — zswap, swappiness, cache pressure
  • Privacy & firewall — Tor, Nginx proxy, AppArmor, firewall rules
  • Boot manager — GRUB entries, kernel parameters
  • Repositories — xbps repo management
  • runit services — enable, disable, start, stop
  • xbps packages — search, install, remove, upgrade
  • System info — kernel version, repo status, hardware
# launch from terminal
$ ether-control-center

control center · 02

Kernel tuning. coming soon

The kernel tuning panel provides a graphical interface for sysctl parameters. Changes are applied immediately and persisted to /etc/sysctl.d/99-odyssey.conf. Profiles can be saved and loaded.

control center · 03

Memory & swap. coming soon

Configure zswap compressor and pool limits, swappiness, and cache pressure. Changes take effect immediately without rebooting.

control center · 04

Privacy & firewall. coming soon

Install and configure Tor as a transparent proxy, set up Nginx, manage firewall rules, and enable AppArmor profiles per application.

control center · 05

Boot manager. coming soon

Edit GRUB entries, set the default boot target, configure kernel parameters, and manage boot timeout — without editing grub.cfg manually.

control center · 06

Repositories. coming soon

Enable, disable, and prioritise xbps repositories. Add custom mirrors. Manage /etc/xbps.d/ entries without touching configuration files directly.

desktop environments · 01

KDE Plasma.

KDE Plasma is the default desktop environment in the Odyssey live ISO. It is the most feature-complete option and the one most tested by the maintainer. Wayland and X11 sessions are both available.

  • Default session: Wayland
  • Display manager: SDDM
  • Custom color scheme: EtherOS.colors
  • Default wallpaper: Odyssey wallpaper

desktop environments · 02

XFCE. coming soon

XFCE is available as an option at install time. Lightweight, stable, X11. Documentation will be expanded in the next release.

desktop environments · 03

Cinnamon. coming soon

Cinnamon is available at install time. X11 and Wayland. Documentation will be expanded in the next release.

desktop environments · 04

niri + Noctalia.

niri is a scrollable tiling Wayland compositor. Noctalia Shell is a Qt-based shell layer that provides a bar, launcher, and notifications on top of any Wayland compositor.

  • Session type: Wayland only
  • Configuration: ~/.config/niri/config.kdl
  • Noctalia config: ~/.config/noctalia/
  • WM configurator available in Control Center

desktop environments · 05

Hyprland + Noctalia. next release

Hyprland support with Noctalia Shell is planned for the next release. Dynamic tiling, rich animations, large ecosystem of compatible tools.

advanced · 01

Building from source.

Odyssey is built using xbps-src for packages and void-mklive for the ISO. The build environment is a standard Void Linux glibc installation.

build the kernel

# clone void-packages
$ git clone https://github.com/void-linux/void-packages
$ cd void-packages
 
# add the linux-odyssey template and build
$ ./xbps-src pkg linux-odyssey

build the iso

# requires void-mklive and Calamares installed
$ cd void-mklive
$ sudo bash mklive.sh -o odyssey-1.0-x86_64.iso -v linux-odyssey ...

advanced · 02

Contributing. coming soon

Odyssey is maintained by one person. Contributions are welcome — bug reports, documentation, testing on hardware, and code. Details will be published when the public repository is available.

advanced · 03

FAQ.

can i use odyssey as my primary system?

Yes. But read the about page first. Odyssey is maintained by one person. Void Linux is maintained by a team and is a safer long-term bet if you need guarantees.

can i switch back to the stock void kernel?

$ sudo xbps-remove linux-odyssey linux-odyssey-headers
$ sudo xbps-install linux linux-headers

is odyssey compatible with void packages?

Completely. All packages come from the official Void repositories. There is no fork, no ABI mismatch, no compatibility issue.

does odyssey support arm?

Not currently. x86-64-v3 only. ARM support is not planned in the near term.

where do i report bugs?

The public repository is not yet available. In the meantime, use the contact information on the about page.

about · 01

Roadmap.

  • alpha 0.1 — now — KDE, XFCE, Cinnamon, niri+Noctalia, linux-odyssey 6.12.82, Control Center
  • alpha 0.2 — Hyprland+Noctalia, MangoWM+Noctalia, hardware testing, public repository
  • beta 1.0 — multi-hardware testing, user documentation, public beta
  • release 1.0 — public release

about · 02

Changelog.

alpha 0.1 — 2025

  • Initial ISO — KDE Plasma, XFCE, Cinnamon, niri+Noctalia
  • linux-odyssey 6.12.82 with BORE scheduler
  • Calamares installer patched for runit
  • xbps-gui, runit-gui, Odyssey Control Center
  • Signed xbps repository on Contabo
  • Custom GRUB theme and KDE color scheme