Skip to content

Instantly share code, notes, and snippets.

@micahlt

micahlt/CavalryOnLinux.md

Created April 18, 2026 09:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save micahlt/3c97f834adaf688fe18344c0f546466c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save micahlt/3c97f834adaf688fe18344c0f546466c to your computer and use it in GitHub Desktop.
Download ZIP
Raw
CavalryOnLinux.md

CavalryOnLinux

A guide to running the Cavalry motion graphics software on Linux using Wine.

This guide has been tested exclusively on Wine 11.

Initial setup

Set up a new prefix

Create a new Wine prefix by creating a folder somewhere on your computer, preferably ~/.cavalry. Within that folder, run WINE_PREFIX=~/.cavalry winetricks which should initialize the prefix.

Install fonts and graphics improvements

In Winetricks, select "Install a Windows DLL or component", then check dxvk and click okay. After it is installed, click "Install a font" and check the corefonts option. Go through all of the font installs. Once they are complete, click "Change settings" and select the fontsmooth=rgb option. These improvements make Cavalry run much smoother.

Override DLLs

Open winecfg with WINEPREFIX=~/.cavalry winecfg

Go to the Libraries tab.

Under "New override for library," type icuuc and click Add. Do the same for icuin. Ensure they are both set to (Native, Builtin).

Install Cavalry

Run the Cavalry installer .msi file through Winetricks or through the command line.

Fix Canva sign-in

Create a new .desktop file to define the Cavalry URI protocol. With the text editor of your choice, create a new file at ~/.local/share/applications/cavalry-handler.desktop. The contents should look like the following:

[Desktop Entry]
Name=Cavalry Protocol Handler
Exec=env WINEPREFIX="/home/micahlt/.cavalry" wine "/home/micahlt/.cavalry/drive_c/Program Files/Cavalry/Cavalry.exe" "%u"
Type=Application
Terminal=false
NoDisplay=true
MimeType=x-scheme-handler/cavalry;

Then run:

update-desktop-database ~/.local/share/applications
xdg-settings set default-url-scheme-handler cavalry ~/.local/share/applications/cavalry-handler.desktop

Run the app

You should be good to run Cavalry, which you should be able to find from your system menu. Canva sign-in should work properly, and you should have GPU acceleration.

@kabaww
Copy link
Copy Markdown

kabaww commented Apr 19, 2026

The wine settings work perfectly! 👍️

I just had to create a wrapper bash script to launch Cavalry since i was getting wine: invalid directory "/home/kabaww/.cavalry" in WINEPREFIX: not an absolute path when using env in the .desktop entry

# ~/.local/bin/cavalry-launcher

#!/bin/bash
export WINEPREFIX="/home/kabaww/.cavalry"
exec wine "/home/kabaww/.cavalry/drive_c/Program Files/Cavalry/Cavalry.exe" "$1"

make sure cavalry-launcher is executable: chmod +x ~/.local/bin/cavalry-launcher

[Desktop Entry]
Name=Cavalry Protocol Handler
Exec=/home/kabaww/.local/bin/cavalry-launcher %u
Type=Application
Terminal=false
NoDisplay=true
MimeType=x-scheme-handler/cavalry;

@Flow-dev0
Copy link
Copy Markdown

Flow-dev0 commented Apr 19, 2026

Any luck trying to get this to work on flatpak version of lutris. Old version works but can't get the new canva based one working. Attempting to login with the mimetype added to the .desktop just spawns a brand new instance of the app.

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 20, 2026 •
edited
Loading

Any luck trying to get this to work on flatpak version of lutris. Old version works but can't get the new canva based one working. Attempting to login with the mimetype added to the .desktop just spawns a brand new instance of the app.

@Flow-dev0 Lutris has a limitation that doesn't allow you to pass arguments directly to the software inside it. You have to either use raw Wine or use a launcher that supports command-line args.

@xanderazuaje
Copy link
Copy Markdown

xanderazuaje commented Apr 20, 2026

I'm following this exact guide with raw wine and it also spawn a new instance of the app. I'm using arch with i3 btw

@jimisol
Copy link
Copy Markdown

jimisol commented Apr 20, 2026

I've also followed this guide exactly, and I also end up with a new instance of the app. I'm using Debian, with wine 11. I'd love to be able to get this to work, it feels like I'm so close!

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 20, 2026 •
edited
Loading

@xanderazuaje @jimisol okay, that's odd - try this instead. Delete the cavalry-handler.desktop file. Then find the existing Cavalry.desktop file that should have been auto-generated by the Wine install (usually in ~/.local/share/applications/wine). Modify the existing Exec line. Change the path to the executable from the .lnk file to the actual .exe. Then add %u to the end, which should leave your line looking like this:

Exec=env "WINEPREFIX=/home/micahlt/.cavalry" wine "C:\\\\Program Files\\\\Cavalry\\\\Cavalry.exe" %u

After that, add the MimeType line at the end of the Cavalry.desktop file:

MimeType=x-scheme-handler/cavalry;text/html;

And then run:

update-desktop-database ~/.local/share/applications
xdg-settings set default-url-scheme-handler cavalry ~/.local/share/applications/wine/Cavalry.desktop

@azacio
Copy link
Copy Markdown

azacio commented Apr 20, 2026 •
edited
Loading

Any luck trying to get this to work on flatpak version of lutris. Old version works but can't get the new canva based one working. Attempting to login with the mimetype added to the .desktop just spawns a brand new instance of the app.

@Flow-dev0 Lutris has a limitation that doesn't allow you to pass arguments directly to the software inside it. You have to either use raw Wine or use a launcher that supports command-line args.

I'm trying to launch Cavalry using Bottles, which does support command line arguments and initially runs the app just fine. But I'm having the same issue as many others: the return journey from the auth website spawns a new instance of the app instead of passing the auth details to the existing one.

Do you know which args Cavalry is looking for? I assumed it's the cavalry:// URL found in the browser console, but could be completely wrong!

(Unfortunately I can't install raw WINE because I'm on an immutable distro, although if there's a way without overlaying it then I'm all ears!)

@Flow-dev0
Copy link
Copy Markdown

Flow-dev0 commented Apr 20, 2026

Lutris has a limitation that doesn't allow you to pass arguments directly to the software inside it. You have to either use raw Wine or use a launcher that supports command-line args.

Appreciate the response I'm not opposed to switching to plain wine I'd just prefer it not to be my first choice. Still stumped on my side. Lutris itself, via the GUI "Wine configuration" tab does allow me to address the "icuin", "icuuc" part of the equation, that's the only bit of progress I've made since the last update. In theory it shouldn't matter but could you mention what DE and browser base you were using? It got me curious because of other people facing same issue as me despite using plain wine. I'm on KDE running a Firefox based browser.

Regarding

(Unfortunately I can't install raw WINE because I'm on an immutable distro, although if there's a way without overlaying it then I'm all ears!

Since you mentioned layering I take it that you running an atomic spin of fedora, while it doesn't address the cavalry specific issue we all facing you could certainly make use of toolbox/distrobox to achieve your "raw Wine" experience

@haniffs
Copy link
Copy Markdown

haniffs commented Apr 21, 2026 •
edited
Loading

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?

2026-04-21.12-27-37.mp4

@xanderazuaje
Copy link
Copy Markdown

xanderazuaje commented Apr 21, 2026

@micahlt I managed to run it passing the token through bash. I did the other steps, but there's no .l/s/a/wine in my computer, so no direct access. Quite odd

@azacio
Copy link
Copy Markdown

azacio commented Apr 21, 2026

(Unfortunately I can't install raw WINE because I'm on an immutable distro, although if there's a way without overlaying it then I'm all ears!

Since you mentioned layering I take it that you running an atomic spin of fedora, while it doesn't address the cavalry specific issue we all facing you could certainly make use of toolbox/distrobox to achieve your "raw Wine" experience

Knew I was missing something, thanks! Unfortunately, the same issue happens if I try to launch Cavalry in a container using raw Wine.

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 21, 2026

Appreciate the response I'm not opposed to switching to plain wine I'd just prefer it not to be my first choice. Still stumped on my side. Lutris itself, via the GUI "Wine configuration" tab does allow me to address the "icuin", "icuuc" part of the equation, that's the only bit of progress I've made since the last update. In theory it shouldn't matter but could you mention what DE and browser base you were using? It got me curious because of other people facing same issue as me despite using plain wine. I'm on KDE running a Firefox based browser.

I was able to successfully log in on GNOME using Zen (Firefox-based).

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 21, 2026

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?

I've encountered this issue as well - I believe it can probably be worked around using Wine's virtual desktop feature, but I haven't had a chance to try it yet. Hopefully someone smarter than I will come along and start working on some compatibility fixes for Cavalry in Wine.

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 21, 2026

@micahlt I managed to run it passing the token through bash. I did the other steps, but there's no .l/s/a/wine in my computer, so no direct access. Quite odd

@xanderazuaje What distro are you running? What Wine version? And how did you install Wine? Is there any .desktop file for Cavalry (does Cavalry show up in your launcher)?

@Flow-dev0
Copy link
Copy Markdown

Flow-dev0 commented Apr 21, 2026 •
edited
Loading

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?

There's no singular reason for it and while I'm by no means a wizard with wine. Common reasons for occurrence I've experienced range from GPU-acceleration configuration issues (dxvk settings etc). not directly related to cavalry but same scenario see the attached link AffinityOnLinux Thread

If you happen to be using gnome + wayland i found their wayland implementation when using wine in particular to be lackluster I haven't tested gnome 50 so perhaps its resolved there (im on kde). If you still happen to have x11 and wayland then I encourage you to switch between the 2 to see if that your issue.

Incomplete windows font also tend to cause the issue (unlikely in this scenario given its not text element that's causing the bug but worth mentioning just in case)

While not the same version of cavalry I don't experience this black box issue on my wine 11 instances, so unlikely to be app related.

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 21, 2026 •
edited
Loading

Just tested with both the Wine virtual desktop and with X11 and experienced the exact same issue with connections. Seems likely to be a graphics issue, which is very much out of my wheelhouse unfortunately.

@Flow-dev0
Copy link
Copy Markdown

Flow-dev0 commented Apr 21, 2026

Just tested with Wine virtual desktop and experienced the exact same issue with connections. Seems likely to be a graphics issue, which is very much out of my wheelhouse unfortunately.

Virtual desktop is planned for obsolescence unfortunately. Consider giving gamescope a try. If you able to test the other things i mentioned let me know.

@kabaww
Copy link
Copy Markdown

kabaww commented Apr 22, 2026 •
edited
Loading

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?
2026-04-21.12-27-37.mp4

Yep I also ran into this issue. Solved it by just using api.connect() via Javascript. Not ideal but good enough for me!

https://cavalry.studio/docs/tech-info/scripting/api-module/#connect

@haniffs
Copy link
Copy Markdown

haniffs commented Apr 23, 2026

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?
2026-04-21.12-27-37.mp4

Yep I also ran into this issue. Solved it by just using api.connect() via Javascript. Not ideal but good enough for me!

https://cavalry.studio/docs/tech-info/scripting/api-module/#connect

Is it done via the console? It seems quite technical since I'm not into some coding things🫠

@kabaww
Copy link
Copy Markdown

kabaww commented Apr 23, 2026

I've successfully install and login to cavalry. but for the connection feature, it doesnt work at all, any solution for it?
2026-04-21.12-27-37.mp4

Yep I also ran into this issue. Solved it by just using api.connect() via Javascript. Not ideal but good enough for me!
https://cavalry.studio/docs/tech-info/scripting/api-module/#connect

Is it done via the console? It seems quite technical since I'm not into some coding things🫠

You can run any javascript in the Javascript Editor window

@erich-muller
Copy link
Copy Markdown

erich-muller commented Apr 23, 2026

​Hey everyone, thanks for the guide! I was having an issue on Zorin OS where following the tutorial almost worked, but after the browser redirected the auth token, it kept opening a second Cavalry window instead of completing the login on the original one. (I also tried modifying the Exec to use wine start, but that just resulted in a stack overflow loop).

Gemini helped me to find out what was happening. ​It turns out the root cause is related to the Working Directory breaking the IPC (Inter-Process Communication) between the Wine instances. When the system calls the handler, it executes from the home directory, so the second instance fails to locate the original process to pass the token and decides to open a fresh window.

​To fix this, you just need to explicitly declare the Path variable in the .desktop file and use absolute paths instead of $USER or ~/.
​Here is the .desktop configuration that finally worked perfectly for me:

[Desktop Entry]
Name=Cavalry Protocol Handler
Exec=env WINEPREFIX="/home/YOUR_USERNAME/.wine" wine "/home/YOUR_USERNAME/.wine/drive_c/Program Files/Cavalry/Cavalry.exe" "%u"
Path=/home/YOUR_USERNAME/.wine/drive_c/Program Files/Cavalry/
Type=Application
Terminal=false
NoDisplay=true
MimeType=x-scheme-handler/cavalry;

Steps to apply:
​1. Replace YOUR_USERNAME with your actual Linux user folder name.
​2. Update the database: update-desktop-database ~/.local/share/applications
3. ​Important: Kill any ghost Wine processes before testing again by running wineserver -k in the terminal, otherwise the duplicated windows issue will persist from cache.

​Hope this helps anyone stuck on the same loop!

@azacio
Copy link
Copy Markdown

azacio commented Apr 23, 2026

@erich-muller THANK YOU SO MUCH! Your solution helped me to get to a working Cavalry! I took a bit of everyone's solutions in this thread, mixed them together and finally, after SIX DAYS of trying to make Cavalry work in Linux, it works!

Notes:

  1. I took @micahlt's suggestion to delete cavalry-handler.desktop and added the Mimetype line directly into the Cavalry.desktop file. I also changed the path to Cavalry in the Exec line to "C:\\\\Program Files\\\\Cavalry\\\\Cavalry.exe" %u.
  2. As @erich-muller suggested, I added the Path= line to the .desktop file.
  3. Running xdg-settings set default-url-scheme-handler cavalry ~/.local/share/applications/wine/Programs/Cavalry.desktop didn't work for me at first, producing an "application cannot be found" error. However, I shortened it to xdg-settings set default-url-scheme-handler cavalry Cavalry.desktop which executed without error. You can also verify that the mimetype was correctly set by examining the mimeinfo.cache file in the same folder as the .desktop file.
  4. Important: I moved the Cavalry.desktop file from ~/.local/share/applications/wine/Programs to the applications folder, then ran update-desktop-database ~/.local/share/applications and the xdg-settings command. This is what seemed to finally unlock the door. Previously, the handler was being set as wine-Programs-Cavalry.desktop which seemed a bit sus to me, so I decided to simplify that by moving the file.

I should also note that. as I mentioned earlier in this thread, I'm running an atomic Linux distro (Project Bluefin). Running in Bottles didn't work, running in a container didn't work, but overlaying Wine and Winetricks worked (rpm-ostree install wine winetricks for anyone who needs that). I know it's not the preferred way to do things, but whatever. I care more about doing stuff than distro ideology. (IMO Wine really, really should be part of the Bluefin images.)

And... breathe...

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 23, 2026

That's great to hear! I will test this myself and assuming everything works right, I will update this gist to contain these changes for future reference. Thanks for y'all's hard work trying to get this to work!

@azacio
Copy link
Copy Markdown

azacio commented Apr 24, 2026

Although the sign-in now works and I guess Cavalry does technically work, there is a known issue with connections (e.g. connecting a shape to a Duplicator). I tried messing with a few Wine render options but it seems there's something that Wine isn't translating between the Windows and Linux instructions.

I even tried Elemental Warrior Wine (which lets Affinity work on Linux), but that had... questionable results. 😅 Things like menus appearing in the middle of the screen, and the connector lines being offset away from the mouse cursor.

@PorkingMane
Copy link
Copy Markdown

PorkingMane commented Apr 25, 2026

We really need to find a way how to fix connection issue. I tried DXVK flags, virtual desktop, different WINEs but couldn't fix it at all

@micahlt
Copy link
Copy Markdown
Author

micahlt commented Apr 26, 2026

Very likely this will be an issue for someone with actual knowledge of Cavalry's architecture to build a patch or find a workaround for it. Possible a decompilation would help? Definitely depends on what technologies Cavalry is made with.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment