| title | Linux | |
|---|---|---|
| tags |
|
|
| updated | 2026-11-15 |
StarOrg Codex runs natively on Linux (x86_64). It does not need Wine: it reads and writes the game's files inside your Wine prefix directly. Builds come from Ubuntu 22.04, so any distro with glibc 2.35 or newer works (the CLI is a static musl binary and runs anywhere).
The fastest way to get the CLI on your PATH (and, with --app, the AppImage with a menu
entry), for your user only, without sudo:
curl -fsSL https://raw.githubusercontent.com/voidput/starorg-codex/main/scripts/install-linux.sh | sh -s -- --appRead the script first if you like (scripts/install-linux.sh); it is described under Installer script. Everything else on this page is the manual way.
x86_64 only. The summary for all platforms is in the README; per flavour on Linux:
| Flavour | Needs |
|---|---|
| AppImage | glibc 2.35+ and a fusermount3 or fusermount program: fuse3 on Arch, Debian, Ubuntu, Fedora and openSUSE (most desktops have it). The AppImage runtime has FUSE built in, so libfuse2 is not needed. No FUSE at all: --appimage-extract-and-run |
| .deb | Debian 12 or Ubuntu 22.04+; apt installs libwebkit2gtk-4.1-0 and libgtk-3-0, and recommends gstreamer1.0-plugins-good |
| .rpm | WebKitGTK 4.1 (webkit2gtk4.1 on Fedora, libwebkit2gtk-4_1-0 on openSUSE); recommends gstreamer1-plugins-good (Fedora) or gstreamer-plugins-good (openSUSE) |
| CLI tarball | Nothing: a static binary |
For Developer mode only:
- Sounds play through GStreamer and need its "good" plugins: Arch/CachyOS
gst-plugins-good, Debian/Ubuntugstreamer1.0-plugins-good, Fedoragstreamer1-plugins-good, openSUSEgstreamer-plugins-good. The .deb and .rpm pull them in as recommended packages (unless you turned recommends off). The AppImage cannot play sounds on most distros: it bundles GStreamer 1.20 (from Ubuntu 22.04) without plugins, and that core cannot load your system's plugins. Use the .deb, .rpm or a source build, or Export the sound instead. - The 3D model viewer needs WebGL 2 in WebKitGTK, which means a working GPU driver with
hardware acceleration. On some older WebKitGTK builds,
--safe-gpuandWEBKIT_DISABLE_COMPOSITING_MODE=1can turn WebGL off, see Troubleshooting.
All files are on the release page.
<v> is the version without the v, e.g. 0.3.0.
| AppImage | .deb | .rpm | CLI tarball | Build from source | |
|---|---|---|---|---|---|
| File | StarOrg.Codex_<v>_amd64.AppImage |
StarOrg.Codex_<v>_amd64.deb |
StarOrg.Codex-<v>-1.x86_64.rpm |
starorg-codex-v<v>-linux-x86_64.tar.gz |
this repo |
| For | Arch, CachyOS, Steam Deck, atomic distros, anything else | Debian, Ubuntu, Mint, Pop!_OS | Fedora, openSUSE, Nobara | Scripts, launch hooks, servers; every flavour's command line | Other CPUs, development |
| Contains | The app (starorg-codex-app) with WebKitGTK bundled |
/usr/bin/starorg-codex-app, menu entry, icons; uses the system libwebkit2gtk-4.1-0 |
Same as the .deb | starorg-codex (static) and LICENSE |
What you build |
| CLI included | No: add the CLI tarball | No: add the CLI tarball | No: add the CLI tarball | Yes | cargo build -p starorg-cli |
| Updates | In the app (Settings -> Network -> Check for updates, off by default): download, signature check, replace, restart (updates) | The app tells you; install the new .deb with apt | The app tells you; install the new .rpm with dnf/zypper | Download the new tarball (or rerun the installer script) | git pull and rebuild |
| Uninstall | Delete the file (and the menu entry, if you made one) | sudo apt remove star-org-codex |
sudo dnf remove star-org-codex |
Delete ~/.local/bin/starorg-codex and the starorg-strings link |
Delete the build |
Run Remove first. Uninstalling any flavour leaves the game as it is. To put the game back
to stock, use Remove in the app or starorg-codex remove --all before you uninstall.
All steps, hooks and data folders: uninstall.
| What | Where |
|---|---|
| Config (profiles, settings) | ${XDG_CONFIG_HOME:-~/.config}/starorg-codex/ |
Data (backups of game files, blueprints, update state app-update.json) |
${XDG_DATA_HOME:-~/.local/share}/starorg-codex/ |
| Cache (extracted game text, GameData; can be deleted, it is rebuilt) | ${XDG_CACHE_HOME:-~/.cache}/starorg-codex/ |
| Asset cache (Developer mode: decoded sounds, exported models, texture previews; 2 GB by default, Settings -> Advanced) | <cache>/assets/, or a StarOrg Codex asset cache subfolder of a folder you choose |
| MCP datasets (local MCP server, experimental) | <cache>/mcp/ |
| Webview storage (WebKitGTK, made by Tauri) | ~/.local/share/tools.starorg.codex/, ~/.cache/tools.starorg.codex/ |
Nothing of ours is stored in the game folder, so the RSI Launcher's "Verify files" cannot remove it. Delete these folders after uninstalling if you want everything gone; keep the data folder if you may still need a backup.
Until 0.3.0 everything was called starorg-strings: the CLI, the app binary
(starorg-strings-app), the release files, the folders above and the webview storage
(tools.starorg.strings). From 0.3.0:
- Folders move by themselves. The first start of the app or the CLI renames each
starorg-stringsfolder (andtools.starorg.strings) to its new name and says so once (Activity in the app, one line on stderr from the CLI). If a folder is on another drive it is copied, every file is checked, and the old one is kept. A start at the same time (app and a launch hook) waits for the other; nothing is moved twice. When a new folder already exists the old one is never touched: Activity (andstarorg-codex status/doctor) names it so you can delete it once you no longer need it. If a move fails the old folder stays in use and Activity says why. - The CLI keeps its old name for one release. The tarball and the installer script add a
starorg-stringslink tostarorg-codex; called by that name it works the same and prints one deprecation line. The link goes away in the release after 0.3. - Launch hooks: blocks written by 0.2 (
# >>> starorg-strings hook >>>) show as Outdated in Settings -> Launch hooks and instarorg-codex hook status. Install them again (the button, orstarorg-codex hook install --bin ~/.local/bin/starorg-codex): the old block is replaced in place, with a backup, and callsstarorg-codex. - Packages: the .deb/.rpm replace
/usr/bin/starorg-strings-appwith/usr/bin/starorg-codex-app(same package,star-org-codex). The installer script with--appreplaces the oldstarorg-strings-app.desktopmenu alias and icon. - Updates and links point at
github.com/voidput/starorg-codex; GitHub redirects the old address.
sudo apt install ./StarOrg.Codex_<v>_amd64.debThe ./ matters: without it apt looks for a package of that name online. apt pulls in
libwebkit2gtk-4.1-0 and libgtk-3-0. Ubuntu 22.04 / Debian 12 or newer. Start it from the
menu (StarOrg Codex) or run starorg-codex-app. Updating is the same command with the
newer file.
sudo dnf install ./StarOrg.Codex-<v>-1.x86_64.rpm # Fedora, Nobara
sudo zypper install ./StarOrg.Codex-<v>-1.x86_64.rpm # openSUSEThe package needs WebKitGTK 4.1 (webkit2gtk4.1 on Fedora, libwebkit2gtk-4_1-0 on
openSUSE); install it by hand if the package manager does not.
There is no AUR package yet. Use the AppImage:
sudo pacman -S --needed fuse3 # the AppImage mounts itself with fusermount3
mkdir -p ~/.local/bin
mv ~/Downloads/StarOrg.Codex_<v>_amd64.AppImage ~/.local/bin/StarOrg-Codex.AppImage
chmod +x ~/.local/bin/StarOrg-Codex.AppImage
~/.local/bin/StarOrg-Codex.AppImageWithout FUSE the AppImage can still run: StarOrg-Codex.AppImage --appimage-extract-and-run
(slower to start; it unpacks to a temp folder each time). The installer script with --app
does the steps above and adds a menu entry and icon. Keep the AppImage in a folder you own
(as here): the in-app update replaces the file in place.
On other distros the package is fuse3 too (Debian, Ubuntu, Fedora, openSUSE); the older
fuse / fuse2 package with fusermount also works. libfuse2 (libfuse2, libfuse2t64,
fuse-libs) is not needed: our AppImage uses the static
type2-runtime, which has FUSE built in.
Use the AppImage, in Desktop Mode on the Deck. The system folders are read-only, so do not use pacman, apt or dnf there; everything goes into your home folder:
- Open Konsole and run the installer script line from the top of this page (or download the AppImage in the browser, then right-click -> Properties -> Permissions -> Is executable).
- Start StarOrg Codex from the application menu (category Utilities), or from Konsole:
~/.local/bin/StarOrg-Codex.AppImage. - If it does not start, run it from Konsole with
--appimage-extract-and-runand see Troubleshooting.
Each release has SHA256SUMS over every file and a build provenance attestation per file.
In the folder with your downloads:
sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify StarOrg.Codex_<v>_amd64.AppImage -R voidput/starorg-codexsha256sum must print OK for each file you have. gh attestation verify (GitHub CLI) proves
the file was built by this repo's release workflow. The installer script always checks
SHA256SUMS and refuses a file that does not match.
None of the app packages include starorg-codex; it is the separate CLI tarball. You need it
for the launch hooks and for scripts. The usual mistake is to extract it in Downloads and then
get starorg-codex: command not found: the shell only finds programs in the folders listed in
PATH.
tar -xzf starorg-codex-v<v>-linux-x86_64.tar.gz
mkdir -p ~/.local/bin
install -m 755 starorg-codex-v<v>-linux-x86_64/starorg-codex ~/.local/bin/Check that the shell finds it:
command -v starorg-codex # should print /home/<you>/.local/bin/starorg-codex
starorg-codex --version
starorg-codex doctor # installs, paths, casing, other tools' traces; changes nothingIf command -v prints nothing, ~/.local/bin is not on your PATH. Many distros add it only
at login and only if the folder existed then, so logging out and back in may be enough.
Otherwise add it for your shell (check with echo $SHELL):
| Shell | Run once |
|---|---|
| bash | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc |
| zsh | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc |
| fish | fish_add_path ~/.local/bin |
Then open a new terminal. Programs started from a launcher (Lutris, the LUG hooks) may not read your shell's startup files, so give the hooks the full path, see Launch hooks.
Star Citizen on Linux lives inside a Wine prefix (LUG Helper, Lutris or your own). The app and the CLI look for it in this order and list every install they find:
--game-dir <folder>(CLI only; skips the search).--prefix <prefix>(CLI only), else theWINEPREFIXenvironment variable.- The LUG Helper config:
~/.config/starcitizen-lug/winedir.conf(the prefix) andgamedir.conf(the game folder). - The default prefixes
~/Games/star-citizenand~/games/star-citizen(LUG Helper and the Lutris installer use the first).
For each prefix (a folder with drive_c/ and system.reg) it reads the RSI Launcher's logs
(drive_c/users/<you>/AppData/Roaming/rsilauncher/logs/log.log and log.old.log), which name
the library folder on any drive, then tries the default
drive_c/Program Files/Roberts Space Industries/StarCitizen. Windows paths from the log are
mapped C: -> <prefix>/drive_c, Z: -> /, other letters through <prefix>/dosdevices/.
Symlinked paths (for example ~/games/star-citizen pointing to /mnt/games/star-citizen) are
resolved and listed once.
If your prefix is somewhere else, point it at the game:
- App: in the setup wizard choose Browse... and pick the folder that contains
LIVE(orPTU,HOTFIX, ...), normally<prefix>/drive_c/Program Files/Roberts Space Industries/StarCitizen. A Lutris prefix is shown in Lutris under the game's Configure -> Game options -> Wine prefix. Hidden folders: press Ctrl+H in the file picker. - App, alternative: start it with the prefix set, e.g.
WINEPREFIX=/path/to/prefix starorg-codex-app(or the AppImage path). - CLI:
starorg-codex --prefix /path/to/prefix channels, orstarorg-codex --game-dir "/path/to/prefix/drive_c/Program Files/Roberts Space Industries/StarCitizen" channels.
starorg-codex channels lists installs and channels with branch and game version;
starorg-codex doctor also says how each install was found.
A few rules the code enforces on Linux:
- Not as root. Apply refuses to run as root (
refusing to run as root or elevated), so never usesudo starorg-codex. - Casing. The prefix is case-sensitive but Wine is not. We write into the folders as they
exist (
Data/,USER.cfg) and stop with an error if two spellings exist side by side. - Game running. A running
StarCitizen.exein the same prefix and channel blocks an apply to that channel (found through/proc); quit the game first. Other channels are not blocked.
With LUG Helper's launch scripts, starorg-codex hook install adds a small block to
sc-prelaunch.sh and sc-postexit.sh in the prefix (backed up first) so every set-up channel
is re-applied before the game starts and blueprints are read after it exits. Because the
launcher may not have your shell's PATH, install the block with the absolute path:
starorg-codex hook install --bin ~/.local/bin/starorg-codex
starorg-codex hook statushook uninstall removes the block again. A block written by 0.2 (old starorg-strings
markers) is reported as outdated and hook install replaces it in place. Use --prefix (or --prelaunch-script /
--postexit-script) when the prefix is not found automatically.
Needs the Rust toolchain from rust-toolchain.toml (rustup installs it) and, for the app,
Node 24 and the WebKitGTK development packages (Debian/Ubuntu: libwebkit2gtk-4.1-dev libsoup-3.0-dev libgtk-3-dev librsvg2-dev).
git clone https://github.com/voidput/starorg-codex && cd starorg-codex
cargo build --release --locked -p starorg-cli # CLI: target/release/starorg-codex
install -m 755 target/release/starorg-codex ~/.local/bin/
cd app && npm ci && npx tauri build --bundles deb # app: target/release/bundle/A self-built app shows new versions but never installs them (download only).
scripts/install-linux.sh (POSIX sh, needs curl, sha256sum, tar):
| Option | Does |
|---|---|
| (none) | Latest release: download the CLI tarball and SHA256SUMS, check the checksum, install starorg-codex to ${XDG_BIN_HOME:-~/.local/bin} |
--app |
Also the AppImage as ~/.local/bin/StarOrg-Codex.AppImage, a menu entry ~/.local/share/applications/starorg-codex-app.desktop and its icon; warns if neither fusermount3 nor fusermount is found |
--version X.Y.Z |
That release instead of the latest |
--bin-dir DIR |
Install somewhere else |
--dry-run |
Resolve the release, check the files exist, print what would happen; writes nothing |
--uninstall |
Remove the CLI (with --app also the AppImage, menu entry and icon). Settings, backups and the game are kept |
It never uses sudo, refuses to run as root, writes only below your home (temp files go to
~/.cache and are removed) and stops if a checksum does not match or the release has no
SHA256SUMS yet (a release is complete a few minutes after it appears). When the install folder
is not on your PATH it prints the exact line to add for your shell (bash, zsh, fish or
~/.profile). STARORG_REPO=owner/name installs from a fork.
| Symptom | What to do |
|---|---|
starorg-codex: command not found |
The CLI is not in a PATH folder. Install it to ~/.local/bin and add that folder to PATH (above); or call it by full path |
| Hooks do nothing although the CLI works in a terminal | The launcher has a different PATH: starorg-codex hook install --bin ~/.local/bin/starorg-codex |
AppImage: nothing happens, or No suitable fusermount binary found on the $PATH |
Install fuse3 (it provides fusermount3), or run it with --appimage-extract-and-run. libfuse2 does not help |
| AppImage: "Permission denied" | chmod +x StarOrg-Codex.AppImage; also check the folder is not on a noexec mount |
| AppImage crashes at start on a rolling distro (Arch, CachyOS), Wayland errors in the terminal | A library bundled in the AppImage clashes with newer system ones. Try GDK_BACKEND=x11 ./StarOrg-Codex.AppImage, or extract it (--appimage-extract), delete squashfs-root/usr/lib/libwayland-* and run squashfs-root/AppRun. Building from source uses only system libraries |
| Window blank, white or black, or flickers (often NVIDIA) | The app already sets WebKitGTK workarounds on NVIDIA (__NV_DISABLE_EXPLICIT_SYNC=1 on KDE Wayland, WEBKIT_DISABLE_DMABUF_RENDERER=1 on X11 and Hyprland). If it still fails, start it with --safe-gpu (adds WEBKIT_DISABLE_COMPOSITING_MODE=1 too), or set WEBKIT_DISABLE_DMABUF_RENDERER=1 yourself. If you set any of these variables yourself, the app leaves all of them alone. On some older WebKitGTK builds --safe-gpu can also turn WebGL off, so the Developer mode 3D model viewer may not work |
| No icon in the taskbar on Wayland | The window's app id is starorg-codex-app; the packages and the installer script ship a starorg-codex-app.desktop for it. For a hand-placed AppImage, run the installer with --app or create that file |
| .deb: "unable to locate package" | Use ./ before the file name: sudo apt install ./StarOrg.Codex_<v>_amd64.deb |
| "No Star Citizen install found" | Start the RSI Launcher in the prefix once (it writes the log we read), or Browse / --prefix / --game-dir (first run) |
| "refusing to run as root or elevated" | Run it as your normal user, without sudo |
| "the game is running for LIVE" | Quit the game fully (also check for a leftover StarCitizen.exe with pgrep -af StarCitizen), then apply again |
A duplicate-case error (data and Data) |
Two folders differ only in case inside the game folder; Wine may use either. Merge them by hand, then apply again. starorg-codex doctor reports casing problems |
| Developer mode: the 3D view says "The webview has no WebGL here (...)" | The model viewer needs WebGL 2. On some older WebKitGTK builds, --safe-gpu and WEBKIT_DISABLE_COMPOSITING_MODE=1 can turn it off: try the app without them (and unset the variable). Otherwise check that the GPU driver is installed and working. "Export .glb" works either way; open the file in Blender |
Developer mode: a sound will not play ("The app's webview could not play…", or NotSupportedError) |
WebKitGTK plays sounds through GStreamer and needs gst-plugins-good for its audio output (autoaudiosink) and for .wav: Arch/CachyOS sudo pacman -S gst-plugins-good, Debian/Ubuntu gstreamer1.0-plugins-good, Fedora gstreamer1-plugins-good, openSUSE gstreamer-plugins-good; then restart the app. The AppImage cannot play sounds on most distros (it bundles GStreamer 1.20 without plugins and cannot use the system's): use the .deb, .rpm or a source build. Exporting the sound works everywhere |
| In-game text unchanged | The game reads global.ini only at start: restart the game. Check that USER.cfg in the channel folder has g_language = english |
Blueprints shows your character twice, or missions mark nothing [Owned] |
A character reset gives a new id. Same account and name are merged on their own (the store is backed up first under the channel's blueprints/backups/). Otherwise: Blueprints -> Fix owned blueprints -> Re-scan game logs or Re-import from Smart Citizen into your current character, or choose "Any of my characters"; then re-apply. Command line: starorg-codex blueprints rescan --dry-run, blueprints reimport --character <name> --dry-run |
Diagnostics (Activity -> Diagnostics) exports a report with user names and home paths replaced.
Attach it to a bug report, together with the output of starorg-codex doctor.