genie

Initialize the bottle (run once, at start)

$ genie [[-i|--initialize]]

$ genie [[-s|--shell]]

$ genie [[-c|--command]] [command]

genie [ACTION] [OPTIONS]
genie -s | --status
genie -e | --enter
genie -u | --shutdown
genie [-h | --help] [-v | --version]
genie [--init-timeout <seconds>] [--shell-timeout <seconds>] [--chroot] [--start-unit <unit>]

-h, --help
    Displays a help message outlining genie's usage and options.

-v, --version
    Shows the current version information of the genie utility.

-s, --status
    Checks and displays the current operational status of the systemd environment managed by genie.

-e, --enter
    Enters the systemd-enabled environment. This is the default action if no other action is specified.

-u, --shutdown
    Initiates a graceful shutdown of the systemd environment and associated processes.

--init-timeout <seconds>
    Specifies the maximum time (in seconds) to wait for systemd to fully initialize.

--shell-timeout <seconds>
    Sets a timeout (in seconds) for the shell to start up when entering the genie environment.

--chroot
    Uses a chroot-like mechanism when entering the systemd environment. This is an advanced option for specific use cases.

--start-unit <unit>
    After entering the systemd environment, attempts to start the specified systemd unit (e.g., docker.service).

The genie command is a specialized utility designed for the Windows Subsystem for Linux 2 (WSL2) environment. Its primary purpose is to enable the full functionality of systemd within WSL2 distributions, which by default do not run systemd as their init process.

Many Linux applications and services, such as snapd, Docker, and various background daemons, rely on systemd for proper initialization and management. genie acts as an init wrapper, creating a nested, isolated environment where systemd is properly initialized as PID 1. This allows users to run and manage systemd-dependent applications and services within their WSL2 instances, bridging a significant gap in WSL2's native capabilities. It provides commands to enter this systemd environment, check its status, and gracefully shut it down, thereby offering a more complete and functional Linux experience.

The genie command is specifically designed for and primarily functions within the Windows Subsystem for Linux 2 (WSL2) environment. It is not a standard, general-purpose Linux command found on bare-metal installations or typical virtual machines. Its operation relies on specific WSL2 characteristics and the presence of systemd within the WSL distribution.

While highly effective, genie provides a community-driven solution and is not officially supported by Microsoft for integrating systemd into WSL. Users should be aware that updates to WSL or systemd itself might occasionally require adjustments or lead to temporary incompatibilities. Performance overhead is generally minimal but can exist due to the nested environment.

genie operates by launching a minimal init process that, in turn, starts systemd as the true PID 1 within a dedicated cgroup namespace. When a user executes genie -e (or similar), it creates a pseudo-login session that effectively chroots or namespaces the user's shell into this systemd-controlled environment. This allows commands executed by the user to interact directly with the systemd instance, enabling the management and execution of systemd-dependent services.

genie is typically not pre-installed on Linux distributions. Users usually install it by downloading pre-built binaries from the official GitHub releases page (arkane-systems/genie) or by compiling it from source. Once installed, it's often added to the user's $PATH for easy execution. Basic usage involves running genie -e to enter the environment, genie -s to check status, and genie -u to shut down the systemd instance within WSL2.

The genie project was developed by arkane-systems (Tarun Kumar) in response to a key limitation of the initial Windows Subsystem for Linux 2 (WSL2) architecture: its lack of native systemd support. By default, WSL2 distributions did not run systemd as PID 1, which prevented many common Linux applications and services (such as snapd, Docker daemon, and others that rely on systemd for process management and dependencies) from functioning correctly or easily.

genie quickly emerged as a prominent community-driven solution, offering a robust method to spin up a systemd-managed environment within WSL2. Its development was motivated by the desire to provide WSL2 users with a more complete and traditional Linux experience, allowing them to leverage systemd-dependent software without resorting to full virtual machines or complex workarounds. Its continued usage highlights its effectiveness in bridging this gap.

wsl(1), systemctl(1), init(8), chroot(1)