ZacharyZhang-NY/omarchycn
2
2
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 3 Wiki Activity

First pass on updates for Quattro

Browse Source
This commit is contained in:
David Heinemeier Hansson
2026-08-13 15:18:33 +02:00
parent 9c9e082954
commit 144f4d1e31
42 changed files with 474 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files
manual/01-welcome-to-omarchy.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Welcome to Omarchy!
Omarchy is an [omakase](https://manuals.omamix.org/3/omacom/76/omakase-computing) Linux distribution based on [Arch](https://archlinux.org/) and the tiling window manager [Hyprland](https://hypr.land/). It ships with everything a modern software developer needs to be productive immediately from [Neovim](https://neovim.io/) (btw) to Spotify, Chromium to [Typora](https://typora.io/), and [Alacritty](https://alacritty.org/) to LibreOffice. Hell, even Zoom is there!
Omarchy is an [omakase](https://manuals.omamix.org/3/omacom/76/omakase-computing) Linux distribution based on [Arch](https://archlinux.org/), the tiling window manager [Hyprland](https://hypr.land/), and the desktop construction-kit [Quickshell](https://quickshell.org/). It ships with everything a modern software developer needs to be productive immediately from [Neovim](https://neovim.io/) (btw) to Chromium, [Obsidian](https://obsidian.md/) to LibreOffice, and Kdenlive to OBS Studio. Hell, even a retro Winamp-style music player is there!
This isn't just a grab bag of preinstalled packages, though. It's a complete system designed with both aesthetics and productivity in mind. Because a _beautiful_ system is a _motivating_ system, and productivity has always been [downstream from motivation](https://world.hey.com/dhh/beautiful-motivations-6fef7c73). There's zero bloat here: Just everything I use.
manual/02-getting-started.md
+10 -6
View File
@@ -1,6 +1,6 @@
# Getting Started
Omarchy is installed using an ISO. It's designed for a dedicated drive, so dual-booting requires two disks in your machine (unless you do a [manual install](38-manual-installation.md) to work around this). The installation will wipe the selected drive and use full-disk encryption, so be sure to take a backup before using an existing drive!
Omarchy is installed using an ISO. You can choose between a full-disk install, which takes over the entire drive, or a free-space install, which puts Omarchy in the unallocated space on a drive — that's how you dual boot alongside Windows or another OS (see [dual-boot install](44-dual-boot-install.md) — note that you'll need to turn off BitLocker in Windows first). Either way, the installation uses full-disk encryption, and the full-disk option will wipe the selected drive, so be sure to take a backup before using an existing one!
[Download the Omarchy ISO](https://omarchy.org/) first, put it on a USB stick (use [balenaEtcher](https://etcher.balena.io/) on Mac/Windows or [caligula](https://github.com/ifd3f/caligula) on Linux), and boot off the stick.
@@ -20,16 +20,20 @@ Now you're ready to Omarchy!
The full-disk encryption won't allow you to enter the password from a Bluetooth keyboard at startup. Just like you can't use a Bluetooth keyboard to enter the BIOS on a PC. You'll need a keyboard that either uses a 2.4ghz dongle or a cable (which is much nicer for latency anyway!). I personally love the [Lofree Flow84](https://www.lofree.co/products/lofree-flow-the-smoothest-mechanical-keyboard)!
### Installing for another owner
If you're setting up a machine for someone else — a family member, a new employee, a buyer — you shouldn't be answering the personal questions on their behalf. Hit `Ctrl + C` on the very first screen of the installer (the keyboard selection), and Omarchy will offer to prepare the machine for another owner instead. The system installs right away, but all the personal setup — keyboard layout, username, password — is deferred until the machine boots for the first time. The drive is still encrypted by default, and the password the new owner picks on that first boot becomes the encryption password too.
### Unattended installs
The ISO can also install completely on its own — no keyboard, no wizard — when it's handed its configuration on a second drive. That's the way to treat Omarchy as a base image for VMs and fleet machines. See [unattended installs](45-unattended-installs.md).
### No-encryption installations
Omarchy is installed with encryption by default. It's the safe, reasponsible choice for any computer that can possibly be lost or stolen. You don't want anyone with access to your hardware to be able to get your data!
Omarchy is installed with encryption by default. It's the safe, responsible choice for any computer that can possibly be lost or stolen. You don't want anyone with access to your hardware to be able to get your data!
But in special circumstances, like remote Omarchy installs on protected computers or for throw-away installations without sensitive data, you may want to install without encryption. You can hit `Ctrl + C` on the disk formatting confirmation to switch to an encryption-less installation.
### Help if you're stuck
If you get stuck, you can usually find someone willing to help in the _#omarchy-help_ channel on [the community Discord](https://omarchy.org/discord).
### Use manual installation for special needs
If you have special needs, like installing Omarchy onto M-Series MacBooks [Asahi Alarm](https://asahi-alarm.org/) or because you want to try dual-booting on a single drive, you should follow [the instructions for a manual installation](38-manual-installation.md).
manual/03-navigation.md
+14 -6
View File
@@ -1,16 +1,16 @@
# Navigation
Everything in Omarchy happens via the keyboard — _EVERYTHING!_ When the system first starts, you literally can't do a thing with the mouse alone. But you can hit `Super + Space` to reveal the application launcher and `Super + Alt + Space` to open the Omarchy Menu. These two commands allow you to do just about everything.
Everything in Omarchy happens via the keyboard — _EVERYTHING!_ When the system first starts, you literally can't do a thing with the mouse alone. But you can hit `Super + Space` to reveal the Omarchy Menu and from here you to do just about everything.
But the application launcher is not intended to be the main way to operate the system most of the time. We can get faster than that! All the most important applications are bound directly to individual hotkeys. You start the terminal with `Super + Return` and a browser with `Super + Shift + Return`. Try doing one after the other, and you'll see the magic of Hyprland's tiling in action:
But the Omarchy menu is not even intended to be the main way to operate the system most of the time. We can get faster than that! All the most important applications are bound directly to individual hotkeys. You start the terminal with `Super + Return` and a browser with `Super + Shift + Return`. Try doing one after the other, and you'll see the magic of Hyprland's tiling in action:
![browser+terminal.png](https://manual.omakub.org/u/browser-terminal-yCV75f.png)
You can then hit `Super + J` to stack them horizontally instead of vertically:
You can then hit `Super + J` to stack them on top of each other instead of side by side:
![stacked.png](https://learn.omacom.io/u/stacked-sswEJE.png)
Hit `Super + J` again to return them to horizontal positions. Then try `Super + Shift + Arrow Right` while on the browser to swap the windows.
Hit `Super + J` again to return them to their side-by-side positions. Then try `Super + Shift + Arrow Right` while on the browser to swap the windows.
Now try `Super + Ctrl + T` to start the Activity monitor. That'll appears as a floating window. You can tile it using `Super + T` (and hit that again to make it floating again). Now press `Super + Shift + F` to open the files manager. You'll have a neat four-way setup:
@@ -36,11 +36,19 @@ But you can also choose to turn a workspace into the scrolling layout where wind
![niri-layout.png](https://learn.omacom.io/u/niri-layout-LvV25i.png)
If you wish to ue the scrolling layout as the default, you can set that in `~/.config/hypr/looknfeel.conf` under `general { layout = scrolling }`.
If you wish to use the scrolling layout as the default, you can set that in `~/.config/hypr/looknfeel.lua`:
```lua
hl.config({
general = {
layout = "scrolling",
},
})
```
### Grouping windows
Windows can be grouped using `Super + G`. Once you're in a group, every window you start while that's active will belong to the group. You can move between these grouped windows using `Super + Ctrl + Arrows` or `Super + Alt + 1/2/3/4` to go directly to grouped window in order.
Windows can be grouped using `Super + G`. Once you're in a group, every window you start while that's active will belong to the group. You can move between these grouped windows using `Super + Ctrl + Arrow Left/Right` or `Super + Alt + 1/2/3/4` to go directly to grouped window in order.
You can move a window out of the grouping with `Super + Alt + G` or disassemble the entire group by hitting `Super + G` again. Finally, you can move windows outside the group into it with `Super + Alt + Arrows`.
manual/04-themes.md
+2 -2
View File
@@ -1,8 +1,8 @@
# Themes
Omarchy comes with nineteen beautiful themes. You can select between them via _Style > Theme_ in the Omarchy Menu (`Super + Alt + Space`) or hop directly to the theme selector using `Super + Ctrl + Shift + Space`.
Omarchy comes with twenty-two beautiful themes. You can select between them via _Style > Theme_ in the Omarchy Menu (`Super + Space`) or hop directly to the theme selector using `Super + Ctrl + Shift + Space`.
Each theme styles the desktop, terminal, neovim, activity screen (btop), notifications (mako), top bar (waybar), application launcher (walker), and the lock screen (hyprlock). (For Obsidian, you must manually select the Omarchy theme via _Appearance > Themes_ inside the app).
Each theme styles the desktop, terminal, neovim, activity screen (btop), Chromium, and the entire Omarchy shell: top bar, menu, notifications, OSD, and the lock screen. (For Obsidian, you must manually select the Omarchy theme via _Appearance > Themes_ inside the app).
Themes have a set of background images that you can pick between using `Super + Ctrl + Space`.
manual/05-hotkeys.md
+49 -24
View File
@@ -1,13 +1,13 @@
# Hotkeys
You can see all the main keyboard bindings with `Super + K`.
You can see all the main keyboard bindings with `Super + K` (Tmux bindings with `Super + Alt + K` and Herdr bindings with `Super + Ctrl + K`).
## Navigating
| Hotkey | Function |
| ----------------------- | --------------------- |
| `Super + Space` | Application launcher |
| `Super + Alt + Space` | Omarchy control menu |
| `Super + Space` | Omarchy menu (apps and everything else) |
| `Super + Alt + Space` | Apps menu |
| `Super + Escape` | System menu (suspend, restart, etc) |
| `Super + Ctrl + L` | Lock computer |
| `Super + W` | Close window |
@@ -29,19 +29,24 @@ You can see all the main keyboard bindings with `Super + K`.
| `Super + Shift + Alt + Arrows` | Move workspaces to directional monitor |
| `Super + Arrow` | Move focus to window in direction of arrow |
| `Super + Shift + Arrow` | Swap window with another in direction of arrow |
| `Super + Equal` | Grow windows to the left |
| `Super + Minus` | Grow windows to the right |
| `Super + Shift + Equal` | Grow windows to the bottom |
| `Super + Shift + Minus` | Grow windows to the top |
| `Super + Minus` | Expand window left |
| `Super + Equal` | Shrink window left |
| `Super + Shift + Minus` | Shrink window up |
| `Super + Shift + Equal` | Expand window down |
| `Super + Alt + Minus/Equal` | Same resizing in smaller steps |
| `Super + Ctrl + Minus/Equal` | Same resizing in bigger steps |
| `Super + Alt + Home` | Save window width |
| `Super + Home` | Restore saved window width |
| `Super + Left Mouse` | Drag window around |
| `Super + Right Mouse` | Resize window |
| `Super + Scroll Wheel` | Scroll through workspaces |
| `Super + G` | Toggle window grouping |
| `Super + Alt + G` | Move window out of grouping |
| `Super + Alt + Tab` | Cycle between windows in grouping |
| `Super + Alt + 1/2/3/4` | Jump to specific window in grouping |
| `Super + Alt + Shift + Tab` | Cycle backward between windows in grouping |
| `Super + Alt + 1/2/3/4/5` | Jump to specific window in grouping |
| `Super + Alt + Arrow` | Move window into grouping in direction of arrow |
| `Super + Ctrl + Arrow` | Move between windows inside a tiling group |
| `Super + Ctrl + Left/Right` | Move between windows inside a tiling group |
| `Super + S` | Show scratchpad workspace overlay |
| `Super + Alt + S` | Move window to scratchpad workspace |
| `Super + Ctrl + Z` | Zoom in on screen (repeat for more zoom) |
@@ -57,22 +62,28 @@ You can see all the main keyboard bindings with `Super + K`.
| Hotkey | Function |
| ----------------------- | --------------------- |
| `Super + Ctrl + A` | Audio controls (wiremix) |
| `Super + Ctrl + B` | Bluetooth controls (bluetui) |
| `Super + Ctrl + W` | Wifi controls (impala) |
| `Super + Ctrl + A` | Audio panel |
| `Super + Ctrl + B` | Bluetooth panel |
| `Super + Ctrl + W` | Wifi/network panel |
| `Super + Ctrl + D` | Display panel |
| `Super + Ctrl + P` | Power panel |
| `Super + Ctrl + Alt + D` | Calendar panel |
| `Super + Ctrl + 1-9` | Toggle bar panel by position |
| `Super + Ctrl + S` | Share menu (via LocalSend) |
| `Super + Ctrl + T` | Activity (btop) |
| `Super + Ctrl + C` | Capture controls (screenshot/-recording/picker) |
| `Super + Ctrl + O` | Toggle menu |
| `Super + Ctrl + H` | Hardware menu |
| `Super + Ctrl + .` | Transcoding menu |
| `Super + Ctrl + Q` | Calculator |
| `Super + Ctrl + .` | Transcode media |
| `Super + Shift + Ctrl + A` | Pick an AI agent |
## Adjustments
| Hotkey | Function |
| ----------------------- | --------------------- |
| `Shift + Brightness Up` | Maximum screen brightness |
| `Shift + Brightness Up` | Minimum screen brightness |
| `Shift + Brightness Down` | Minimum screen brightness |
| `Alt + Brightness Up/Down` | Precise 1% brightness changes |
| `Alt + Volume Up/Down` | Precise 1% volume changes |
@@ -82,6 +93,7 @@ You can see all the main keyboard bindings with `Super + K`.
| ----------------------- | --------------------- |
| `Super + Return` | Terminal |
| `Super + Alt + Return` | Tmux terminal |
| `Super + Ctrl + Return` | Herdr (agent manager) |
| `Super + Shift + Return` | Browser |
| `Super + Shift + Alt + B` | Browser (private/incognito) |
| `Super + Shift + F` | File manager |
@@ -89,23 +101,25 @@ You can see all the main keyboard bindings with `Super + K`.
| `Super + Shift + M` | Music (Spotify) |
| `Super + Shift + Alt + M` | Music (cliamp) |
| `Super + Shift + /` | Password manager (1password) |
| `Super + Shift + N` | Neovim |
| `Super + Shift + N` | Editor (Neovim) |
| `Super + Shift + C` | Calendar ([HEY](https://hey.com/)) |
| `Super + Shift + E` | Email ([HEY](https://hey.com/)) |
| `Super + Shift + Alt + E` | New email ([HEY](https://hey.com/)) |
| `Super + Shift + A` | AI (ChatGPT) |
| `Super + Shift + Alt + A` | AI (Grok) |
| `Super + Shift + G` | Messenger (Signal) |
| `Super + Shift + P` | Google Photos |
| `Super + Shift + S` | Google Maps |
| `Super + Shift + Alt + G` | Messenger (WhatsApp) |
| `Super + Shift + Ctrl + G` | Messenger (Google) |
| `Super + Shift + D` | Docker (LazyDocker) |
| `Super + Shift + O` | Obsidian |
| `Super + Shift + W` | Writing (Typora) |
| `Super + Shift + W` | Writing (Omawrite) |
| `Super + Shift + X` | X |
| `Super + Shift + Alt + X` | X Compose |
| `Super + Shift + Y` | YouTube |
Change/add bindings in `~/.config/hypr/bindings.conf`.
Change/add bindings in `~/.config/hypr/bindings.lua`.
## Universal clipboard
@@ -116,7 +130,7 @@ Change/add bindings in `~/.config/hypr/bindings.conf`.
| `Super + V` | Paste |
| `Super + Ctrl + V` | Clipboard manager |
Usually on Linux, you need `Ctrl + Shift + C/V` to copy'n'paste in the terminal and `Ctrl + C/V` to do it everywhere else. These Omarchy unified clipboard hotkeys work everywhere (except the file manager).
Usually on Linux, you need `Ctrl + Shift + C/V` to copy'n'paste in the terminal and `Ctrl + C/V` to do it everywhere else. These Omarchy unified clipboard hotkeys work everywhere.
## Capture
@@ -127,13 +141,15 @@ Usually on Linux, you need `Ctrl + Shift + C/V` to copy'n'paste in the terminal
| `Alt + Print Screen` | Screenrecord |
| `Super + Print Screen` | Color picker |
| `Super + Ctrl + Print Screen` | Text extraction to clipboard |
| `Super + Alt + [` | Make webcam overlay smaller while recording |
| `Super + Alt + ]` | Make webcam overlay larger while recording |
| `Alt + Shift + L` | Copy current URL from webapp or Chromium |
| `Super + Ctrl + X` | Start/stop dictation (requires _Install > AI > Dictation_) |
| `F9` | Push-to-talk dictation (requires _Install > AI > Dictation_) |
With screenrecordings, hit the hotkey to start, hit it again to stop.
All capture options are also accessible under _Capture_ in the Omarchy menu (`Super + Alt + Space`).
All capture options are also accessible under _Trigger > Capture_ in the Omarchy menu (`Super + Space`).
## Notifications
@@ -143,6 +159,7 @@ All capture options are also accessible under _Capture_ in the Omarchy menu (`Su
| `Super + Shift + ,` | Dismiss all notifications |
| `Super + Ctrl + ,` | Toggle silencing notifications |
| `Super + Alt + ,` | Invoke most recent notification |
| `Super + Shift + Alt + ,` | Open notification history |
## Style
@@ -153,20 +170,21 @@ All capture options are also accessible under _Capture_ in the Omarchy menu (`Su
| `Super + Backspace` | Toggle transparency on a window |
| `Super + Ctrl + Backspace` | Toggle single-window square aspect |
Extra background images live in `~/.config/omarchy/current/backgrounds`. Also available via _Install > Background_ in the Omarchy menu.
Extra background images live in `~/.config/omarchy/backgrounds/<theme name>`. Also available via _Install > Style > Background_ in the Omarchy menu.
All style options are also accessible under _Style_ in the Omarchy menu (`Super + Alt + Space`).
All style options are also accessible under _Style_ in the Omarchy menu (`Super + Space`).
## Toggles
| Hotkey | Function |
| ----------------------- | --------------------- |
| `Super + Ctrl + I` | Toggle idle/sleep prevention |
| `Super + Ctrl + I` | Toggle locking on idle |
| `Super + Ctrl + N` | Toggle nightlight display temperature |
| `Super + Ctrl + Delete` | Toggle laptop display on/off |
| `Super + Ctrl + Alt + Delete` | Toggle laptop display mirroring |
| `Super + Shift + Space` | Toggle the top bar |
| `Super + Mute` | Switch to next audio output |
| `Shift + Mute` | Switch to next audio output |
| `Shift + Play` | Switch to next media source |
| `Super + Shift + Backspace` | Toggle window gaps |
## Reminders
@@ -183,7 +201,7 @@ All style options are also accessible under _Style_ in the Omarchy menu (`Super
| ----------------------- | --------------------- |
| `Super + Ctrl + Alt + T` | Show time as notification |
| `Super + Ctrl + Alt + B` | Show battery as notification |
| `Super + Ctrl + Alt + W` | Show weather as notification |
| `Super + Ctrl + Alt + W` | Toggle weather as notification |
## Tmux
@@ -197,6 +215,9 @@ The prefix key is `Ctrl + Space` (`Ctrl + B` also works). You can change these b
| `Prefix + h` | Split pane below (horizontal) |
| `Prefix + x` | Kill pane |
| `Prefix + z` | Toggle pane zoom (fullscreen) |
| `Alt + Enter` | Split pane below (no prefix) |
| `Alt + Shift + Enter` | Split pane beside (no prefix) |
| `Alt + Escape` | Kill pane (no prefix) |
| `Ctrl + Alt + Arrows` | Move between panes |
| `Ctrl + Alt + Shift + Arrows` | Resize panes |
@@ -209,6 +230,7 @@ The prefix key is `Ctrl + Space` (`Ctrl + B` also works). You can change these b
| `Prefix + r` | Rename window |
| `Alt + 1-9` | Go to specific window |
| `Alt + Arrow Left/Right` | Move between windows |
| `Alt + Shift + Arrow Left/Right` | Move window left/right |
### Sessions
@@ -236,6 +258,7 @@ The prefix key is `Ctrl + Space` (`Ctrl + B` also works). You can change these b
| Hotkey | Function |
| ----------------------- | --------------------- |
| `Prefix + q` | Reload config |
| `Prefix + ?` | Show Tmux keybindings |
| `Prefix + :` | Command prompt |
### Tmux layout functions
@@ -321,6 +344,7 @@ You can use `Super + Ctrl + E` to show a complete emoji picker that'll put the s
| `CapsLock M R` | 🤘 | rock |
| `CapsLock M K` | 😘 | kiss |
| `CapsLock M E` | 🙄 | eyeroll |
| `CapsLock M I` | 😉 | wink |
| `CapsLock M P` | 🙏 | pray |
| `CapsLock M D` | 🤤 | drool |
| `CapsLock M M` | 💰 | money |
@@ -333,6 +357,7 @@ You can use `Super + Ctrl + E` to show a complete emoji picker that'll put the s
| `CapsLock M B` |🤯 | blowing |
## Quick Completions
| Hotkey | Completion |
| ------------ | ---------- |
| `CapsLock Space Space` | — (mdash) |
manual/06-unified-clipboard-history.md
+1 -1
View File
@@ -15,7 +15,7 @@ _Note that most agent harnesses will use `Ctrl + V` for pasting images, but `Sup
### Clipboard history
The clipboard history is provided by Walker and works for both text and images. You trigger it by `Super + Ctrl + V`, select your entry with return, and then that'll be placed on the clipboard ready to paste on `Super + V`.
The clipboard history is provided by the Omarchy shell and works for both text and images. You trigger it by `Super + Ctrl + V`, select your entry with return, and then that'll be placed on the clipboard ready to paste on `Super + V`.
![clipbord-history.png](https://learn.omacom.io/u/clipbord-history-soxtYp.png)
manual/08-notices.md
+1 -1
View File
@@ -4,7 +4,7 @@ You can quickly access the date and time, battery status, and current weather us
### Date & Time
`Super + Ctrl + At + T`
`Super + Ctrl + Alt + T`
![datetime-notice.png](https://learn.omacom.io/u/datetime-notice-dnB5VT.png)
manual/10-omarchy-cli.md
+14 -8
View File
@@ -1,6 +1,6 @@
# Omarchy CLI
Omarchy is usually controlled through the hotkeys and the Omarchy menu (`Super + Alt + Space`). But you can also control it through the `omarchy` CLI. This is particularly helpful when you're having an AI agent work with you on customization or configuration.
Omarchy is usually controlled through the hotkeys and the Omarchy menu (`Super + Space`). But you can also control it through the `omarchy` CLI. This is particularly helpful when you're having an AI agent work with you on customization or configuration.
The CLI has access to all the internal tooling that is used both via the menu and otherwise. You can see everything that's available by running `omarchy` in the terminal.
@@ -25,18 +25,21 @@ Common commands:
omarchy debug Print debugging information
Groups:
ac AC power detection
agent AI coding agent usage data
audio Audio input and output controls
bar Omarchy shell bar layout and settings
battery Battery status helpers
bluetooth Bluetooth device controls
branch Omarchy git branch management
branding About and screensaver branding
brightness Display and keyboard brightness
capture Screenshots and screen recording
channel Omarchy release channel management
clipboard Clipboard helpers
cmd Command and shortcut helpers
config System configuration helpers
debug Diagnostics and support logs
dev Omarchy development tools
drive Drive selection and encryption
font Font management
...
```
And you can dive deeper on every group:
@@ -44,7 +47,10 @@ And you can dive deeper on every group:
```
~ ❯ omarchy capture
Capture commands — Screenshots and screen recording:
omarchy capture screenrecording [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--resolution=<size>] [--stop-recording] Start or stop screen recording
omarchy capture screenshot [smart|region|windows|fullscreen] [slurp|copy] [--editor=<name>] Take a screenshot
omarchy capture text extraction Extract text from a screenshot region with OCR
omarchy capture qr Decode a QR code from a screenshot region
omarchy capture screenrecording [--fullscreen] [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--webcam-size=<small|medium|large>] [--resolution=<size>] [--stop-recording] Start or stop screen recording
omarchy capture screenrecording with webcam Pick a webcam and start a screen recording with it
omarchy capture screenshot [smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>] Take a screenshot
omarchy capture text Extract text from a screenshot region with OCR
omarchy capture webcam resize <smaller|larger|reset|small|medium|large> Resize the active webcam recording overlay
```
manual/11-terminal.md
+7 -5
View File
@@ -1,10 +1,10 @@
# Terminal
[Alacritty](https://alacritty.org/) is the default terminal for Omarchy. It's fast, beautiful, and compatible with even old computers. It does not, however, support native tabs, splits, or image rendering.
[Foot](https://codeberg.org/dnkl/foot) is the default terminal for Omarchy. It's fast, lightweight, and compatible with even old computers. It does not, however, support native tabs or splits.
If you use Tmux, you may not mind, but if not, we fully support _Ghostty_, _Foot_, and _Kitty_ as options as well. Pick your preference under _Install > Terminal_ in the Omarchy menu.
If you use Tmux, you may not mind, but if not, we fully support _Alacritty_, _Ghostty_, and _Kitty_ as options as well. Pick your preference under _Install > Terminal_ in the Omarchy menu.
You start a new terminal using `Super + Return`. (This binding will automatically point to whichever Terminal you've installed via _Install > Terminal_.)
You start a new terminal using `Super + Return`. (This binding will automatically point to whichever Terminal you've installed via _Install > Terminal_, and you can switch between installed terminals under _Setup > Defaults > Terminal_.)
## Tmux
@@ -16,7 +16,7 @@ Omarchy ships with an ergonomically-optimized Tmux configuration, which has a lo
## Tmux layout functions
Because Tmux is programmable, we can use functions to create layouts. Omarchy ships with three different functions for common developer layouts.
Because Tmux is programmable, we can use functions to create layouts. Omarchy ships with four different functions for common developer layouts.
`tdl [agent]` starts a three-way split IDE-like interface with the `$EDITOR` on the left, your chosen AI agent on the right (like `c` for opencode or `cx` for Claude or `codex` for OpenAI), and then a terminal at the bottom.
@@ -28,7 +28,9 @@ You can also start a second agent with `tdl c cx` (opencode + claude) (or just `
![tmux-tdl2-x.png](https://learn.omacom.io/u/tmux-tdl2-x-5FoPqh.png)
You can also start this layout configuration for every subdirectory in the current directory using `tdlm [agent]`, then navigate using `alt + 1/2/3/5/6/...`:
There's also `tds`, which starts a four-way square with the editor top left, a live diff watcher top right, a terminal bottom left, and opencode bottom right.
You can also start this layout configuration for every subdirectory in the current directory using `tdlm [agent]`, then navigate using `alt + 1/2/3/4/5/...`:
![tdlm-x.png](https://learn.omacom.io/u/tdlm-x-RPg6sr.png)
manual/12-neovim.md
+2 -2
View File
@@ -6,7 +6,7 @@ If you're totally new to vim-style editing, I recommend you checkout [ThePrimeag
Now Neovim is basically infinitely configurable. If you really want to go nuts, you can create your own Neovim configuration from scratch. There's a great course from [Typecraft on setting up Neovim from scratch](https://www.youtube.com/watch?v=zHTeCSVAFNY). And [ThePrimegean has one as well](https://www.youtube.com/watch?v=w7i4amO_zaE).
But Omarchy ships with a complete Neovim setup that's been lovingly tuned to showcase the best of what's possible out of the box. Without you having to write a single line of configuration! It's called [LazyVim](https://www.lazyvim.org/), and it's a distribution of Neovim plugins and configurations. It's awesome.
But Omarchy ships with a complete Neovim setup — the `omarchy-nvim` package — that's been lovingly tuned to showcase the best of what's possible out of the box. Without you having to write a single line of configuration! It's built on [LazyVim](https://www.lazyvim.org/), a distribution of Neovim plugins and configurations. It's awesome.
## LazyVim Basics
@@ -35,7 +35,7 @@ You can see all the possible commands on [the LazyVim Keymaps page](https://www.
## Starting Neovim
You can start Neovim using `Super + Shift + N`, but it's usually easier to drive it from the terminal by navigating to the directory you wish to work in and typing `n`. The `n` is the alias for `nvim`, which will use the the present directory to open by default. You can open a single file with `n myfile.txt`.
You can start Neovim using `Super + Shift + N` (the binding launches your default editor, which is Neovim out of the box), but it's usually easier to drive it from the terminal by navigating to the directory you wish to work in and typing `n`. The `n` is the alias for `nvim`, which will use the the present directory to open by default. You can open a single file with `n myfile.txt`.
## Using Neovim for sudo edits
manual/13-ai.md
+29 -12
View File
@@ -1,21 +1,38 @@
# AI
Omarchy ships with [OpenCode](https://opencode.ai/) and [Claude Code](https://code.claude.com/docs/en/overview) as the default agent harnesses for programmers. OpenCode lets you use models from all the major commercial providers as well as the rapidly improving open-weight models.
Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a favorite for you. Instead, every major coding-agent CLI comes pre-wired as a lazy-loaded launcher. The launchers are tiny [mise](https://mise.jdx.dev/)-managed stubs in `~/.local/bin/`, so nothing is downloaded until the first time you actually run one. Invoke any of these and authenticate when prompted:
The best way to use OpenCode is by going to the directory you're going to work on in the terminal, then invoke the `c` alias to start OpenCode within that directory. Claude Code let's you use Anthropic's models with their proprietary subscriptions, and can be started in danger mode using the `cx` alias.
| Command | Agent |
|------------|------------------------------------------------------------------|
| `claude` | [Claude Code](https://code.claude.com/docs/en/overview) |
| `codex` | [OpenAI Codex](https://github.com/openai/codex) |
| `opencode` | [OpenCode](https://opencode.ai/) |
| `gemini` | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) |
| `copilot` | [GitHub Copilot CLI](https://github.com/github/copilot-cli) |
| `crush` | [Crush](https://github.com/charmbracelet/crush) |
| `grok` | Grok CLI from xAI |
| `pi` | [Mario Zechner's Pi](https://github.com/badlogic/pi-mono) |
| `omp` | [Oh My Pi](https://github.com/can1357/oh-my-pi) |
### Alternative agent CLIs
To wrap an additional CLI the same way, run `omarchy-mise-install <package> [command-name]`. The stubs are kept current along with everything else mise manages when you run `omarchy update` (or the `mup` alias).
Beyond the default `c` (OpenCode) and `cx` (Claude Code) aliases, Omarchy ships pre-wired lazy-loaded launchers for every major coding-agent CLI. The launchers themselves are tiny shell stubs in `~/.local/bin/`, so on first run, each one fetches its npm package through npx against a mise-managed node@latest, so nothing is downloaded until you actually invoke it. Run any of these and authenticate when prompted:
### The default agent
| Command | Package | Provider |
|----------|-------------------------------|---------------------------------------|
| `codex` | @openai/codex | [OpenAI Codex](https://github.com/openai/codex) |
| `gemini` | @google/gemini-cli | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) |
| `copilot` | @github/copilot | [GitHub Copilot CLI](https://github.com/github/copilot-cli) |
| `pi` | @mariozechner/pi-coding-agent | [Mario Zechner's Pi](https://github.com/badlogic/pi-mono) |
Pick your default agent with `omarchy default agent <name>` or under _Setup > Defaults > Agent_ in the Omarchy Menu (`Super + Space`). If the agent isn't installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.
To wrap an additional npm-published CLI the same way, run `omarchy-npx-install <package> [command-name]`.
Once you've chosen, `Super + Shift + Ctrl + A` launches the default agent in a dedicated terminal window (or brings up the picker if you haven't chosen yet). You can also launch it straight into a task with `omarchy agent prompt "Review this project"`. Agents launched this way run unattended in their respective don't-stop-to-ask modes, so be ready for them to actually do things! And since agents refuse to remember trust for your home directory, launches from `$HOME` start in `~/Work` instead.
There are terminal shortcuts too: `a` runs the default agent inline in the current terminal, while `c`, `cx`, and `cy` start OpenCode, Claude Code, and Codex directly (again in their auto-approving modes). Theme changes sync to the agents as well: Claude Code, Pi, and OpenCode all follow along when you switch the Omarchy theme.
### The agents panel
The top bar grows an agents icon the first time Omarchy finds AI coding usage on the machine (and stays out of the way until then). The panel behind it tracks every subscription in one place: your plan, the percentage used of the 5-hour session and weekly limits (or the remaining prepaid balance), and token usage by day and by model. Claude Code, Codex, and Fireworks are covered out of the box.
Left-click the bar icon for the panel, right-click to launch your default agent. The usage records behind it are regenerated every 15 minutes by `omarchy agent usage-update`, and the panel can even merge usage from your other machines via a synced folder. See the README under `$OMARCHY_PATH/shell/plugins/agents/` for the full settings.
### Crash diagnosis
Omarchy watches systemd-coredump for process crashes. When something segfaults, you'll get a "Process crashed" notification — click it, and the crash is handed to your default agent along with Omarchy's diagnose-crash skill, which walks the agent through establishing the facts from the core dump and deciding whether the crash is worth reporting upstream. You can also run it by hand against any PID from `coredumpctl list` with `omarchy agent crash <pid>`.
### Local LLMs
@@ -23,6 +40,6 @@ Omarchy recommends two ways of running local LLM models: LM Studio and Ollama. L
### The Omarchy Skill
Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like making changes to waybar or even creating a new theme from scratch. It's automatically configured in OpenCode (and Claude Code and any other harness that supports `~/.claude/skills`).
Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like tweaking your Hyprland config, adjusting the bar, or even creating a new theme from scratch. It's symlinked into the skill directories for Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), Pi (`~/.pi/agent/skills`), and the generic `~/.agents/skills` location, so most harnesses pick it up automatically.
But you should treat this skill as experimental. Different models will use it to different effect. It's best to run in plan mode first, so you have an idea of what the agent would like to change. And then be ready to rollback changes or even invoking `omarchy reinstall configs`, if the agent makes a mess of everything.
manual/14-development-tools.md
+5 -5
View File
@@ -2,15 +2,15 @@
## Alternative Editors
Omarchy ships with [Neovim](https://neovim.io/) by default, but if you'd like something a bit more mainstream and familiar, you can run the Omarchy Menu (`Super + Alt + Space`) and see the options under _Install > Editor_. We have VSCode, Cursor, Zed, Sublime Text, and Helix listed there. If you don't find what you're looking for, checkout _Install > Package_, and see if it isn't in an Arch package (and if not, try _Install > AUR_ to check the AUR).
Omarchy ships with [Neovim](https://neovim.io/) by default, but if you'd like something a bit more mainstream and familiar, you can run the Omarchy Menu (`Super + Space`) and see the options under _Install > Editor_. We have VSCode, Cursor, Zed, Sublime Text, Helix, Vim, and Emacs listed there. If you don't find what you're looking for, checkout _Install > Package_, and see if it isn't in an Arch package (and if not, try _Install > AUR_ to check the AUR).
Theme matching is offered for `VSCode`, `Cursor`, `VSCodium`, `Helix`, and `Zed`.
Theme matching is offered for `VSCode`, `Cursor`, `VSCodium`, and `Helix`.
You can set the system-wide default editor under `Setup > Defaults > Editor`.
## Environment
Omarchy supports setting up a whole host of development environments through the _Install > Development_ section of the Omarchy Menu (`Super + Alt + Space`). You'll of course find _Ruby on Rails_, but also all three major runtimes for JavaScript (Node.js, bun, Deno), as well as popular PHP frameworks like Laravel and Symfony. Oh, and there's .NET, OCamal, Zig, and Elixir too. It's a very broad selection!
Omarchy supports setting up a whole host of development environments through the _Install > Development_ section of the Omarchy Menu (`Super + Space`). You'll of course find _Ruby on Rails_, but also all three major runtimes for JavaScript (Node.js, Bun, Deno), as well as popular PHP frameworks like Laravel and Symfony. Oh, and there's Go, Rust, Python, Java, Elixir (with Phoenix), .NET, OCaml, Zig, Clojure, and Scala too. It's a very broad selection!
The majority of these environments are managed by [Mise](https://mise.jdx.dev/). It's a tool that lets you install and run multiple versions of a programming language on the same machine. It's like rbenv or rvm for Ruby or virtualenv for Python, but it works for a bunch of different environments.
@@ -26,8 +26,8 @@ You can setup the common databases for local development in Docker using _Instal
## GitHub CLI
[The GitHub CLI](https://cli.github.com/) let's you authenticate with your GitHub account and clone private repositories using it. To authenticate, run `gh auth login`. Then you can checkout private repositories using `gh repo clone org/repo`.
[The GitHub CLI](https://cli.github.com/) let's you authenticate with your GitHub account and clone private repositories using it. It's wired up as one of the lazy-loading mise stubs, so the first time you run `gh`, it installs itself. To authenticate, run `gh auth login`. Then you can checkout private repositories using `gh repo clone org/repo`.
You can also perform a bunch of other GitHub operations using this command. Just run `gh` to see everything that's possible.
There's a lazy-installing stub for `ghui` for managing your pull requests in a TUI too.
There's a lazy-installing stub for `ghui` for managing your pull requests in a TUI too. And [lazygit](https://github.com/jesseduffield/lazygit) is preinstalled, if you'd like to drive git itself from a TUI as well.
manual/15-shell-tools.md
+1 -1
View File
@@ -14,7 +14,7 @@ The full manual can be found via `man fzf`.
## Zoxide
[Zoxide](https://github.com/ajeetdsouza/zoxide) is a replacement for cd. It remembers the directories you've been in, so you can more easily jump to them next time. Say you do `cd ~/.local/share/omarchy` once. Next time, you can just do `cd omarchy` (or even just `cd oma`), and Zoxide will take you directly there.
[Zoxide](https://github.com/ajeetdsouza/zoxide) is a replacement for cd. It remembers the directories you've been in, so you can more easily jump to them next time. Say you do `cd ~/.config/omarchy` once. Next time, you can just do `cd omarchy` (or even just `cd oma`), and Zoxide will take you directly there.
The full manual can be found via `man zoxide`.
manual/16-shell-functions.md
+28 -2
View File
@@ -9,8 +9,30 @@ Omarchy comes with a set of shell functions to simplify common tasks and encapsu
## Drives
- `iso2sd [image.iso]`: Create a bootable drive on an SD card using the referenced iso file and picking the drive interactively.
- `format-drive`: Select an entire disk to format with a single exFAT partition (which works on Windows and macOS too). Be careful!
- `iso2sd [image.iso]`: Create a bootable drive on an SD card using the referenced iso file and picking the drive interactively.
- `format-drive [device] [name]`: Format an entire disk with a single exFAT partition (which works on Windows and macOS too). Run it without arguments to see the available drives. Be careful!
## Dev layouts
Instant multi-pane development layouts for tmux:
- `tdl [ai]`: Create a Tmux Dev Layout with your editor, an AI agent, and a terminal. Use the agent aliases, like `tdl c` for opencode or `tdl cx` for Claude Code, or pass a second agent to run both, like `tdl c cx`.
- `tds`: Create a Tmux Dev Square with editor, diff watching (via `hunk diff --watch`), terminal, and opencode.
- `tdlm [ai]`: Create a `tdl` window for every subdirectory in the current directory.
- `tsl [count] [command]`: Create a swarm of panes tiled in a grid, all running the same command (great for AI agents).
The same layouts are available for Herdr as `hdl`, `hds`, `hdlm`, and `hsl`.
## Git worktrees
- `ga [branch]`: Create a new worktree and branch next to the current repository and jump into it.
- `gd`: Remove the current worktree and its branch (asks for confirmation first).
## Rsync watchers
- `rsw [source] [destination]`: Start a background watcher that rsyncs source to destination whenever anything changes. The destination can be a remote host, like `rsw ~/Work/app nyc-dev:Work/app`.
- `lsw`: List all active watchers.
- `dsw`: Stop all active watchers.
## SSH Portforwarding
@@ -21,3 +43,7 @@ Ideal for doing web development with localhost secure-context privileges against
- `lip`: List all active SSH port forwards.
Say you start a dev server on port `3000` on a machine accessible as `nyc-dev`, then you can run `fip nyc-dev 3000` to forward that port, so `localhost:3000` actually reaches `nyc-dev:3000`, but without the need for SSL certificates to establish the secure context needed for testing web sockets or the like.
## SSH reconnection
`ssh` itself is wrapped in a function that cleans up the terminal if a connection dies while a remote tmux, Herdr, or editor has claimed it, and then automatically reconnects when an interactive session drops (Ctrl-C stops the retry loop).
manual/17-tuis.md
+14 -8
View File
@@ -20,22 +20,28 @@ You stop a container using `s` or start/restart it using `r`. See all commands u
[Btop](https://github.com/aristocratos/btop) is a beautiful resource manager that shows memory, CPU, disk, and network usage. It also lists all active processes, and allows you to manage them.
Omarchy has added an app for it called Activity, which you can start from the application launcher. But it's quicker to just hit `Super + Shift + T`.
Omarchy calls it Activity, and you start it by hitting `Super + Ctrl + T`. It opens as a floating window, which you can tile with `Super + T`.
## Impala
## Herdr
[Impala](https://github.com/pythops/impala) is a TUI for managing your Wi-Fi connection. You hop between sections on tab, then select a network with space. If a password is needed, just input and hit return. It's available by clicking the Wi-Fi icon in the top menu bar.
[Herdr](https://github.com/omacom-io/herdr) is a terminal workspace manager that gives you workspaces, tabs, and panes, and keeps them all running in a persistent session you can detach from and come back to later.
## BlueTUI
[BlueTUI](https://github.com/pythops/bluetui) is a TUI for managing your Bluetooth connections. It's made by the same creator as Impala and works the same way.
You start it (or reattach to your existing session) with `Super + Ctrl + Return`. Omarchy ships a Herdr configuration that mirrors its Tmux config, so the prefix key is `Ctrl + Space` here too. You can browse all the keybindings with `Super + Ctrl + K`.
## Fastfetch
[Fastfetch](https://github.com/fastfetch-cli/fastfetch) shows system information, like kernel version, uptime, theme, CPU, memory, and more. It's a successor to the popular neofetch tool.
Omarchy has packaged this as _About_ in the Omarchy menu (`Super + Alt + Space`).
Omarchy has packaged this as _About_ in the Omarchy menu (`Super + Space`).
## Cliamp
[Cliamp](https://www.cliamp.stream/) is a retro terminal music player inspired by Winamp 2.x," letting you play built-in radio stations for low-fi Launch it with `Super + Shift + Alt + M`, or from the Omarchy menu under _Apps_. Press `?` for the full keybinding list.
[Cliamp](https://www.cliamp.stream/) is a retro terminal music player inspired by Winamp 2.x, complete with built-in radio stations for lo-fi beats. Launch it with `Super + Shift + Alt + M`, or from the Omarchy menu under _Apps_. Press `?` for the full keybinding list.
## What about Wi-Fi and Bluetooth?
You won't find TUIs for Wi-Fi and Bluetooth — those jobs belong to the Omarchy shell. Click the Wi-Fi icon in the top bar (or hit `Super + Ctrl + W`) to see networks and connect, and click the Bluetooth icon (or hit `Super + Ctrl + B`) to pair and connect devices. Networking itself is handled by NetworkManager, and there are `omarchy network` and `omarchy bluetooth` commands if you prefer the terminal.
## Adding your own
Any terminal program can get the full app treatment. Go to _Install > TUI_ in the Omarchy menu (`Super + Space`), give it a name, a launch command, a window style, and an icon, and it'll show up in the app launcher like any other application. You can remove it again under _Remove > TUI_.
manual/18-guis.md
+25 -1
View File
@@ -10,12 +10,24 @@ Obsidian also offers a [commercial add-on for syncing](https://obsidian.md/sync)
You start Obsidian with `Super + Shift + O`. To use theme syncing, you must select the `Omarchy` theme under settings.
## Omawrite
[Omawrite](https://github.com/omacom-io/omawrite) is Omarchy's own dead-simple Markdown writing app. No vaults, no plugins, just you and the words.
You start Omawrite with `Super + Shift + W`.
## Pinta
[Pinta](https://www.pinta-project.com/) is a basic image editing tool that's great for cropping, resizing, and other basic manipulations. Just don't expect a Photoshop alternative. But it's still got a Magic Wand and layers!
You start Pinta via the application launcher (`Super + Space`).
## Aether
[Aether](https://github.com/bjarneo/aether) is a theming application that can extract colors from a background image and turn them into a complete, cohesive theme. It's the easiest way to [make your own theme](37-making-your-own-theme.md).
You start Aether via the application launcher (`Super + Space`).
## LocalSend
[LocalSend](https://localsend.org/) lets you send files to other devices on the same network running the app, like Apple's AirDrop. It's cross-platform, though, so you can send files to and from Windows, macOS, Android, iOS, and of course Linux.
@@ -28,11 +40,17 @@ You can open the LocalSend menu on `Super + Ctrl + S` or under _Trigger > Share_
You start LibreOffice via the application launcher (`Super + Space`).
## Omacalc
[Omacalc](https://github.com/omacom-io/omacalc) is Omarchy's own dead-simple calculator, which opens in a floating window.
You start Omacalc with `Super + Ctrl + Q` (or the calculator key, if your keyboard has one).
## Signal
[Signal](https://signal.org/) is the pioneer of E2E encrypted messaging, and a great communication option for anyone who'd prefer not to go through one of the big tech conglomerates.
You start Signal with `Super + Shift + G`.
You start Signal with `Super + Shift + G`. It's not part of the base install, so the first time you hit that, Omarchy will offer to install it for you (it's also under _Install > Service_ in the Omarchy menu).
## mpv
@@ -51,3 +69,9 @@ You start OBS Studio via the application launcher (`Super + Space`).
[Kdenlive](https://kdenlive.org/) is an excellent video editor. Perfect for working on video that comes out of OBS Studio before sharing it.
You start Kdenlive via the application launcher (`Super + Space`).
## Omacut
[Omacut](https://github.com/omacom-io/omacut) is Omarchy's own dead-simple video trimmer. When all you need is to cut the start and end off a clip, it beats firing up a full video editor.
You start Omacut via the application launcher (`Super + Space`).
manual/19-commercial-apps-services.md
+6 -14
View File
@@ -6,32 +6,24 @@ Omarchy is mostly focused on providing free, open source software, but it's not
Keeping your passwords in a password manager is a best practice. Doubly so if you're working with a team. And [1password](https://1password.com/) is a great solution, which also comes with a command line tool for integrating key lookups in scripts.
You start 1Password with `Super + Shift + /`.
## Typora
[Typora](https://typora.io/) is a minimal, distraction-free writing tool in the same spirit as iA Writer for the Mac and Windows. Like Obsidian, it uses Markdown for formatting, but in a way that's focused on writing individual pieces or essays and very little else.
Best used in full screen mode (F11) for that totally immersive nothing-but-words look.
It comes with a 15-day free trial, and is then a $15 one-time cost.
You start Typora using `Super + Shift + W`.
You start 1Password with `Super + Shift + /`. If it isn't installed yet, that hotkey kicks off the installation first (you can also use _Install > Service > 1Password_ from the Omarchy menu). The installer sets up the 1Password extension for Chromium as well.
## Spotify
[Spotify](https://spotify.com/) is the world's most popular streaming music service. And the Linux application provides everything you'd expect, including offline playing.
You start Spotify using `Super + Shift + M`.
You start Spotify using `Super + Shift + M`. Like 1Password, the hotkey kicks off the installation first if Spotify isn't installed yet (or use _Install > Service > Spotify_ from the Omarchy menu).
## Dropbox
[Dropbox](https://www.dropbox.com/) is a great way to sync files between machines while keeping a backup in the cloud. To set it up, select _Install > Service > Dropbox_ from the Omarchy menu.
[Dropbox](https://www.dropbox.com/) is a great way to sync files between machines while keeping a backup in the cloud. To set it up, select _Install > Service > Dropbox_ from the Omarchy menu. Once it's running, hover the tray in the top right of the bar and right-click the Dropbox icon to finish the setup.
## Tailscale
[Tailscale](https://tailscale.com/) is a mesh VPN that makes getting access to all your computers and servers over the internet securely super simple way. To set it up, select _Install > Service > Tailscale_ from the Omarchy menu.
Installing it also puts a Tailscale indicator in the bar, adds a web app for the Tailscale admin console, and sets up Taildrop. That means you can send files between your machines with `omarchy tailscale send <machine> <file>`, and incoming files automatically land in `~/Downloads`.
## NordVPN
[NordVPN](https://nordvpn.com/) is a standard VPN service that lets you exit your traffic from most regions around the world. To set it up, select _Install > Service > NordVPN_ from the Omarchy menu.
[NordVPN](https://nordvpn.com/) is a standard VPN service that lets you exit your traffic from most regions around the world. To set it up, select _Install > Service > NordVPN_ from the Omarchy menu. After the reboot it asks for, run `nordvpn login` to authenticate.
manual/20-web-apps.md
+23 -5
View File
@@ -1,6 +1,6 @@
# Web Apps
You can add your own web apps using _Install > Web App_ in the Omarchy menu (`Super + Alt + Space`). It'll ask you for the app name, app URL, and the icon URL, if it can't retrieve it via favicon. You can get great PNG icons for many popular web apps on [Dashboard Icons](https://dashboardicons.com).
You can add your own web apps using _Install > Web App_ in the Omarchy menu (`Super + Space`). It'll ask you for the app name, app URL, and the icon URL, if it can't retrieve it via favicon. You can get great PNG icons for many popular web apps on [Dashboard Icons](https://dashboardicons.com).
They'll then be accessible through the app launcher (`Super + Space`), and use the beautiful frameless web-app window.
@@ -8,7 +8,7 @@ If you wish to remove a web app, just go to _Remove > Web App_ in the Omarchy me
It's best if you log into all your accounts using a regular browser before using the web app shortcuts. The thin wrapper frame doesn't work well with 1password, so just easier to be logged in directly first.
All the keyboard hotkeys for these web apps can be changed in `~/.config/hypr/bindings.conf`.
All the keyboard hotkeys for these web apps can be changed in `~/.config/hypr/bindings.lua`.
When you're in a web app, you can copy the current URL to the clipboard using `Shift + Alt + L`.
@@ -18,7 +18,7 @@ By default, Omarchy already ships with an assortment of default apps:
[HEY](https://www.hey.com/) is an email and calendar service that serves as a great alternative to people tired of Gmail, Outlook, or Apple Mail. It's made by [37signals](https://37signals.com/) where Omarchy originated.
You can start HEY Email using `Super + Shift + E` and HEY Calendar using `Super + Shift + C`.
You can start HEY Email using `Super + Shift + E`, jump straight to composing a new email using `Super + Shift + Alt + E`, and start HEY Calendar using `Super + Shift + C`.
## Basecamp
@@ -32,11 +32,23 @@ You can start Basecamp using the application launcher (`Super + Space`)
You can start ChatGPT using `Super + Shift + A`.
## Grok
[Grok](https://grok.com) is xAI's chat bot.
You can start Grok using `Super + Shift + Alt + A`.
## WhatsApp
[WhatsApp](https://www.whatsapp.com/) is one of the most popular messaging services in the world, and the web version is a great option for Linux.
You can start WhatsApp using `Super + Ctrl + G`.
You can start WhatsApp using `Super + Shift + Alt + G`.
## Google apps
Google Messages, Google Photos, Google Maps, and Google Contacts are all included as web apps too.
You can start Google Messages using `Super + Shift + Ctrl + G`, Google Photos using `Super + Shift + P`, and Google Maps using `Super + Shift + S`. Google Contacts is available through the app launcher (`Super + Space`).
## X
@@ -52,6 +64,12 @@ You can start YouTube using `Super + Shift + Y`.
## Zoom
[Zoom](https://zoom.us/) is the most popular video chat system used in the US. Great connections across the world. And 40-minute meetings can be held without a paying account.
[Zoom](https://zoom.us/) is the most popular video chat system used in the US. Great connections across the world. And 40-minute meetings can be held without a paying account. Omarchy wraps Zoom's web client, and zoom meeting links will open straight into it.
You start Zoom using the application launcher (`Super + Space`).
## Discord
[Discord](https://discord.com/) is where most gaming and open source communities hang out, including [Omarchy's own](https://discord.gg/tXFUdasqhY).
You start Discord using the application launcher (`Super + Space`).
manual/21-gaming.md
+23 -15
View File
@@ -1,14 +1,14 @@
# Gaming
Omarchy isn't just for _pRoDUcTiVItY_, it's also for having fun, and what's more fun than gaming? Omarchy ships with a whole suite of gaming options — Steam and RetroArch for native and retro play, Lutris and Heroic for non-Steam stores, Moonlight for PC streaming, Xbox Cloud Gaming + NVIDIA GeForce NOW for cloud, plus the evergreen Minecraft.
Omarchy isn't just for _pRoDUcTiVItY_, it's also for having fun, and what's more fun than gaming? Omarchy ships with a whole suite of gaming options — Steam and RetroArch for native and retro play, Battle.net, Lutris, and Heroic for non-Steam stores, Moonlight for PC streaming, Xbox Cloud Gaming + NVIDIA GeForce NOW for cloud, plus the evergreen Minecraft.
Thanks to Valve's incredible work on [the proton compatibility layer](https://en.wikipedia.org/wiki/Proton_(software)), there are now tens of thousands of playable modern games on Linux. Oh, and did you know that the [Steam Deck](https://store.steampowered.com/steamdeck/) actually runs Arch!
All gaming installers live under _Install > Gaming_ in the Omarchy menu (`Super + Alt + Space`). If you ever want to undo one, use _Install > Gaming > Remove_.
All gaming installers live under _Install > Gaming_ in the Omarchy menu (`Super + Space`). If you ever want to undo one, use _Remove > Gaming_.
## Steam
Install [Steam](https://store.steampowered.com/) by selecting _Install > Gaming > Steam_ from the Omarchy menu (`Super + Alt + Space`).
Install [Steam](https://store.steampowered.com/) by selecting _Install > Gaming > Steam_ from the Omarchy menu (`Super + Space`).
After you've installed it, you'll be able to launch Steam with `Super + Space`.
@@ -18,21 +18,23 @@ Note that Steam can take 10-20 seconds to start up, and it's not going to provid
## RetroArch
Install [RetroArch](https://www.retroarch.com/) by selecting _Install > Gaming > RetroArch_ from the Omarchy menu (`Super + Alt + Space`).
Install [RetroArch](https://www.retroarch.com/) by selecting _Install > Gaming > RetroArch_ from the Omarchy menu (`Super + Space`). It comes with the full set of libretro cores, so all the classic systems are covered.
RetroArch is fully preconfigured with the beautiful CRT Royale shader for that perfect retro look.
To get going:
1. Drop your BIOS and ROM files into `~/Games`.
1. Drop your BIOS files into `~/Games/bios` and your ROMs into `~/Games/roms`.
2. Launch RetroArch with `Super + Space` and typing `retro`.
3. Scan the `~/Games` directory and you're ready to play.
3. Scan the `~/Games/roms` directory and you're ready to play.
You can also give a favorite game its own entry in the app launcher with _Install > Gaming > RetroArch Game Launcher_, which lets you pick a core and a ROM, and jump straight into the game from `Super + Space`.
![retroarch.jpg](https://learn.omacom.io/u/retroarch-wd6cuZ.jpg)
## Xbox Cloud Gaming
Install the Xbox Cloud Gaming web app by selecting _Install > Gaming > Xbox Cloud Gaming_ from the Omarchy menu (`Super + Alt + Space`). It's "just" a web app for the service, but it's quick to start and runs great at 1080p.
Install the Xbox Cloud Gaming web app by selecting _Install > Gaming > Xbox Cloud Gaming_ from the Omarchy menu (`Super + Space`). It's "just" a web app for the service, but it's quick to start and runs great at 1080p.
If you already have Xbox Game Pass, this is a solid way to play Fortnite and other titles you can't run natively on Linux.
@@ -40,13 +42,13 @@ If you already have Xbox Game Pass, this is a solid way to play Fortnite and oth
## NVIDIA GeForce Now
Install the cloud-gaming service [NVIDIA GeForce NOW](https://www.nvidia.com/en-us/geforce-now/) by selecting _Install > Gaming > NVIDIA GeForce Now_ from the Omarchy menu (`Super + Alt + Space`). Another great way to play titles that aren't available natively on Linux.
Install the cloud-gaming service [NVIDIA GeForce NOW](https://www.nvidia.com/en-us/geforce-now/) by selecting _Install > Gaming > NVIDIA GeForce NOW_ from the Omarchy menu (`Super + Space`). Another great way to play titles that aren't available natively on Linux.
![screenshot-2026-05-05_09-00-11-medium.jpg](https://learn.omacom.io/u/screenshot-2026-05-05_09-00-11-medium-tSjM9x.jpg)
## Minecraft
Install Minecraft by selecting _Install > Gaming > Minecraft_ from the Omarchy menu (`Super + Alt + Space`).
Install Minecraft by selecting _Install > Gaming > Minecraft_ from the Omarchy menu (`Super + Space`).
Like Steam, note that it can take a while after logging in or starting up for the next screen to appear, and you're not going to get any feedback while you're waiting.
@@ -54,24 +56,30 @@ Like Steam, note that it can take a while after logging in or starting up for th
## Xbox Controllers
Install support for Bluetooth Xbox controllers by selecting _Install > Xbox Controllers_ from the Omarchy menu (`Super + Alt + Space`). Pair the controllers via Bluetooth and they'll work in all your games. You don't need this if you're just hardwiring your controller with a USB-C cable.
Install support for Bluetooth Xbox controllers by selecting _Install > Gaming > Xbox Controllers_ from the Omarchy menu (`Super + Space`). Pair the controllers via Bluetooth (`Super + Ctrl + B`) and they'll work in all your games. You don't need this if you're just hardwiring your controller with a USB-C cable.
## Moonlight (Game streaming from a PC)
Install the [Moonlight client](https://github.com/moonlight-stream/moonlight-qt) by selecting _Install > Gaming > Moonlight_ from the Omarchy menu (`Super + Alt + Space`). Moonlight streams games from a Windows PC running [Sunshine](https://app.lizardbyte.dev/Sunshine/).
The [Moonlight client](https://github.com/moonlight-stream/moonlight-qt) comes preinstalled with Omarchy, so you can stream games from a Windows PC running [Sunshine](https://app.lizardbyte.dev/Sunshine/) right away. Launch Moonlight via `Super + Space`.
If both your Omarchy machine and the remote gaming PC are hardwired, the experience is indistinguishable from playing locally. Crank the resolution up to native, set the refresh to 120Hz, and max the bitrate — this is the best way to play competitive shooters like Fortnite on Linux.
## Lutris (Battle.net games)
You can also turn an Omarchy machine into the host by running `omarchy install service sunshine`, which installs Sunshine and opens the Moonlight streaming ports for your LAN and Tailscale.
Install [Lutris](https://lutris.net/) by selecting _Install > Gaming > Lutris_ from the Omarchy menu (`Super + Alt + Space`). Lutris is the way to play [Battle.net](https://eu.shop.battle.net/en-us) titles like Diablo, Starcraft, and World of Warcraft on Linux.
## Battle.net
Installation is a little janky and looks like nothing is happening at times — just be patient, it's working in the background.
Install [Battle.net](https://eu.shop.battle.net/en-us) by selecting _Install > Gaming > Battle.net_ from the Omarchy menu (`Super + Space`). This gives you titles like Diablo, Starcraft, and World of Warcraft as a standalone install running under GE-Proton — no Steam, Lutris, or Heroic needed.
![starcraft.png](https://learn.omacom.io/u/starcraft-WU9zw7.png)
## Lutris (Windows games)
Install [Lutris](https://lutris.net/) by selecting _Install > Gaming > Lutris_ from the Omarchy menu (`Super + Space`). Lutris is the way to play Windows games from stores like EA and Ubisoft Connect that don't have their own installer above.
Installation is a little janky and looks like nothing is happening at times — just be patient, it's working in the background.
## Heroic Launcher (Epic Games)
Install the [Heroic Launcher](https://heroicgameslauncher.com/) by selecting _Install > Gaming > Heroic Launcher_ from the Omarchy menu (`Super + Alt + Space`). Heroic lets you run Epic Games titles, like OddSparks, that don't rely on anti-cheat. Sadly, that means no Fortnite and no Rocket League — until Tim Sweeney comes to Linux, this is as close as it gets.
Install the [Heroic Launcher](https://heroicgameslauncher.com/) by selecting _Install > Gaming > Heroic (Epic Games)_ from the Omarchy menu (`Super + Space`). Heroic lets you run Epic Games titles, like OddSparks, that don't rely on anti-cheat — plus games from GOG and Amazon Prime Gaming. Sadly, that means no Fortnite and no Rocket League — until Tim Sweeney comes to Linux, this is as close as it gets.
Like Lutris, it can feel slow and janky while installing games. Give it time.
manual/23-windows-vm.md
+2 -2
View File
@@ -1,8 +1,8 @@
# Windows VM
Omarchy offers an easy way to run Windows through a Docker VM. You can install it using _Install > Windows_ from the Omarchy menu (`Super + Alt + Space`). It takes a while, but you can follow the progress in the browser.
Omarchy offers an easy way to run Windows through a Docker VM. You can install it using _Install > Windows_ from the Omarchy menu (`Super + Space`). It takes a while, but you can follow the progress in the browser.
When the installation is complete, you can launch Windows using the app launcher, and that'll give you a RDP connection to your installation. There's no GPU passthrough with this setup, so it's not suitable for gaming or video editing, but it's a great way to run apps like Microsoft Office or whatever else if you absolutely must have that.
When the installation is complete, you can launch Windows using the app launcher, and that'll give you a RDP connection to your installation. When you close the RDP session, the VM automatically stops again. If you want to get rid of the whole thing, use _Remove > Windows_ from the Omarchy menu. There's no GPU passthrough with this setup, so it's not suitable for gaming or video editing, but it's a great way to run apps like Microsoft Office or whatever else if you absolutely must have that.
The directory `~/Windows` in your home directory is automatically shared with this Windows VM. So you put files there if you want to make them accessible to Windows. The VM does not have access to any other files on your system, so you're safe from malware or viruses on the Linux side.
manual/24-other-packages.md
+1 -1
View File
@@ -2,7 +2,7 @@
Arch has an amazing wealth of packages available for almost any type of software between the official repository and the Arch User Repository (AUR).
It couldn't be easier to use either. You install a new Arch package by going to _Install > Package_ in the Omarchy menu (`Super + Alt + Space`) and typing the package you want. It'll automatically fuzzy filter the list of all packages. (You can also do it manually using with `omarchy pkg add [package]` in the terminal).
It couldn't be easier to use either. You install a new Arch package by going to _Install > Package_ in the Omarchy menu (`Super + Space`) and typing the package you want. It'll automatically fuzzy filter the list of all packages. (You can also do it manually using `omarchy pkg add [package]` in the terminal).
You can do the same with AUR, just use _Install > AUR_. Just remember that the AUR isn't vetted by the Arch team. It's like RubyGems or npm. Anyone can upload.
manual/25-updates.md
+7 -7
View File
@@ -1,8 +1,8 @@
# Updates
Omarchy and your packages are kept up to date via _Update > Omarchy_ in the Omarchy menu (`Super + Alt + Space`).
Omarchy and your packages are kept up to date via _Update > Omarchy_ in the Omarchy menu (`Super + Space`).
This pulls [the latest Omarchy code and configs](https://github.com/basecamp/omarchy/releases), runs any pending migrations to get your system in sync with the latest, and updates all system packages from the [Omarchy Arch Mirror](https://github.com/omacom-io/omarchy-mirror), [Omarchy Package Repository](https://github.com/omacom-io/omarchy-pkgs), and [AUR](https://aur.archlinux.org/) (if you have installed any AUR packages).
Omarchy itself is installed as regular pacman packages from the [Omarchy Package Repository](https://github.com/omacom-io/omarchy-pkgs), so an update installs [the latest Omarchy release](https://github.com/basecamp/omarchy/releases), runs any pending migrations to get your system in sync with the latest, and updates all system packages from the [Omarchy Arch Mirror](https://github.com/omacom-io/omarchy-mirror) and [AUR](https://aur.archlinux.org/) (if you have installed any AUR packages).
When new releases are made, a circle arrow icon will appear to the right of your clock. Click it and the update process will start.
@@ -12,17 +12,17 @@ When new releases are made, a circle arrow icon will appear to the right of your
Omarchy is updated along four channels: stable, RC, edge, and dev. New installations start on the stable channel, which tracks the [official releases](https://github.com/basecamp/omarchy/releases/), as well as the [stable Omarchy Arch mirror](https://github.com/omacom-io/omarchy-mirror) that's running one month behind the latest, so we can catch any new incompatibilities that require config changes before they cause problems for people.
But if you'd like to help spot those potential issues, you can run on the edge channel. That'll keep your Omarchy code tracking official releases, but lets you update to the latest Arch packages as soon as they're available. You should only do this if you're experienced with Linux, and know how to recover a system that has problems.
But if you'd like to help spot those potential issues, you can run on the edge channel. That'll keep your Omarchy packages tracking the latest development builds, and lets you update to the latest Arch packages as soon as they're available. You should only do this if you're experienced with Linux, and know how to recover a system that has problems.
Before any new major release, we'll be doing final validation using the RC channel. If you're interested in helping with final polishing, come hang out in #omarchy-release-candidates on the Discord.
Finally, there's the dev channel, which gives you the very latest Omarchy code changes and the edge packages. You should only use this channel if you're an experienced Linux user, working directly on Omarchy, and willing to tolerate breakage.
Finally, there's the dev channel, which links Omarchy directly to a git checkout of the source code in `~/omarchy`, combined with the edge packages. You should only use this channel if you're an experienced Linux user, working directly on Omarchy, and willing to tolerate breakage.
You can switch between channels using _Update > Channel_ from the Omarchy menu.
You can switch between channels using _Update > Channel_ from the Omarchy menu (or `omarchy-channel-set` in the terminal).
### Warning about direct pacman/yay updates
If you're already familiar with Arch, you might be tempted to just run `pacman -Syu` or `yay -Syu` yourself, but if you do that, you run the risk that you'll miss updates to the configuration files needed to support newer versions of libraries or tools. So it's best to stick with `Update > Omarchy`, so you're sure that any migrations are run together with new packages.
If you're already familiar with Arch, you might be tempted to just run `pacman -Syu` or `yay -Syu` yourself, but if you do that, you'll miss the snapshot, migrations, and configuration updates that Omarchy runs together with new packages. That's why Omarchy will actually stop a direct system upgrade and point you to `omarchy update` instead. (If you really know what you're doing, the guard will tell you how to bypass it for a single transaction.)
### Rolling back bad updates
@@ -30,4 +30,4 @@ If you ever have a problem after doing an update, you can rollback your system t
![omarchy-bootloader.png](https://learn.omacom.io/u/omarchy-bootloader-EVTCUU.png)
If somehow your configuration files have been corrupted, you can also perform an Omarchy reinstall using `omarchy reinstall` in the terminal. This will restore your Omarchy installation to the latest release, put you on stable and downgrade any packages, and reset all the configuration files. Note that all your user config changes to the Omarchy defaults will be overwritten doing this!
If somehow your configuration files have been corrupted, you can also perform an Omarchy reinstall using `omarchy reinstall` in the terminal. This will reinstall all the default Omarchy packages, put you on stable and downgrade any packages that are too new, and reset all the configuration files. Note that all your user config changes to the Omarchy defaults will be overwritten doing this!
manual/26-dotfiles.md
+15 -15
View File
@@ -1,22 +1,21 @@
# Dotfiles
Omarchy is primarily configured through the so-called dotfiles that live in `~/.config`. Those are considered your files for your changes. The files that live in `~/.local/share/omarchy` belong to Omarchy itself, and you ideally shouldn't be messing with those. If you need to change anything in `~/.local/share/omarchy`, you should be overwriting the value in `~/.config` instead.
Omarchy is primarily configured through the so-called dotfiles that live in `~/.config`. Those are considered your files for your changes. The files that live in `/usr/share/omarchy` belong to Omarchy itself, and you shouldn't be messing with those. If you need to change anything in `/usr/share/omarchy`, you should be overwriting the value in `~/.config` instead.
Almost everything can be edited through _Setup > Configs > [process]_ through the Omarchy menu (`Super + Alt + Space`). When you do it this way, any process that needs restarting after config edits automatically will be after you quit the Neovim editor (`:wq`, remember!).
The key configs can be edited straight from the Omarchy menu (`Super + Space`), like _Setup > Monitors_, _Setup > Keybindings_, _Setup > Input_, and _Setup > Config > [file]_. When you do it this way, any process that needs restarting after config edits automatically will be after you quit the editor (Neovim by default — `:wq`, remember! — but you can change that via _Setup > Defaults > Editor_).
Here's a list of the key files in `~/.config` and what they control:
| File | Purpose |
| ----------------------- | --------------------- |
| `~/.config/hypr/hyprland.conf` | Controls keybindings, default apps, and everything Hyprland. [Learn more about Hyprland configs](https://wiki.hypr.land/Configuring/). |
| `~/.config/hypr/monitors.conf` | Controls your monitors, resolution, and position. |
| `~/.config/hypr/hypridle.conf` | Controls your idle/sleep settings. Shouldn't need touching. |
| `~/.config/hypr/hyprlock.conf` | Controls your lock screen, but this is symlinked to your theme for styling. |
| `~/.config/waybar/config.jsonc` | Controls your top bar that's run with waybar. [Learn more about Waybar configs](https://github.com/Alexays/Waybar/wiki/Configuration). |
| `~/.config/waybar/style.css` | Controls your top bar design, but it's symlinked to your theme. |
| `~/.config/walker/config.toml` | Controls your launcher that's run with Walker. |
| `~/.config/alacritty/alacritty.toml` | Controls your terminal. |
| `~/.config/uwsm/default` | Controls your default $EDITOR. Requires relaunching Hyprland when changed. |
| `~/.config/hypr/hyprland.lua` | The main Hyprland config. Loads the Omarchy defaults plus your override files below. [Learn more about Hyprland configs](https://wiki.hypr.land/Configuring/). |
| `~/.config/hypr/bindings.lua` | Your own keybindings and overrides of the defaults. |
| `~/.config/hypr/monitors.lua` | Controls your monitors, resolution, and position. |
| `~/.config/hypr/input.lua` | Controls your keyboard layout, mouse, and trackpad settings. |
| `~/.config/hypr/looknfeel.lua` | Controls gaps, borders, animations, and the rest of the look. |
| `~/.config/hypr/autostart.lua` | Controls extra processes started with the session. |
| `~/.config/omarchy/shell.json` | Controls the Omarchy shell: bar position, layout, and widgets, plus screensaver, lock, and idle timings. |
| `~/.config/foot/foot.ini` | Controls your terminal (foot is the default). |
| `~/.XCompose` | Defines your quick-access emoji and name/email autocomplete. Make sure to run `omarchy-restart-xcompose` after making changes. |
If you end up making a lot of changes to tweak your own setup, it's a good idea to backup all these dotfiles. [Stow is a great way to do that](https://www.youtube.com/watch?v=NoFiYOqnC4o).
@@ -27,15 +26,16 @@ Omarchy ships with a bunch of ergonomic aliases and helpful functions, but it's
### Changing internal Omarchy files
Look, this is your computer. You can do whatever you want with it, but I would advise against making changes to the files in `~/.local/share/omarchy` directly. It'll make it harder for you to upgrade in the future. You're better off just overwriting any default values you don't like in the `~/.config/*` folder instead.
Look, this is your computer. You can do whatever you want with it, but I would advise against making changes to the files in `/usr/share/omarchy` directly. They belong to the Omarchy pacman package, so your changes will simply be overwritten on the next update. You're better off just overwriting any default values you don't like in the `~/.config/*` folder instead.
You can change just about everything that way, like the default keybindings. Just edit `~/.config/hypr/hyprland.conf` to, say, replace [Obsidian](https://obsidian.md/) with [Joplin](https://joplinapp.org/) (install with `yay -S joplin-bin`):
You can change just about everything that way, like the default keybindings. Just edit `~/.config/hypr/bindings.lua` to, say, replace [Obsidian](https://obsidian.md/) with [Joplin](https://joplinapp.org/) (install with `omarchy-pkg-add joplin-bin`):
```
bind = SUPER SHIFT, O, exec, joplin
hl.unbind("SUPER + SHIFT + O")
o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop")
```
If you insist on changing internal Omarchy files, you'll need to commit your changes before you can use `omarchy update`. You can do that with `gcam "Look ma! I'm breaking the rules!"` from inside the `~/.local/share/omarchy` directory. Ain't nobody here to tell you what to do!
If you insist on hacking on the internal Omarchy files, switch to the dev channel via _Update > Channel > Dev_. That links Omarchy to a git checkout of the source code in `~/omarchy`, which you're free to change to your heart's content. Ain't nobody here to tell you what to do!
### Resetting any changes
manual/27-monitors.md
+12 -12
View File
@@ -2,23 +2,23 @@
Omarchy assumes you're running on a 2x-capable retina-class display by default. This is what you need to get those nice, crisp programmer fonts. It's what almost all new premium laptops with high-resolution screens are optimized for. It's what you'd want to run on a 27" 5K [Apple Studio Display](https://www.apple.com/studio-display/)/[ProArt PA27JCV](https://www.asus.com/us/displays-desktops/monitors/proart/proart-display-5k-pa27jcv/)/[Samsung S9](https://www.samsung.com/us/computing/monitors/5k/27-viewfinity-s9-5k-monitor-with-thunderbolt-4-matte-display-and-smart-features-ls27c900panxza/)/[Kuycon G27P](https://kuycon.us/monitors/G27P/) or 32" 6K [Apple XDR](https://www.apple.com/pro-display-xdr/)/[ProArt PA32QCV](https://www.asus.com/displays-desktops/monitors/proart/proart-display-6k-pa32qcv/)/[Kuycon G32P](https://kuycon.us/monitors/G32P/).
But if you're not running a display with a PPI of 218 or above, you'll want to change the monitor settings. For example, if you have a 27" or 32" 4K, you can use fractional scaling by opening `~/.config/hypr/monitors.conf` and switching to the recommendation for that combo:
But if you're not running a display with a PPI of 218 or above, you'll want to change the monitor settings. For example, if you have a 27" or 32" 4K, you can use fractional scaling by opening `~/.config/hypr/monitors.lua` (via _Setup > Monitors_ in the Omarchy menu) and switching to the recommendation for that combo:
```
env = GDK_SCALE,1.75
monitor=,preferred,auto,1.666667
```lua
local omarchy_gdk_scale = 2
local omarchy_monitor_scale = 1.6
```
If you're using a 1080p or 1440p display, you'll probably just want to use 1x scaling, so you can use:
```
env = GDK_SCALE,1
monitor=,preferred,auto,1
```lua
local omarchy_gdk_scale = 1
local omarchy_monitor_scale = 1
```
Changes to `GDK_SCALE` apply to applications started after the change. So make sure you quit the windows that you have that are oversized after the change (or close all windows with `Ctrl + Alt + Del`!).
Changes to `GDK_SCALE` apply to applications started after the change (and GTK only honors whole numbers, so keep it at the nearest integer of your monitor scale). So make sure you quit the windows that you have that are oversized after the change (or close all windows with `Ctrl + Alt + Del`!).
You can also quickly cycle through the major monitor scaling ratios (1x, 1.6x, 2x, 3x) using `Super + /` to go higher and `Super + Alt + /` to go lower. If you have the default configuration, these changes will also persist past reboot.
You can also quickly cycle through the major monitor scaling ratios (1x, 1.25x, 1.6x, 2x, 3x, 4x) using `Super + /` to go higher and `Super + Alt + /` to go lower. If you have the default configuration, these changes will also persist past reboot.
### Extending and mirroring laptop displays
@@ -28,18 +28,18 @@ When you're extending, closing the lid on the laptop will automatically turn off
### Arranging multiple screens
Hyprland works great with multiple screens. Read more about how to lay them out in [the Hyprland monitor documentation](https://wiki.hypr.land/Configuring/Basics/Monitors/). You can [bind specific workspaces to specific monitors](https://wiki.hypr.land/Configuring/Basics/Workspace-Rules/) as well.
Hyprland works great with multiple screens. Read more about how to lay them out in [the Hyprland monitor documentation](https://wiki.hypr.land/Configuring/Basics/Monitors/). You can [bind specific workspaces to specific monitors](https://wiki.hypr.land/Configuring/Basics/Workspace-Rules/) as well. In Omarchy, these rules go in `~/.config/hypr/monitors.lua` as `hl.monitor` entries — the file ships with commented examples for pinning a specific monitor to a resolution, position, and rotation.
You can also checkout [Hyprmon](https://github.com/erans/hyprmon/), if you'd like a TUI to help you with the positioning of multiple screens.
### Controlling brightness
Monitor brightness is controlled by the dedicated function keys for brightness up/down. If you hold down shift while pressing these, you'll go to maximum or minimum brightness.
Monitor brightness is controlled by the dedicated function keys for brightness up/down. If you hold down shift while pressing these, you'll go to maximum or minimum brightness. The keys control the display you're focused on, so external monitors that speak DDC/CI are adjusted the same way as the laptop screen.
### Apple Displays
If you're using an Apple display, the regular keyboard brightness keys will also automatically work, if you're focused on the Apple display. This is done through the `asdcontrol` command.
Note that if you're using an Apple 6K XDR display, you may see a phantom screen in your `hyprctl monitors` listing. You can turn this off with something like `monitor=DP-2,disable` via _Setup > Monitors_.
Note that if you're using an Apple 6K XDR display, you may see a phantom screen in your `hyprctl monitors` listing. You can turn this off with something like `hl.monitor({ output = "DP-2", disabled = true })` via _Setup > Monitors_.
On Intel machines, you should be connecting to Apple displays using a regular Thunderbolt cable. On other machines without Thunderbolt, you'll typically have to use a [DP + USB-A -> USB-C cable](https://www.amazon.com/dp/B0BNX7MS6N) to make it work.
manual/28-keyboard-mouse-trackpad.md
+38 -26
View File
@@ -1,46 +1,58 @@
# Keyboard, Mouse, Trackpad
Hyprland let's you configure all your inputs in great detail. You can change the keyboard repeat to be supersonically fast or make the trackpad use natural scrolling. You change all of it in `~/.config/hypr/input.conf`, which you can also reach via _Setup > Input_ in the Omarchy menu (`Super + Alt + Space`).
Hyprland lets you configure all your inputs in great detail. You can change the keyboard repeat to be supersonically fast or make the trackpad use natural scrolling. You change all of it in `~/.config/hypr/input.lua`, which you can also reach via _Setup > Input_ in the Omarchy menu (`Super + Space`). Anything you set there replaces Omarchy's defaults.
Here's an example:
```
input {
# Use multiple keyboard layouts and switch between them with Alt + Space
kb_layout = us,dk
kb_options = compose:caps,grp:alt_space_toggle
```lua
hl.config({
input = {
-- Use multiple keyboard layouts and switch between them with Left Alt + Right Alt
kb_layout = "us,dk",
kb_options = "compose:caps,shift:both_capslock_cancel,grp:alts_toggle",
# Change speed of keyboard repeat
repeat_rate = 40
repeat_delay = 600
-- Change speed of keyboard repeat
repeat_rate = 40,
repeat_delay = 600,
# Increase sensitity for mouse/trackpack (default: 0)
sensitivity = 0.35
-- Increase sensitivity for mouse/trackpad (default: 0)
sensitivity = 0.35,
touchpad {
# Use natural (inverse) scrolling
natural_scroll = true
touchpad = {
-- Use natural (inverse) scrolling
natural_scroll = true,
# Use two-finger clicks for right-click instead of lower-right corner
clickfinger_behavior = true
-- Use two-finger clicks for right-click instead of lower-right corner
clickfinger_behavior = true,
# Control the speed of your scrolling
scroll_factor = 0.3
}
}
-- Control the speed of your scrolling
scroll_factor = 0.3,
},
},
})
# Scroll faster in the terminal
windowrule = scrolltouchpad 1.5, tag:terminal
-- Scroll faster in the terminal
o.window("(Alacritty|kitty|foot)", { scroll_touchpad = 1.5 })
```
You can [see all the input options](https://wiki.hypr.land/Configuring/Basics/Variables/#input) on the Hyprland wiki for inputs.
### Trackpad gestures
You can also turn on [touchpad gestures](https://wiki.hypr.land/Configuring/Advanced-and-Cool/Gestures/), like swiping with three fingers to change workspaces:
```lua
hl.gesture({ fingers = 3, direction = "horizontal", action = "workspace" })
```
### Use ALT as SUPER
On some keyboards, it's not convenient to use the primary meta key (Windows/cmd key) as SUPER. You can change this to be ALT instead using this change:
```
input {
kb_options = compose:caps,altwin:swap_alt_win
}
```lua
hl.config({
input = {
kb_options = "compose:caps,shift:both_capslock_cancel,altwin:swap_alt_win",
},
})
```
manual/29-system-sleep.md
+3 -3
View File
@@ -4,10 +4,10 @@ Omarchy enables suspend and hibernation by default, but if you're having issues
### Toggle suspend
You toggle suspend under _Setup > System Sleep > Enable/Disable Suspend_. That just reveals/hides the option under _System_ (or `Super + Esc`), and then you can see if it works consistently on your system. If not, you can turn it off again using _Setup > System Sleep > Disable Suspend_.
You toggle suspend by running `omarchy toggle suspend` from the terminal. That just reveals/hides the option under _System_ (or `Super + Esc`), and then you can see if it works consistently on your system. If not, you can hide it again with the same command.
### Toggle hibernation
You toggle hibernation under _Setup > System Sleep > Enable/Disable Hibernation_. Hibernation creates a /swap subvolume on your boot drive the size of our physical RAM allocation, so make sure you have plenty of room to spare. On a 32GB machine, you'll always need 32GB+ free for this volume.
You set up hibernation by running `omarchy hibernation setup` from the terminal. Hibernation creates a /swap subvolume on your boot drive the size of your physical RAM allocation, so make sure you have plenty of room to spare. On a 32GB machine, you'll always need 32GB+ free for this volume. Hibernation also requires the default Limine bootloader.
When enabled, you'll see the hibernate option under _System_ (or `Super + Esc`), and then you can see if it works consistently on your system. If not, you can turn it off again using _Setup > System Sleep > Disable Hibernate_.
When set up, you'll see the hibernate option under _System_ (or `Super + Esc`), and then you can see if it works consistently on your system. If not, you can remove it again by running `omarchy hibernation remove`.
manual/30-hardware-authentication.md
+6 -6
View File
@@ -2,16 +2,16 @@
### Fingerprint authentication
A lot of laptops come with a fingerprint sensor to do authentication. You can use this with Omarchy by running _Setup > Security > Fingerprint_ in the Omarchy menu (`Super + Alt + Space`).
A lot of laptops come with a fingerprint sensor to do authentication. You can use this with Omarchy by running _Setup > Security > Fingerprint_ in the Omarchy menu (`Super + Space`).
That'll install the fingerprint package, collect your print, verify it, and you'll be set to go using your fingerprint to unlock from the lock screen (which you can trigger with `Super + Escape`), enter sudo mode, and authorize system prompts.
That'll install the fingerprint package, collect your print, verify it, and you'll be set to go using your fingerprint to unlock from the lock screen (which you can trigger with `Super + Ctrl + L`), enter sudo mode, and authorize system prompts.
If you've setup fingerprint authentication, but then need to work on an external keyboard that doesn't have it, just hit `CTRL + C`, when you're prompted for your fingerprint during `sudo`.
When your laptop lid is closed, the fingerprint prompt is automatically skipped, so you go straight to the password prompt instead of waiting on a sensor you can't reach. If you otherwise need to work on an external keyboard that doesn't have a sensor, just hit `CTRL + C`, when you're prompted for your fingerprint during `sudo`.
You can remove the fingerprint authentication under _Remove > Fingerprint_ in the Omarchy menu.
You can remove the fingerprint authentication under _Remove > Security > Fingerprint_ in the Omarchy menu.
### Fido2 authentication
If you're using a Fido2 device, you can set it up for `sudo` authentication using _Setup > Security > Fido2_ in the Omarchy menu (`Super + Alt + Space`). It's only for `sudo`, though, not unlocking your computer.
If you're using a Fido2 device, you can set it up for `sudo` authentication using _Setup > Security > Fido2_ in the Omarchy menu (`Super + Space`). It covers `sudo` and system authorization prompts, though, not unlocking your computer.
You can remove the fido2 authentication under _Remove > Fido2_ in the Omarchy menu.
You can remove the fido2 authentication under _Remove > Security > Fido2_ in the Omarchy menu.
manual/31-fonts.md
+1 -1
View File
@@ -4,6 +4,6 @@ Omarchy uses JetBrainsMono Nerd Font as both the terminal and system font by def
![jetbrainsmono.jpg](https://learn.omacom.io/u/jetbrainsmono-lhatXs.jpg)
You can change this for the terminal through the _Style > Font_ menu in the Omarchy menu (`Super + Alt + Space`).
You can change this through the _Style > Font_ menu in the Omarchy menu (`Super + Space`). That sets the monospace font everywhere: the terminal, the bar, and anything else that asks for it.
You can install other popular programming fonts via _Install > Style > Font_ in the Omarchy menu.
manual/32-backgrounds.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Backgrounds
All the backgrounds for Omarchy live in `~/.config/omarchy/backgrounds/[theme]`. If you want to add an extra background image to, say, the nord theme, you just put the file in `~/.config/omarchy/backgrounds/nord`.
Every theme ships with its own set of backgrounds, and you can add extras of your own in `~/.config/omarchy/backgrounds/[theme]`. If you want to add an extra background image to, say, the nord theme, you just put the file in `~/.config/omarchy/backgrounds/nord`.
You can do this most easily by going to _Install > Style > Background_ in the Omarchy Menu. That'll bring up the folder where the backgrounds for that theme is stored. Hit `Super + Shift + F` to start another file manager, find your background, copy it over. Now it'll be included in the choices of backgrounds you can select between using `Super + Ctrl + Space`.
manual/34-branding.md
+7 -1
View File
@@ -4,7 +4,13 @@ Omarchy allows you to set your company logo or personal image for both the boot
### Boot unlock
You can use `omarchy plymouth preview` to see what your custom logo and colors would look like. Then apply the setup with `omarchy plymouth set`. If you want to revert, you can use `omarchy plymouth reset`.
You can use `omarchy plymouth preview` to see what your custom logo and colors would look like. It takes a background color, a text color, a logo png, and a path for the preview image:
```
omarchy plymouth preview '#1d2021' '#ebdbb2' logo.png preview.png
```
Then apply the setup with `omarchy plymouth set '#1d2021' '#ebdbb2' logo.png`, which will also give the SDDM login screen the same colors and logo. If you want to revert, you can use `omarchy plymouth reset`.
![shopify-plymouth.jpeg](https://learn.omacom.io/u/shopify-plymouth-AjqlgW.jpeg)
manual/35-common-tweaks.md
+17 -13
View File
@@ -6,28 +6,32 @@ If you screw something up, you can restore individual configs to their original
### Reveal all tray icons all the time
By default, tray icons, like Dropbox, 1password, or Steam, are hidden behind the tray expander icon. If you'd like to have them exposed all the time, you can change the `group/tray-expander` line to `tray` in Waybar's `~/.config/waybar/config.jsonc` (access via _Setup > Config > Waybar_).
By default, tray icons, like Dropbox, 1password, or Steam, are hidden behind the tray expander arrow, which reveals them when you hover it. If you'd like to have them exposed all the time, right-click the expander arrow to open the tray icon manager, then pin the icons you want to keep visible (you can also hide the ones you never want to see).
### Rounded window corners
Omarchy's default design is one of square corners, but if you like to soften that up a bit, you can change `~/.config/hypr/looknfeel.conf` so rounding is no longer commented out:
Omarchy's default design is one of square corners, but if you like to soften that up a bit, you can change `~/.config/hypr/looknfeel.lua` so rounding is no longer commented out:
```
decoration {
# Use round window corners
rounding = 8
}
hl.config({
decoration = {
-- Use round window corners.
rounding = 8,
},
})
```
### Remove window gaps
On laptop displays, some people prefer to not to waste any pixels on window gaps (or even a top bar, which you can toggle off with `Super + Shift + Space`). You can remove all gaps by removing the comments in this section of `~/.config/hypr/looknfeel.conf`:
On laptop displays, some people prefer not to waste any pixels on window gaps (or even a top bar, which you can toggle off with `Super + Shift + Space`). You can toggle all gaps and borders off with `Super + Shift + Backspace`, or remove them permanently by removing the comments in this section of `~/.config/hypr/looknfeel.lua`:
```
general {
# No gaps between windows or borders
gaps_in = 0
gaps_out = 0
border_size = 0
}
hl.config({
general = {
-- No gaps between windows or borders.
gaps_in = 0,
gaps_out = 0,
border_size = 0,
},
})
```
manual/36-extra-themes.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Extra themes
You can install any of these themes by copying the GitHub URL and selecting `Install > Style > Theme` via the Omarchy menu (`Super + Alt + Space`). If you want to remove it again, just use `Remove > Style > Theme` and select it there.
You can install any of these themes by copying the GitHub URL and selecting `Install > Style > Theme` via the Omarchy menu (`Super + Space`). If you want to remove it again, just use `Remove > Theme` and select it there.
![aetheria.png](https://learn.omacom.io/u/aetheria-jaDcHN.png)
[Aetheria](https://github.com/JJDizz1L/aetheria)
manual/37-making-your-own-theme.md
+6 -6
View File
@@ -1,18 +1,18 @@
# Making your own theme
You can add your own themes to `~/.config/omarchy/themes`. Just copy one of the existing ones as a base (look in `~/.local/share/omarchy/themes`), then tweak to your delight. As long as your theme is inside that folder, it'll be included in the theme selection menu.
You can add your own themes to `~/.config/omarchy/themes`. Just copy one of the existing ones as a base (look in `/usr/share/omarchy/themes`), then tweak to your delight. As long as your theme is inside that folder, it'll be included in the theme selection menu.
The main file you have to tweak is `colors.toml`. That defines the color set that's then used to generate configurations for the terminal (Ghostty/Alacritty/Kitty), btop, Chromium, Hyprland, Hyprlock, Mako, SwayOSD, Walker, and Waybar.
The main file you have to tweak is `colors.toml`. That defines the color set that's then used to generate configurations for the terminal (Foot/Alacritty/Ghostty/Kitty), btop, Chromium, Hyprland, Neovim, Helix, VSCode, Obsidian, and the entire Omarchy shell (top bar, menu, notifications, OSD, and lock screen).
You can also use the included Aether application to create a new theme using a lovely GUI interface to play with colors and search for backgrounds. Just start it via the app launcher on `Super + Space`.
You can also use the included Aether application to create a new theme using a lovely GUI interface to play with colors and search for backgrounds. Just start it via the apps menu on `Super + Alt + Space`.
### Light mode
If you're making a light mode theme, drop an empty file called `light.mode` in the root of your theme. Then it'll automatically be paired with light mode for all the apps.
If you're making a light mode theme, set `mode = "light"` at the top of your `colors.toml`. Then it'll automatically be paired with light mode for all the apps. (The old way of dropping an empty file called `light.mode` in the root of your theme still works too.)
### Icon colors
If you'd like to color-match the file manager icons to your theme, add a file called `icons.theme` with the name of the icon set you want to you. By default, the options are: `Yaru Yaru-blue Yaru-dark Yaru-magenta Yaru-olive Yaru-prussiangreen Yaru-purple Yaru-red Yaru-sage Yaru-wartybrown Yaru-yellow`.
If you'd like to color-match the file manager icons to your theme, add a file called `icons.theme` with the name of the icon set you want to use. By default, the options are: `Yaru Yaru-blue Yaru-dark Yaru-magenta Yaru-olive Yaru-prussiangreen Yaru-purple Yaru-red Yaru-sage Yaru-wartybrown Yaru-yellow`.
### Unlock image
@@ -20,6 +20,6 @@ Themes supplied with `unlock.png` and `preview-unlock.png` images will be listed
### Distributing your theme
If you want to distribute your theme so others can use it, you need to put it on a public git server, like GitHub. Then people can install it using _Install > Theme_ in the Omarchy menu using that URL. It's recommended that you follow the naming convention of `omarchy-[themename]-theme`, as the theme will show correctly as just `[themename]` in the theme selection menu after installation.
If you want to distribute your theme so others can use it, you need to put it on a public git server, like GitHub. Then people can install it using _Install > Style > Theme_ in the Omarchy menu using that URL. It's recommended that you follow the naming convention of `omarchy-[themename]-theme`, as the theme will show correctly as just `[themename]` in the theme selection menu after installation.
You can have your theme added to [the extra themes page](36-extra-themes.md) by pinging @tahayvr on [the #omarchy Discord](https://discord.gg/tXFUdasqhY).
manual/39-mac-support.md → manual/38-mac-support.md
+5 -1
View File
@@ -1,6 +1,6 @@
# Mac support
As of Omarchy 3, there's built-in support for **Intel Macs**. There are a couple of known limitations at the moment, but as long as you're aware and OK with those; you can breathe some new life into your old Macs by loading Omarchy.
Omarchy has built-in support for **Intel Macs**. There are a couple of known limitations at the moment, but as long as you're aware and OK with those; you can breathe some new life into your old Macs by loading Omarchy.
Please note that installing on an M-series Mac is not directly supported at this time. You can find out more about the state of this in #omarchy-on-other in our [Discord](https://discord.gg/tXFUdasqhY).
@@ -35,6 +35,8 @@ It is necessary to disable Apple's Secure Boot in order to boot the bootable USB
3. Select the orange EFI Boot device
4. Proceed with the [install as normal](02-getting-started.md)
The installer detects Mac hardware and applies the needed fixes automatically: Broadcom Wi-Fi drivers and firmware, the SPI keyboard driver on the MacBook models that need it, and an NVMe suspend fix for those same models.
### Known Limitations
Members of the community are constantly working on solutions to these challenges so if these are problematic for you, join #omarchy-on-other in our [Discord](https://discord.gg/tXFUdasqhY) and see if there's any up-to-date methods for resolving these.
@@ -65,3 +67,5 @@ The Apple T2 Security Chip was introduced in 2017. The T2 chip was discontinued
- MacBook Pro 15-inch (2019) – Model: A1990
- MacBook Pro 13-inch (2020, two Thunderbolt 3 ports) – Model: A2265
- MacBook Pro 15-inch (2020) – Model: A1990
On these models, the installer automatically sets up the patched `linux-t2` kernel, the T2 audio configuration, Apple's Broadcom Wi-Fi/Bluetooth firmware, and fan control via `t2fanrd`. The Touch Bar runs on the kernel's built-in Boot Camp-style support.
manual/38-manual-installation.md
-37
View File
@@ -1,37 +0,0 @@
# Manual installation
If you can't use the Omarchy ISO, you can do a manual installation using the vanilla arch ISO, archinstall, and following the steps in this guide. This is not something most people should attempt, but if you know what you're doing, and why you're doing it, this is how.
1. [Download the Arch Linux ISO](https://archlinux.org/download/#http-downloads), put it on a USB stick (use [balenaEtcher](https://etcher.balena.io/) on Mac/Windows), and boot off the stick (remember to turn off Secure Boot in the BIOS!).
2. If you're on wifi, start by running `iwctl`, then type `station wlan0 scan`, then `station wlan0 connect <tab>`, pick your network, and enter the password. If you're on ethernet, you don't need this.
3. Run `archinstall` and pick these options (and leave anything not mentioned as-is):
| Section | Option |
| -------- | ------ |
| Mirrors and repositories | Select regions > Your country |
| Disk configuration | Partitioning > Default partitioning layout > Select disk (with space + return) |
| Disk > File system | btrfs (default structure: yes + use compression) |
| Disk > Disk encryption | Encryption type: LUKS + Encryption password + Partitions (select the one) |
| Hostname | Give your computer a name |
| Bootloader | Limine |
| Authentication > Root password | Set yours |
| Authentication > User account | Add a user > Superuser: Yes > Confirm and exit |
| Applications > Audio | pipewire |
| Network configuration | Copy ISO network config |
| Timezone | Set yours |
Beware that you _must setup disk encryption_ to use Omarchy as designed! The setup relies exclusively on disk encryption to secure your device, as it'll auto-login the user after the disk has been decrypted at boot.
Just note that this encryption setup won't allow you to enter the password from a Bluetooth keyboard at startup. Just like you can't use a Bluetooth keyboard to enter the BIOS on a PC. You'll need a keyboard that either uses a 2.4ghz dongle or a cable (which is much nicer for latency anyway!). I personally love the [Lofree Flow84](https://www.lofree.co/products/lofree-flow-the-smoothest-mechanical-keyboard)!
Here's what the disk encryption setup should look like. You need to pick `LUKS`, then set the encryption password, then apply to the partition (this step is crucial or nothing gets encrypted!):
![arch-encryption.png](https://learn.omacom.io/u/arch-encryption-urjrDm.png)
Once Arch has been installed, pick reboot, login with the user you just setup, and now you're ready to install Omarchy by running:
`curl -fsSL https://omarchy.org/install | bash`
It'll first ask you to sudo, then shortly thereafter, it'll ask for your name and email address. Those credentials are used to preconfigure git (`git config --global user.name/email`) and set for auto-expansion on `CapsLock Space E` (email) and `CapsLock Space N` (name). After that, it'll run by itself for 5-30 minutes, depending on the speed of your internet connection. When it's all done, it'll ask for your permission to reboot the system.
Now you're ready to Omarchy!
manual/40-troubleshooting.md → manual/39-troubleshooting.md
+9 -5
View File
@@ -2,25 +2,29 @@
### I broke my system with an update!
First try to [rollback your system](42-system-snapshots.md) the version before your recent update. If that doesn't work, use `omarchy-debug` to share with your problem on #omarchy-help in the Discord. And if all that fails, you can reinstall the defaults configs and packages using `omarchy-reinstall`.
First try to [rollback your system](41-system-snapshots.md) the version before your recent update. If that doesn't work, use `omarchy-debug` to share with your problem on #omarchy-help in the Discord. And if all that fails, you can reinstall the defaults configs and packages using `omarchy-reinstall`.
### Why are some apps so large on my display?
Omarchy assumes a 2x high-resolution display, which requires setting `GDK_SCALE` to 2 in `~/.config/hypr/hyprland.conf`. But if you're on a 1x display, you can change this to 1 (and then restart any app that's oversized). See [the manual on monitors](27-monitors.md).
Omarchy assumes a 2x high-resolution display, which requires setting `GDK_SCALE` to 2 in `~/.config/hypr/monitors.lua`. But if you're on a 1x display, you can change `local omarchy_gdk_scale = 2` to 1 (and then restart any app that's oversized). See [the manual on monitors](27-monitors.md).
For Spotify, you can use `Ctrl + Minus` to shrink the UI (and `Ctrl + Plus` to make it bigger).
### Why isn't Caps Lock working?
In Omarchy, Caps Lock has been designated to be the xcompose key. That's how you get [quick emojis](05-hotkeys.md#quick-emojis) and [other autocompletions](05-hotkeys.md#quick-completions) done. If you really miss using Caps Lock, you can remape the xcompose key to something else by editing `~/.config/hypr/input.conf`, like setting it to the right alt key:
In Omarchy, Caps Lock has been designated to be the xcompose key. That's how you get [quick emojis](05-hotkeys.md#quick-emojis) and [other autocompletions](05-hotkeys.md#quick-completions) done. If you really miss using Caps Lock, you can remap the xcompose key to something else by editing `~/.config/hypr/input.lua`, like setting it to the right alt key:
```
kb_options = compose:ralt
hl.config({
input = {
kb_options = "compose:ralt",
},
})
```
### Why are my external speakers not playing?
Probably because they're not set as the primary output. Click on the speaker in the top right of the waybar, and it'll launch the volume controls where you can select the primary speaker (designate it as default with "d").
Probably because they're not set as the primary output. Click on the speaker icon on the right side of the bar, and it'll open the volume popup where you can pick the output device (and mix per-app volumes too).
### Why can't I login or sudo with my password?
manual/41-faq.md → manual/40-faq.md
+16 -20
View File
@@ -2,39 +2,33 @@
### How do I switch between keyboard layouts?
Edit your `~/.config/hypr/input.conf` file and add this to switch between layouts on `Left Alt + Right Alt`:
Edit your `~/.config/hypr/input.lua` file and add this to switch between layouts on `Left Alt + Right Alt`:
```
# Use multiple keyboard layouts and switch between them with Left Alt + Right Alt
input {
kb_layout = us,fr
kb_options = compose:caps,grp:alts_toggle
}
hl.config({
input = {
-- Use multiple keyboard layouts and switch between them with Left Alt + Right Alt
kb_layout = "us,fr",
kb_options = "compose:caps,shift:both_capslock_cancel,grp:alts_toggle",
},
})
```
You can even [configure Waybar to showing your current keyboard layout in the top bar](https://github.com/basecamp/omarchy/discussions/111).
The bar will automatically show your current keyboard layout once you have multiple layouts configured (and you can click it to switch too).
### How do I change the clock format to 12-hour?
Edit your `~/.config/waybar/config.jsonc` file and replace this:
Right-click the clock in the bar to cycle through the common formats, including the 12-hour ones. You can also set the format directly:
```
"clock": {
"format": "{:%A %H:%M}",
```
with:
```
"clock": {
"format": "{:%A %I:%M %p}",
omarchy bar set omarchy.clock format "dddd h:mm AP"
```
This will display Sunday 10:55 AM.
### How do I change where screenshots or screenrecordings are saved?
If you screenshots to be saved to `~/Pictures/Screenshots` instead of just `~/Pictures`, you can open _Setup > Defaults_ via the Omarchy menu and set this:
If you want screenshots to be saved to `~/Pictures/Screenshots` instead of just `~/Pictures`, you can add this to a file under `~/.config/uwsm/env.d/` (like `~/.config/uwsm/env.d/capture`):
```
export OMARCHY_SCREENSHOT_DIR="$HOME/Pictures/Screenshots"
@@ -52,12 +46,14 @@ Remember that you have built-in brightness control in Omarchy for the Apple Disp
### How do I get rid of all the extra software?
If you don't want programs like Spotify or Obsidian or any of the other preinstalled stuff, you can very easily remove it.
If you don't want programs like Obsidian or LibreOffice or any of the other preinstalled stuff, you can very easily remove it.
Run _Remove > Package_ to see every package that's installed. Then you can select any package you'd like to remove with tab, and start removing everything you've selected with return.
And you can use _Remove > Web App_ from the Omarchy menu to remove any of the preinstalled web apps you don't want.
Or run _Remove > Preinstalls_ to sweep out all the preinstalled extras — web apps, TUIs, and optional applications — in one go.
---
For errors and broken bits, see [the Troubleshooting section](40-troubleshooting.md).
For errors and broken bits, see [the Troubleshooting section](39-troubleshooting.md).
manual/42-system-snapshots.md → manual/41-system-snapshots.md
+1 -1
View File
@@ -12,7 +12,7 @@ When you arrive inside, a notification will popup notifying you that you're in a
![omarchy-restore-snapshot.png](https://learn.omacom.io/u/omarchy-restore-snapshot-2TrMhj.png)
This will restore your `/root`, but not your `/home`. So it works for reverting a broken system update, but not for recovering lost personal files.
This will restore your root filesystem, but not your `/home`. So it works for reverting a broken system update, but not for recovering lost personal files.
This also means that your `~/.config` directory is kept as-is. So if you're rolling back to an earlier version of a library or application that stores configuration files in a new format, you'll have to sort that out manually.
manual/43-security.md → manual/42-security.md
+4 -3
View File
@@ -3,12 +3,13 @@
Omarchy takes security extremely seriously. This is meant to be an operating system that you can use to do _Real Work_ in the _Real World_. Where losing a laptop can't lead to a security emergency. So here's what we do:
1. *Full-disk encryption is mandatory*: This is the most important step to securing the physical protection of your data. If your computer is lost or stolen, the data is fully encrypted using standard LUKS (Linux Unified Key Setup).
2. *Firewall is enabled by default*: All incoming traffic by default except for port 22 for ssh and port 53317 for [LocalSend](https://localsend.org/). We even lock down Docker access using the [ufw-docker](https://github.com/chaifeng/ufw-docker) setup to prevent that your containers are accidentally exposed to the world.
3. *Arch always have the latest updates*: Arch, the underlying distro that Omarchy is built on, is a rolling distribution. This means that any security vulnerability that's discovered and patched in any package is immediately available for install using `yay -Syu`. You're always running the latest, most secure versions of everything that way.
4. *Omarchy maintains its own packages and mirror*: Omarchy only relies on packages from Arch's own core/extra/multilib repositories and its own Omarchy Package Repository by default. You can install software directly from AUR, but Omarchy does not by default. Even for the optional installs.
2. *Firewall is enabled by default*: All incoming traffic is blocked by default except for port 53317 for [LocalSend](https://localsend.org/). Even ssh is off until you turn it on via _Setup > Security > SSHD_, which opens port 22 (rate limited against brute force) as part of the setup. We even lock down Docker access using the [ufw-docker](https://github.com/chaifeng/ufw-docker) setup to prevent that your containers are accidentally exposed to the world.
3. *Arch always have the latest updates*: Arch, the underlying distro that Omarchy is built on, is a rolling distribution. This means that any security vulnerability that's discovered and patched in any package is quickly available for install using `omarchy-update`. You're always running the latest, most secure versions of everything that way.
4. *Omarchy maintains its own packages and mirror*: Omarchy only relies on packages from Arch's own core/extra/multilib repositories and its own Omarchy Package Repository by default. You can install software directly from AUR, but the base install doesn't — only a few optional installs, like the third-party browsers, pull from the AUR.
5. *Cloudflare protects us from DDoS*: All the Omarchy distribution infrastructure — the ISOs, the Omarchy packages, the Arch mirror — is protected behind Cloudflare's formidable DDoS shield and hosted on their CDN. This provides superb availability.
## Signing Keys
The public key for all ISO signatures and Omarchy repo package is `40DFB630FF42BCFFB047046CF0134EE680CAC571` ([verify at openpgp.org](https://keys.openpgp.org/search?q=pkgs%40omarchy.org)). The `omarchy/omarchy-keyring` package contains this as well and will be used to rollout any potential updates seamlessly.
You can find the signature for any ISO release by adding .sig to the URL. Like https://iso.omarchy.org/omarchy-x.x.x.iso.sig.
manual/44-omarchy-on.md → manual/43-omarchy-on.md
View File
manual/45-dual-boot-install.md → manual/44-dual-boot-install.md
+6 -2
View File
@@ -1,10 +1,11 @@
# Dual Boot Install
In Omarchy Quattro, you're able to install Omarchy to a single partition alongside Windows or other installations. This differs from previous versions where full-disk was required.
You're able to install Omarchy to a single partition alongside Windows or other installations.
This installation method still comes with LUKS encryption for the partition by default so it's effectively no different than full drive and simply requires free space to be available on the disk.
## Making Space on Windows
To install alongside Windows, type `disk management` in the start menu and select the option for **Create and format hard disk partitions**.
![screenshot-2026-06-06_13-37-28.png](https://learn.omacom.io/u/screenshot-2026-06-06_13-37-28-mjjTRj.png)
@@ -22,19 +23,22 @@ When you're finished, you should see something like this where the 50GB section
![screenshot-2026-06-06_13-38-36.png](https://learn.omacom.io/u/screenshot-2026-06-06_13-38-36-LjrgYW.png)
## Installing Omarchy
The install process for Omarchy is effectively the same as normal. After you select your disk, you'll be given the option of **Free space install**. Select that option to prevent wiping the full disk.
![screenshot-2026-08-12_20-21-05.png](https://learn.omacom.io/u/screenshot-2026-08-12_20-21-05-MiHt03.png)
Confirm that everything looks good and wait for the install to finish like normal. This is also where you could elect to install unecrypted (not recommended) just like on a full-drive install.
Confirm that everything looks good and wait for the install to finish like normal. This is also where you could elect to install unencrypted (not recommended) just like on a full-drive install.
![screenshot-2026-08-12_20-33-49.png](https://learn.omacom.io/u/screenshot-2026-08-12_20-33-49-UX0gZl.png)
## Adding Other Installs to the Bootloader
When you finish your Omarchy install, you'll notice that the Limine bootloader is the default now. With this, you can also add options to Limine for your other installs such as Windows.
In order to do that, run `limine-scan` and follow the prompts to add whichever items you'd like to your limine config. Then when you boot, you'll see your normal options for Omarchy, as well as Windows Boot Manager or others.
## Bitlocker
It's important to note that this install method is not compatible with Bitlocker as it encrypts the entire drive, not just the partition. If you encounter an error stating that Bitlocker is enabled, boot to Windows, go to **Settings -> Privacy & Security -> Device encryption** and toggle Bitlocker off. It may take some time to decrypt the drive.
![screenshot-2026-08-12_20-28-27.png](https://learn.omacom.io/u/screenshot-2026-08-12_20-28-27-jdscbY.png)
manual/45-unattended-installs.md
+61
View File
@@ -0,0 +1,61 @@
# Unattended Installs
The Omarchy ISO can install itself with nobody at the keyboard. If the installer finds a second drive labeled `cidata` carrying its configuration files, it copies them off, skips the setup wizard entirely, and reboots into the finished system on its own. No special ISO build, no extra boot menu entry — with no such drive attached, nothing changes and you get the normal wizard.
This makes Omarchy great as a base image for disposable dev environments: create a VM in Proxmox or with Packer, boot it, walk away, SSH in. `cidata` is the cloud-init `NoCloud` label, so all the common virtualization tooling already knows how to attach such a drive.
## The configuration files
The files are exactly what the installer's own wizard writes, so the easiest way to get a starting set is to run one interactive install (in a VM, say) and copy what it wrote into `/root`:
| File | Required | Purpose |
|------|----------|---------|
| `user_configuration.json` | Yes | Disk, hostname, timezone, keyboard |
| `user_credentials.json` | Yes | Username and password hash |
| `user_full_name.txt` | No | Git full name |
| `user_email_address.txt` | No | Git email |
| `user_encrypt_installation.txt` | No | `true` when the configuration carries a `disk_encryption` block |
| `authorized_keys` | No | SSH public keys, one per line |
| `tailscale_authkey` | No | Tailscale auth key for joining your tailnet on first boot |
Generate the password hash for `user_credentials.json` with `openssl passwd -6 "yourpassword"`.
You can also drop in an empty file named `defer-provisioning` in place of `user_credentials.json`. That runs the same [prepare-for-another-owner install](02-getting-started.md) you can trigger interactively: the machine installs with no personal details, and whoever boots it first picks their keyboard and creates their user. That's the mode for imaging rigs, where the drive shouldn't carry anyone's credentials at all.
## SSH access
When `authorized_keys` is present, the install sets the keys up as the user's `~/.ssh/authorized_keys`, enables `sshd`, and opens the firewall for it. (A stock Omarchy install ships openssh with the service disabled and the port closed, so an unattended machine would otherwise be unreachable.) The install only adds your keys — it doesn't loosen any of the SSH daemon's other authentication settings.
When `tailscale_authkey` is present, the machine joins your tailnet on first boot instead: Tailscale is installed from the ISO's bundled packages, the firewall allows the tailnet interface, and a background job runs the join as soon as the machine actually has network, retrying until it succeeds. Use a reusable, pre-authorized key so one drive image can serve many machines.
## Building the cidata drive
Any filesystem with the right label works. A tiny ISO is the easy way:
```bash
mkdir cidata
cp user_configuration.json user_credentials.json authorized_keys cidata/
genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/
```
Then attach it to the VM alongside the Omarchy ISO. Here's a full Proxmox example:
```bash
qm create 101 --name my-omarchy \
--bios ovmf --machine q35 --cpu host --cores 4 --memory 8192 \
--ostype l26 --scsihw virtio-scsi-single \
--efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0 \
--scsi0 local-lvm:40,discard=on,iothread=1 \
--net0 virtio,bridge=vmbr0 --vga virtio --serial0 socket \
--ide2 local:iso/omarchy.iso,media=cdrom \
--ide3 local:iso/cidata.iso,media=cdrom \
--boot order='scsi0;ide2'
qm start 101
```
The boot order lists the disk first on purpose: the empty disk falls through to the ISO on the first boot, and the installed system boots from disk ever after.
## Two caveats
Encrypted unattended installs aren't fully unattended — someone still has to type the LUKS passphrase at the first boot. And the `disk_encryption` block in `user_configuration.json` carries that passphrase in plaintext, so treat a cidata drive built from an encrypted install as the secret it is.