Docs

myLinux is a small Linux desktop that lives entirely in RAM, built for Apple-silicon Macs. It runs as a QEMU virtual machine on Apple's Hypervisor.framework, shows a Qt 6 Wayland compositor with a macOS-style look, and borrows its keyboard-driven workflow and themes from Omarchy. Persistent things live on a separate apps disk.

Install and run

You need an Apple-silicon Mac with macOS 15 or newer, Homebrew, and about 8 GB of free RAM for the virtual machine. Prebuilt images are attached to the GitHub releases, so building is optional.

$ brew install qemu
$ git clone https://github.com/adminmylinux/mylinux.git
$ cd mylinux
$ tools/get-image.sh      # Image + rootfs.cpio.gz of the latest release into out/, SHA-256 checked
$ ./run.sh

run.sh wraps QEMU in out/myLinux.app, so the Mac shows it as "myLinux". The window opens at the size of the display under your mouse pointer. If the first start puts it on another display, give your terminal app Accessibility permission in System Settings › Privacy & Security and it is moved automatically.

Environment variables for run.sh:

First boot

The first boot shows a welcome dialog. "Set up the apps disk" formats the blank out/apps.img, a sparse 16 GB file that run.sh creates, downloads Debian's minimal arm64 rootfs and installs the desktop apps plus Claude Code and Codex. It takes a few minutes and uses about 1.3 GB. Everything you install or save afterwards persists on that disk; your home directory /root is on it.

Only one running virtual machine can hold the apps disk at a time.

Keys

The Mac Option key is the Super key inside myLinux, Cmd stays with macOS. The set follows Omarchy's, so the same fingers work on both. Press OptionK for the full list with search.

Alt+Tab reaches the guest only with GRAB=full, because Alt is the Mac Cmd key and macOS keeps Cmd+Tab otherwise.

Daily use

Startup apps

The desktop opens the Claude and ChatGPT app windows at start. Change the list in share/mylinux.ini; any command works, for example /usr/bin/claude-code for the terminal agent or /usr/bin/foot.

[session]
autostart=/usr/bin/claude-web,/usr/bin/chatgpt

Clipboard

Text copied on the Mac can be pasted inside myLinux right away: run.sh mirrors the Mac clipboard through the share folder and a small daemon in the guest applies it. The other direction is on request, like Omarchy: Option+Ctrl+C sends what you copied in myLinux to the Mac. Text only.

Dock and window frames

The dock hides below the screen edge and slides up when the pointer touches the bottom. Style › "Dock: always visible" keeps it on screen. Apps that draw their own header bar (Firefox, Chromium, Remmina) get no second title bar; plain windows get the macOS-style one. Window › "Title bars" switches between auto, always and never.

Terminal

Option+Enter opens a terminal in your home directory on the apps disk. The base system is BusyBox; everything installed on the apps disk is on the PATH as well, so claude, codex, git, python3 and apt install just work inside the Debian chroot. For a full Debian shell type apps-run bash.

Settings and API keys

The gear in the menu bar opens Settings: OpenRouter, Anthropic, OpenAI and Tailscale API keys and a GitHub token. They are saved with owner-only permissions in ~/.config/mylinux/secrets.env on the apps disk and exported to every new terminal and app.

Tailscale and remote desktops

Tailscale is built in. The menu bar's dot-grid icon opens its panel: Connect joins your tailnet as mylinux, and once connected the panel lists every machine with its online state and IP; click one for an SSH terminal. The dock's Remote Desktop icon starts Remmina for VNC, RDP or SSH profiles. For VNC servers with TLS, put the server certificate in share/ and add a hosts line to share/hosts, which is merged into the guest at every start.

Quitting

Use Shut Down or Restart from the menu at the top left, or type shut into the Option+K sheet. That unmounts the apps disk cleanly. Closing the window or Cmd+Q on the Mac side is a power cut for the virtual machine: the disk is journalled and flushed every second, so you lose at most about a second of writes, but a clean shutdown is the safe habit.

Themes

Themes use Omarchy's format: a directory with colors.toml, optional light.mode and a backgrounds/ folder. Twenty Omarchy palettes ship in the image with generated wallpapers.

• Theme picker: "Download Omarchy backgrounds for all themes" fetches the real Omarchy photos, about 70 MB, into your home on the apps disk.
• Install any Omarchy theme repo from GitHub: type install owner/repo in the theme picker, or run theme-install https://github.com/owner/repo in a terminal.
• Your own themes go in ~/.config/mylinux/themes/<name>/.

Account and sync

An account on this site keeps one profile per machine: the display scale and brightness, keyboard layout, theme and background, the apps that open at start, the Debian packages you added, and free notes. The profile is exactly what share/mylinux.ini holds, plus a package list and notes.

• Sign in and add a machine, say macbook.
• Fill in the form, or paste the contents of share/mylinux.ini into "Import ini".
• On another Mac, download the profile as mylinux.ini into share/ before starting ./run.sh. The packages list is a reminder for install <pkg> in the menu.

API

Create a personal API token under Tokens in your account. It is shown once; the site keeps only a hash. Send it as a bearer token. Machines are addressed by name or id.

$ export MYLINUX_TOKEN=mlx_…
$ curl -sf -H "Authorization: Bearer $MYLINUX_TOKEN" \
    https://mylinux.app/api/machines/macbook/ini -o share/mylinux.ini
$ curl -sf -X PUT --data-binary @share/mylinux.ini \
    -H "Authorization: Bearer $MYLINUX_TOKEN" \
    https://mylinux.app/api/machines/macbook/ini

Build the image yourself

Building needs OrbStack with a Debian machine named debian, because Buildroot wants a case-sensitive filesystem. The build tree lives inside Debian at ~/br; the repository stays on the Mac.

$ sudo apt install -y build-essential git cmake ninja-build python3 rsync bc wget cpio unzip file \
    libncurses-dev libssl-dev bzip2 xz-utils zstd perl-modules ccache gawk texinfo patch
$ mkdir -p ~/br && cd ~/br && git clone --branch 2026.08 --depth 1 https://gitlab.com/buildroot.org/buildroot.git
$ mkdir -p ~/br/output ~/br/dl

$ tools/buildroot-patch.sh
$ orb run -m debian sh -c "cd ~/br/output && make O=\$PWD BR2_EXTERNAL=$PWD -C ~/br/buildroot mylinux_defconfig"
$ ./build.sh              # first build about an hour, later builds minutes
$ tools/sdk-update.sh     # once: export the SDK for the fast shell loop
$ tools/app-build.sh shell # builds shell/ into share/, picked up on the next shell restart

PLAN.md in the repository documents every design decision and milestone.

License

GPL-3.0-or-later. The desktop shell links the Qt Wayland Compositor module, which Qt offers under the GPL v3 only. Theme palettes are from Omarchy (MIT); the Inter font is under the SIL OFL.