Coalstack on Linux

Coalstack on Linux

The Linux build is experimental. The app is the same one Windows users get. It manages the same server files, streams the same console, runs the same backups and automations. Most of this page is about the parts that are different or rough.

If you want the full feature walkthrough, read the main Documents page. Everything there applies on Linux unless this page says otherwise.

Running on a headless server is the setup we test most. The app starts with --headless (or COALSTACK_HEADLESS=1), keeps servers, backups and Conduit working with no window, and stops servers cleanly when systemd sends it a stop signal.

Installing

Two packages are on the Download page, under the Linux tab.

• .deb for Debian and Ubuntu. Install it with sudo apt install ./coalstack_*_amd64.deb. This one registers the app properly with your desktop.
• .AppImage for anything else. Run chmod +x coalstack_*.AppImage and then start it. Nothing gets installed system wide.

Both need a fairly recent system: 64-bit, glibc 2.35 or newer, and WebKitGTK 4.1 (libwebkit2gtk-4.1-0). In practice that means Ubuntu 22.04 or later, Debian 12 or later, Fedora 36 or later, or a rolling release. Older systems will not run it.

The build is not signed. There is no Windows style warning screen, it just runs.

Features that do not work

These rely on Windows tools and are off on Linux.

• Firewall rules. The Networking page can ask Windows to add a firewall rule for your server port. On Linux that button does nothing useful. Open the port yourself, for example sudo ufw allow 25565.
• Run as administrator. The "elevate" prompt that shows up around the firewall and UPnP features tries to launch a Windows tool. It fails on Linux. You do not need it anyway.
• Auto update for the .deb. Your package manager owns that install, so the in-app updater leaves it alone. Grab the new .deb from the site when there is a release. The AppImage does update itself.
• The RAM type label. The Performance page shows your CPU name and total RAM. It does not show "DDR4" or "DDR5" on Linux. That reading came from a Windows-only query.

Things that often need a fix

• coalstack:// links from the AppImage. Clicking "Connect this app" on the website, or opening an invite link, hands off to the app through a coalstack:// URL. The .deb sets this up. The AppImage does not, unless you integrate it with something like AppImageLauncher. From the AppImage, sign in inside the app instead of using the website hand-off.
• Rust game servers. Rust support is experimental on every platform. On Linux there is an extra catch: SteamCMD ships a 32-bit helper, so you need sudo apt install lib32gcc-s1 (and sometimes libc6-i386). Without it the install step fails.
• The tray icon on GNOME. Stock GNOME hides tray icons. You need the AppIndicator extension to see Coalstack's. KDE, XFCE, Cinnamon and MATE show it fine. This matters because of the next point.
• Closing the window on GNOME. When a server is running and you close the window, the app hides to the tray instead of quitting. If there is no tray, the window is gone and you cannot bring it back. Quit fully from the tray menu, or do not close the window while a server runs, or add the AppIndicator extension.
• Docker mode. This works on Linux, and Linux is a good place to run it. You do have to set Docker up yourself first: install it, then add your user to the docker group and log back in. There is no Docker Desktop step like on Windows.

Smaller things that might bite

• The interface uses a different browser engine. On Windows the app draws its UI with the same engine as Edge. On Linux it uses WebKitGTK, which is closer to Safari. Almost everything looks the same. A panel here or there might be slightly off, and blur or see-through effects are the most likely to look wrong or drop out.
• Saved keys may not survive a reboot. Your Anthropic API key, your website login, and per-server RCON and S3 keys are kept in the Linux kernel keyring. That store is not always kept after a reboot. If a key is gone after you restart the machine, just enter it again. RCON passwords regenerate on their own.
• UPnP is less reliable with more than one network. If the machine has a VPN up, or both Wi-Fi and Ethernet, the automatic port-forward can send its request out the wrong interface and miss the router. Forwarding the port by hand in your router always works.
• The title bar is custom. Coalstack draws its own title bar rather than using the system one. Dragging the window works. Resizing from an edge, and tiling or snapping, can feel a little off on some Wayland setups.
• Modded servers copied from Windows. A Forge or NeoForge server folder made on Windows carries a launch file that uses Windows path separators. It will not start on Linux. Make the server fresh on Linux with the Setup Wizard instead. Vanilla, Paper and Fabric folders copy over with no problem.
• "Open folder" and "open in browser". These call xdg-open. Any normal desktop has it. A bare server install might not, in which case install xdg-utils.

What works well

The core of the app is solid on Linux:

• Creating, cloning and running servers
• The live console, chat log and Send Command box
• RCON, player lists, whitelist, bans and operators
• Local backups, the secondary copy, and S3 cloud backups
• Automations, scheduled commands and scheduled restarts
• Conduit remote control, and Discord or webhook alerts
• The live map, the Marketplace, and the Auto Debugger
• Java auto-download, DuckDNS and Cloudflare dynamic DNS
• Headless mode, and a clean shutdown on systemctl stop

Where Coalstack keeps its files

The app data folder is ~/.local/share/com.kylea.coalstack (or wherever $XDG_DATA_HOME points). Downloaded Java versions, SteamCMD, and the app's own settings live there. Config sits under ~/.config/com.kylea.coalstack.

Your server folders are wherever you told the Setup Wizard to put them. They are normal directories. Nothing about them is Coalstack-specific, so you can move, back up, or open them like any other folder.

Reporting a bug

Hit something not on this list? Tell us on Discord. Say which package you used (.deb or .AppImage), your distro and version, and your desktop (GNOME, KDE, and so on). If the app logged anything, the console output helps.