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

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

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:

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

updating the kernel

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

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.

xbps+ — unix, spoken human

xbps is powerful, but its commands are famously hard to remember: -S to sync, -Su to upgrade, -Rs to search a repository. Odyssey ships xbps+, a small layer of plain-language commands on top of xbps. No cryptic flags, no looking things up. It is purely additive — every original xbps command above still works exactly the same; xbps+ just gives you a friendlier way in.

Every command starts with o (for Odyssey), so a single o followed by Tab lists them all.

parallel downloads

Plain xbps downloads packages one after another. On a big update with many dependencies, that waiting adds up. xbps+ pre-fetches every package in parallel (via aria2) before handing them to xbps, which then installs straight from cache. The more packages, the bigger the difference.

the full vocabulary

• oadd — install one or more packages
• oremove — remove a package (lists impact, then confirms)
• oorphan — remove orphaned dependencies
• oupdate — sync repositories and upgrade everything
• osearch — search the repositories
• oinfo — show information about a package
• olist — list installed packages
• oreconfigure — reconfigure an installed package
• oalternatives — manage alternatives
• ocheck — verify and repair the package database
• ofetch — download a file by URL
• oupgradable — show which packages have updates
• ochecksum — compute a file digest
• oraw — pass any command straight through to xbps

Anything not covered by a verb is reachable with oraw — for example oraw query -l runs xbps-query -l unchanged. And if you prefer the original tools, just keep using xbps-install, xbps-query and the rest — xbps+ never gets in the way.

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

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
• Firewall — nftables, one-click enable, rule editor
• AppArmor — per-program profiles, enforce/complain modes, violation log
• 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

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

Firewall nftables.

A firewall is a doorman for your network connections. It decides what is allowed to reach your computer from the outside and what gets turned away. With it on, programs on other machines cannot knock on your ports unless you have explicitly allowed them — while everything you start (browsing, updates, games, chat) keeps working normally.

Odyssey ships the firewall turned off, on purpose, so that the very first boot works on any network without surprises. Turning it on is one click in the Control Center, and the rest of this page explains exactly what that click does. You never need the terminal for this — but if you are curious, every step is also shown as a command at the end.

open the panel

Open the Control Center from the application menu and click Firewall. At the top you will see a status row with three indicators. Read them left to right; together they tell you exactly where you are:

• nftables installed — the firewall tool itself. On a fresh install this may say "not installed", and that is fine.
• service — whether the firewall is currently running (enabled) or stopped (disabled).
• ruleset — whether a set of rules exists for the firewall to apply.

turn it on (one click)

This is all most people will ever need to do:

• 1 · Install — if the status row says nftables is not installed, click the Install button. The panel fetches the package and the indicator turns green. Skip this step if it is already installed.
• 2 · Enable — click Enable firewall. The panel writes a safe default ruleset, starts the service, and sets it to start automatically at every boot.

That is it. Your computer now blocks unwanted incoming connections and will keep doing so after a reboot. To switch it off again, the same button becomes Disable firewall.

what the default actually protects

The default rules are the standard, sensible choice for a desktop:

• Incoming connections are blocked — nobody on the network can start a connection to your machine.
• Your own traffic is allowed — anything you start (a website, an update, a game) and its replies come through, because the firewall remembers connections you opened.
• Your computer can talk to itself — local apps that use the loopback interface keep working.

In plain terms: nothing you normally do will break. You will not notice the firewall at all — which is the point.

letting something in (advanced)

Sometimes you want a connection from outside: hosting a game server, sharing files on your LAN, or reaching your machine over SSH. For that you open a port — think of it as unlocking one specific door. In the panel, click Edit rules to open the ruleset, add a line inside the input block, and click Apply. Common examples you can copy:

If you are unsure which port a program needs, check that program's documentation — it will tell you. When you are done, the panel applies the change and it stays after reboot.

One caution — if you are working on a remote machine over SSH, open your SSH port before enabling the firewall, otherwise you will disconnect yourself. On a normal desktop in front of you, this cannot happen.

under the hood

The panel is a friendly front-end over three things you can also handle by hand. The firewall tool is nft; the service lives in /etc/sv/nftables and is enabled by symlinking it into /var/service/; the rules live in /etc/nftables.conf and are loaded at start. Every panel button maps to one of these commands:

The default ruleset the panel writes is this — a single inet table covering both IPv4 and IPv6, with a drop policy on input:

Rules you apply live with nft are forgotten on reboot — only what is written in the file survives, and the panel always writes to the file.

control center · 05

AppArmor profiles.

AppArmor puts individual programs on a leash. For each protected program there is a profile — a list of the files and actions that program is allowed to use. If the program tries to do anything outside that list, it is stopped. The benefit is simple: even if an app is buggy or hijacked, the harm it can do is limited to its leash instead of your whole system. It works quietly in the background; you do not have to configure anything for the protection to be there.

The Control Center AppArmor module lets you see what is protected, loosen or tighten it, and check whether anything has been blocked — all without editing files. Because this reads system-level settings, it asks for your password once when you open it.

the one idea to understand: modes

Every profile is always in one of three modes. Picture a security guard at a door:

• Enforce ● — the guard blocks anything not on the list and writes it down. This is full protection.
• Complain ◐ — the guard lets everything through but writes down anything that wasn't on the list. Nothing is blocked; it is "watch and learn" mode, used to see what a program needs before you lock it down.
• Disabled ○ — the guard is off duty. The program runs with no leash at all.

That single distinction explains everything the panel does. Most users never need to change a mode — Odyssey ships sensible defaults — but it is good to know what the colours mean.

the panel: two tabs

The module has two tabs.

• Profiles — the full list of profiles on the system, each with a coloured dot showing its mode. A line at the top counts how many are in enforce, complain, and disabled, so you get the overall picture at a glance. A search box filters the list by name. Click a profile to switch its mode (enforce / complain / disable) or to open its file. Two buttons act on everything at once: All complain and All enforce.
• Violations — a log of what has been blocked or noted: which program tried to do something outside its leash, and what that something was. Double-click an entry to jump straight to the profile responsible.

A note for newcomers: seeing entries in Violations is not automatically a problem — it is the system telling you it is doing its job. And the two bulk buttons are powerful: All enforce on profiles that were never tuned can make some apps misbehave, so use it deliberately, not as a reflex.

how to confine a program yourself

If you want to bring a new program under AppArmor, the safe order is always learn first, lock down second. Never jump straight to enforce on a profile you have not watched — you will break the program the first time it does something the profile forgot to allow. In the panel:

• 1 — set the program's profile to complain (nothing is blocked yet).
• 2 — use the program normally for a while, doing the things you actually do with it.
• 3 — open the Violations tab and look at what it tried to do. Decide which of those actions are legitimate.
• 4 — once you have allowed the legitimate actions and the log stays quiet, switch the profile to enforce.

From then on the program is protected: anything new it tries to reach is blocked and logged.

under the hood

Profiles are plain text files in /etc/apparmor.d/, the protection runs in the kernel, and the service lives in /etc/sv/apparmor. The panel buttons map directly to these commands:

Blocked accesses are recorded in /var/log/audit/audit.log (or the kernel log, dmesg, if auditd is not installed). A denial line names the profile and what it was refused — for example, profile usr.bin.foo was stopped from reading /etc/secret. If that access should be allowed, add it to the profile and reload; if not, the leash just did exactly its job.

control center · 06

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 · 07

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.

applications · 01

Repository & applications.

Void Linux deliberately leaves out a number of packages for design and policy reasons. Odyssey is apolitical by design, so the Odyssey supplementary repository ships many of the applications people actually look for — without pushing you toward Flatpak, which Odyssey discourages for technical reasons.

The base system stays minimal. The applications below are the curated defaults, chosen for performance, privacy, and the Unix philosophy — GPL software is preferred wherever possible. Each one is themed to match Odyssey and ships with a way back to its unmodified upstream behaviour. Alongside them Odyssey provides a curated file manager and a notes application.

• Zen — browser, hardened for privacy, profile loaded in RAM
• Kitty — GPU-accelerated terminal with the Odyssey menu
• MPV — media player with a custom Odyssey skin

also in the repository

Beyond the defaults, the repo carries popular packages Void does not provide out of the box — for example Hyprland, Ollama, Brave, Obsidian, and common databases. The goal is a repository complete enough that you rarely need anything outside it.

applications · 02

Zen browser.

Zen is the default Odyssey browser — a Firefox-based browser with a clean, modern interface. Odyssey ships it hardened for privacy: the profile is configured with settings adapted from LibreWolf — anti-tracking, telemetry disabled, restrictive policies — so it protects you out of the box with no extra setup.

profile in RAM

Odyssey adds a script that, on machines with 4 GB of RAM or more, loads the entire browser profile into RAM at startup. Tabs open instantly and overall responsiveness improves noticeably. The script reads your hardware first: on machines with less than 4 GB it detects this and skips the RAM profile entirely, so it never compromises a low-memory system.

the RAM profile is a separate package

The profile-in-RAM feature ships as its own package, odyssey-browser-ram, kept separate from the Zen package so browser updates never touch the RAM logic. It migrates the Zen profile into /dev/shm at login, snapshots it back to disk every three minutes (atomic SQLite backups, so the databases never corrupt while Zen is open), and saves on logout. A clean shutdown loses nothing; an unclean one — power loss, kernel panic — can lose at most the last few minutes. On machines with too little RAM the feature auto-disables and Zen runs from disk.

returning to a stock browser

To run Zen from an ordinary on-disk profile, turn the RAM feature off. It can be disabled per user, or removed from the system entirely.

This affects only the RAM profile. The privacy hardening is independent — it ships inside the Odyssey zen-browser package as three files, applied through Mozilla's autoconfig and enterprise-policy mechanism (the same approach LibreWolf uses):

Removing those files returns the browser to upstream defaults. local-settings.js is the bridge that activates zen.cfg, so without it the preferences are ignored; policies.json is enforced separately and also sets DuckDuckGo as the default search engine. Because the three files are part of the Odyssey package, a reinstall or update of zen-browser restores them — for a permanently stock browser, install Zen from upstream instead of the Odyssey package.

applications · 03

Kitty terminal.

Kitty is the default terminal — GPU-accelerated, GPLv3, and one of the fastest terminals available. Odyssey ships it themed to match the rest of the system: black background, #e8192c accent, JetBrains Mono, a red block cursor, a custom tab bar, and the Odyssey ANSI palette.

the odyssey menu

Vanilla Kitty has no menus — it is keyboard-driven by design. Odyssey adds a clickable menu, opened with Ctrl+Shift+Space, that exposes extra functions on top of Kitty without getting in the way of purists.

• Switch between multiple Kitty sessions
• Plan 9 tools — the rc shell and the acme editor
• Navigate between tabs
• Reset — remove all Odyssey customisations and return to vanilla Kitty

common keybindings

configuration

All Kitty configuration lives in ~/.config/kitty/ — the main kitty.conf, the menu kitten odyssey-launch.py, and the custom tab bar tab_bar.py.

returning to vanilla kitty

The quickest way is the Reset entry in the Odyssey menu (Ctrl+Shift+Space), which removes the customisations for you. To do it by hand, move the config aside so Kitty falls back to its built-in defaults:

applications · 04

MPV media player.

MPV is the default media player — minimal, scriptable, and extremely fast. Odyssey ships it with a custom skin in the project style, with red playback controls.

returning to stock mpv

MPV configuration and the Odyssey skin live in ~/.config/mpv/. Move or remove that directory and MPV reverts to its default appearance and behaviour.

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

build the iso

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?

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.

Odyssey is developed in private. Alphas and betas circulate among contributors; the release candidate is the first build open to everyone. The dates below are targets, not promises.

where we are

• alpha 4 — feature freeze · now — everything planned is in. From here on it is bug fixing, cleanup and polish only — no new features before 1.0.

what's next

• alpha 5 — June — bug fixing, native-app polish, terminal integration
• alpha 6 — early July — desktop and window-manager refinements, full app translation
• beta 1 — mid-July — wider hardware testing, user documentation, stabilisation
• release candidate — mid-to-late August — first public build; closed development opens up here
• 1.0 — early September — public release, shipping with the complete manual

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