Running AI agents on Windows was a poor experience (PowerShell is not agent-friendly, and there are no great terminals available), and I also ran into some issues with WSL2. Since I prefer working on the CLI anyway, I decided to switch to Linux, and on a friend’s recommendation I went with CachyOS.

I have been on CachyOS for over a month now, and it has been a great experience — no crashes yet. These days I only keep Windows around for gaming. I have also been seeing a lot of Linux posts lately, so I decided to write this guide as a summary of my own tinkering.

Note
CachyOS is based on Arch Linux with rolling releases, focused on performance for gaming and productivity.
The installation itself is fairly simple — the real work is the customization and configuration that comes after. If you don’t want to tinker, it’s probably not for you; but if you want a beautiful desktop and the latest software, it’s highly recommended.

CachyOS Installation

First, prepare a USB drive and the CachyOS system image. Download the desktop ISO from the CachyOS website, then write it to the USB drive to make a bootable drive. I recommend Ventoy for this — check its official site for details.

Once that’s ready, you can start the installation. I’ll demonstrate in a VM, so the screenshots may have some resolution issues.

Note
If you’re setting up a dual-boot system, enter the BIOS in advance and disable Secure Boot.

Boot from the USB drive, adjust the language, and launch the installer.

cachyos-installation-1.png

Select the language to use.

cachyos-installation-2.png

Select the time zone.

cachyos-installation-3.png

Skip the keyboard step and move on to the bootloader selection. Limine is the default recommendation, but it requires at least 4 GB for the EFI partition, mounted at /boot. Since I was setting up a dual-boot system and didn’t allocate much space to CachyOS, I chose GRUB instead. Search for the differences and pick what fits your needs.

cachyos-installation-4.png

Now it’s time to partition. If you’re installing a dual-boot system, manual partitioning is recommended.

cachyos-installation-5.png

Select the free space you reserved and create a partition.

cachyos-installation-6.png

Create the EFI partition first. For GRUB, 1 GB is recommended, with the fat32 file system, mounted at /boot/efi, and the boot flag checked.

cachyos-installation-7.png

Next, use the remaining space for the system partition. Just set the mount point to / and leave everything else as default — adjust the size if needed. The default btrfs file system is recommended; CachyOS will set up subvolumes automatically. You can search for a swap partition tutorial if you want, but CachyOS uses zram by default, and you can also use a swap file instead of a dedicated partition, so I don’t recommend a swap partition.

cachyos-installation-8.png

Next, choose a desktop. The only ones I know of are KDE (the default), GNOME, Niri, and Hyprland. I prefer tiling window managers (Niri, Hyprland), and I heard Niri is a bit more stable than Hyprland, so I chose Niri. Pick whatever you like.

cachyos-installation-9.png

Select packages as needed (usually no changes required). I wanted Chrome, so I unchecked Firefox.

cachyos-installation-10.png

Finally, set up the account and password, then start the installation.

cachyos-installation-11.png

Configuration and Tuning

It’s been almost a month, so I’ve forgotten some of the configuration details. I’ll write down whatever comes to mind and add more later.

For configuration questions, check ArchWiki, or install an agent tool and let AI help you configure. Just don’t let the AI go wild and break your system — you can have it give you the steps and walk through them manually.

CachyOS uses fish as the default shell. You can switch to anything you like; I switched to zsh since I’m more used to it.

First, the update command:

1
sudo pacman -Syu

Snapshots

When you choose btrfs as the file system, CachyOS installs the btrfs assistant and snapper (for system snapshots) by default. You can open the btrfs assistant to adjust the snapshot settings. By default, snapshots are only created when installing, upgrading, or removing packages.

archlinuxcn Repo

CachyOS automatically picks suitable mirrors for your region, but the archlinuxcn repo is not enabled by default. I recommend adding it.

1
sudo vim /etc/pacman.conf

Add the following at the end:

1
2
3
4
5
6
[archlinuxcn]
Server = https://mirrors.ustc.edu.cn/archlinuxcn/$arch
Server = https://mirrors.tuna.tsinghua.edu.cn/archlinuxcn/$arch
Server = https://mirrors.hit.edu.cn/archlinuxcn/$arch
Server = https://repo.huaweicloud.com/archlinuxcn/$arch
Server = https://repo.archlinuxcn.org/$arch

One Server line is enough — pick whichever you like. Then install archlinuxcn-keyring and refresh the package database:

1
2
sudo pacman -S archlinuxcn-keyring
sudo pacman -Syu

yay

I recommend installing yay (an AUR helper). Search for details if you’re not familiar with it.

1
sudo pacman -S yay

Note that you don’t need sudo in front of yay commands. After installing yay, I barely used pacman manually anymore.

Daily updates become:

1
yay -Syu

Here’s the general difference between packages with no suffix, with -bin, and with -git. I recommend the -bin versions:

  • No suffix: downloads the source tarball of the official release and builds it locally
  • -bin: downloads the prebuilt binary of the official release — no local build needed
  • -git: downloads the latest source from the git repository and builds it locally

Some packages without -bin still install the official prebuilt binary, such as closed-source software (e.g. linuxqq).

Network Issues

One painful issue is that AUR downloads can be slow or fail entirely, since source packages and prebuilt binaries are downloaded from GitHub. I won’t go into detail here — do your own research if needed.

CachyOS Hello

This app starts automatically on first boot and has some useful features. Click Apps/Tweaks.

cachyos-hello-1.png

I won’t go into detail on the tweaks section — you can search with AI and enable what you need.

For utilities, the first three are the ones I usually use.

cachyos-hello-2.png

QQ

Install it with:

1
yay -S linuxqq

Since it’s built with Electron, it has some issues on Linux. It starts under XWayland by default, and when I type too fast with the input method, characters get dropped. The fix is to run it with Wayland — configure ~/.config/qq-flags.conf and add the following:

1
2
3
--ozone-platform=wayland
--enable-wayland-ime
--wayland-text-input-version=3

VS Code

Install it with:

1
yay -S visual-studio-code-bin

On my Niri desktop, the keyring service isn’t detected automatically (other apps seem to have the same problem). Editing ~/.vscode/argv.json and manually setting password-store to gnome-libsecret fixed it.

Clipboard

Install wl-clip-persist to fix the issue where copied content becomes unavailable after you close the source application.

Install comalot-clipsync-git to fix the issue where content copied in X11 applications doesn’t sync to Wayland.

1
yay -S wl-clip-persist comalot-clipsync-git

Remember to set up autostart. For wl-clip-persist, I use Niri’s autostart with spawn-at-startup "wl-clip-persist" "--clipboard" "regular". For comalot-clipsync-git, use systemctl --user enable --now clipsync.

Input Method

I use fcitx5 + fcitx5-rime + rime-ice.

1
yay -S fcitx5 fcitx5-rime fcitx5-configtool fcitx5-gtk fcitx5-qt rime-ice-git

My ~/.local/share/fcitx5/rime/default.custom.yaml looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
patch:
  # Just enable this line to use rime-ice's default configuration
  __include: rime_ice_suggestion:/
  # The following is optional and for reference only.
  # To customize a specific recipe, use its <recipe>.custom.yaml, e.g. rime_ice.custom.yaml
  __patch:
    menu/page_size: 8
    key_binder/select_first_character: "comma"
    key_binder/select_last_character: "period"
    key_binder/bindings/+:
      - { when: paging, accept: bracketleft, send: Page_Up }
      - { when: has_menu, accept: bracketright, send: Page_Down }

You also need to configure the environment variables. Edit ~/.config/environment.d/ime-env.conf and save:

1
2
3
4
QT_IM_MODULES="wayland;fcitx;ibus"
QT_IM_MODULE="fcitx"
XMODIFIERS="@im=fcitx"
SDL_IM_MODULE="fcitx"

Configure ~/.config/gtk-3.0/settings.ini and ~/.config/gtk-4.0/settings.ini and save:

1
2
[Settings]
gtk-im-module=fcitx

You can also run fcitx5-diagnose to troubleshoot input method issues.

To commit the raw string with shift while typing, open fcitx5-configtool, select 中州韵 (Rime), open its configuration, and set the behavior when switching input methods to “commit the raw string”.

fcitx5-configtool.png

Fonts

Here are the fonts and configuration I use — just for reference, feel free to adjust.

1
yay -S inter-font noto-fonts-cjk noto-fonts-emoji ttf-sarasa-gothic ttf-lxgw-wenkai ttf-jetbrains-mono-nerd ttf-caladea

Configure ~/.config/fontconfig/fonts.conf:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>

  <match target="font">
    <edit name="antialias" mode="assign"><bool>true</bool></edit>
  </match>

  <alias binding="strong">
    <family>sans-serif</family>
    <prefer>
      <family>Inter</family>
      <family>更纱黑体 UI SC</family>
      <family>更纱黑体 SC</family>
      <family>思源黑体 CN</family>
      <family>Noto Sans CJK SC</family>
    </prefer>
  </alias>

  <alias binding="strong">
    <family>serif</family>
    <prefer>
      <family>霞鹜文楷</family>
      <family>Noto Serif CJK SC</family>
    </prefer>
  </alias>

  <alias binding="strong">
    <family>monospace</family>
    <prefer>
      <family>JetBrainsMonoNL Nerd Font</family>
      <family>JetBrainsMonoNL Nerd Font Mono</family>
      <family>Sarasa Term SC</family>
      <family>等距更纱黑体 SC</family>
      <family>Sarasa Fixed SC</family>
    </prefer>
  </alias>

  <match target="pattern">
    <test name="lang" compare="contains"><string>zh</string></test>
    <edit name="family" mode="append" binding="strong"><string>更纱黑体 SC</string></edit>
  </match>

</fontconfig>

Configure /etc/fonts/conf.d. Every file in it is a symlink — by default there should be 41 of them pointing into /usr/share/fontconfig/conf.default, and I added 2 more from /usr/share/fontconfig/conf.avail. The command is:

1
2
3
4
sudo ln -s \
/usr/share/fontconfig/conf.avail/10-sub-pixel-rgb.conf \
/usr/share/fontconfig/conf.avail/70-no-bitmaps-except-emoji.conf \
/etc/fonts/conf.d/

The complete set of symlinks looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
10-hinting-slight.conf -> /usr/share/fontconfig/conf.default/10-hinting-slight.conf
10-powerline-symbols.conf -> /usr/share/fontconfig/conf.default/10-powerline-symbols.conf
10-scale-bitmap-fonts.conf -> /usr/share/fontconfig/conf.default/10-scale-bitmap-fonts.conf
10-sub-pixel-rgb.conf -> /usr/share/fontconfig/conf.avail/10-sub-pixel-rgb.conf
10-symbols.conf -> /usr/share/fontconfig/conf.default/10-symbols.conf
10-yes-antialias.conf -> /usr/share/fontconfig/conf.default/10-yes-antialias.conf
11-lcdfilter-default.conf -> /usr/share/fontconfig/conf.default/11-lcdfilter-default.conf
20-unhint-small-dejavu-lgc-sans.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-lgc-sans.conf
20-unhint-small-dejavu-lgc-sans-mono.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-lgc-sans-mono.conf
20-unhint-small-dejavu-lgc-serif.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-lgc-serif.conf
20-unhint-small-dejavu-sans.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-sans.conf
20-unhint-small-dejavu-sans-mono.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-sans-mono.conf
20-unhint-small-dejavu-serif.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-dejavu-serif.conf
20-unhint-small-vera.conf -> /usr/share/fontconfig/conf.default/20-unhint-small-vera.conf
30-metric-aliases.conf -> /usr/share/fontconfig/conf.default/30-metric-aliases.conf
40-nonlatin.conf -> /usr/share/fontconfig/conf.default/40-nonlatin.conf
45-generic.conf -> /usr/share/fontconfig/conf.default/45-generic.conf
45-latin.conf -> /usr/share/fontconfig/conf.default/45-latin.conf
46-noto-sans.conf -> /usr/share/fontconfig/conf.default/46-noto-sans.conf
46-noto-serif.conf -> /usr/share/fontconfig/conf.default/46-noto-serif.conf
48-guessfamily.conf -> /usr/share/fontconfig/conf.default/48-guessfamily.conf
48-spacing.conf -> /usr/share/fontconfig/conf.default/48-spacing.conf
49-sansserif.conf -> /usr/share/fontconfig/conf.default/49-sansserif.conf
50-user.conf -> /usr/share/fontconfig/conf.default/50-user.conf
51-local.conf -> /usr/share/fontconfig/conf.default/51-local.conf
57-dejavu-sans.conf -> /usr/share/fontconfig/conf.default/57-dejavu-sans.conf
57-dejavu-sans-mono.conf -> /usr/share/fontconfig/conf.default/57-dejavu-sans-mono.conf
57-dejavu-serif.conf -> /usr/share/fontconfig/conf.default/57-dejavu-serif.conf
58-dejavu-lgc-sans.conf -> /usr/share/fontconfig/conf.default/58-dejavu-lgc-sans.conf
58-dejavu-lgc-sans-mono.conf -> /usr/share/fontconfig/conf.default/58-dejavu-lgc-sans-mono.conf
58-dejavu-lgc-serif.conf -> /usr/share/fontconfig/conf.default/58-dejavu-lgc-serif.conf
60-generic.conf -> /usr/share/fontconfig/conf.default/60-generic.conf
60-latin.conf -> /usr/share/fontconfig/conf.default/60-latin.conf
62-caladea.conf -> /usr/share/fontconfig/conf.default/62-caladea.conf
62-carlito.conf -> /usr/share/fontconfig/conf.default/62-carlito.conf
65-fonts-persian.conf -> /usr/share/fontconfig/conf.default/65-fonts-persian.conf
65-nonlatin.conf -> /usr/share/fontconfig/conf.default/65-nonlatin.conf
66-noto-sans.conf -> /usr/share/fontconfig/conf.default/66-noto-sans.conf
66-noto-serif.conf -> /usr/share/fontconfig/conf.default/66-noto-serif.conf
69-unifont.conf -> /usr/share/fontconfig/conf.default/69-unifont.conf
70-no-bitmaps-except-emoji.conf -> /usr/share/fontconfig/conf.avail/70-no-bitmaps-except-emoji.conf
80-delicious.conf -> /usr/share/fontconfig/conf.default/80-delicious.conf
90-synthetic.conf -> /usr/share/fontconfig/conf.default/90-synthetic.conf

After configuring, refresh the font cache with fc-cache -fv.

Closing Thoughts

That’s about all I can think of. Other configuration — like Niri desktop theming, noctalia v5, terminals (I use ghostty), and various CLI tools — I haven’t covered, since those are all personal preference. Refer to the official docs and combine them with AI for configuration.

Finally, here’s a screenshot of my desktop:

cachyos-desktop.png