Skip to content

Linux Installation

Install Gremia Shell on Linux using AppImage or .deb packages.

System Requirements

Requirement Minimum
OS Ubuntu 22.04+, Fedora 38+, or equivalent
Architecture x86_64 (64-bit)
RAM 4 GB
Disk Space 200 MB
Runtime WebKitGTK 4.1+
Network HTTPS outbound to api.gremia.io

Download

Download the latest package from the Releases page:

File Format Best for
gremia-shell_x.y.z_amd64.deb Debian package Ubuntu, Debian, Pop!_OS
gremia-shell_x.y.z_amd64.AppImage AppImage Any Linux distribution

Option A: Debian Package (.deb)

Install dependencies

The .deb package declares its dependencies, but ensure the following are present:

sudo apt update
sudo apt install -y libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1

Install the package

sudo dpkg -i gremia-shell_x.y.z_amd64.deb
sudo apt install -f  # Resolve any missing dependencies

Launch

gremia-shell

Or find Gremia Shell in your application launcher.

Uninstall

sudo apt remove gremia-shell

Option B: AppImage

Make executable and run

chmod +x gremia-shell_x.y.z_amd64.AppImage
./gremia-shell_x.y.z_amd64.AppImage

Desktop integration

Use AppImageLauncher to integrate the AppImage into your application menu with automatic updates.

FUSE requirement

AppImage requires FUSE to mount. On Ubuntu 22.04+:

sudo apt install libfuse2

WebKitGTK Dependency

Gremia Shell uses WebKitGTK for its UI. Install it for your distribution:

sudo apt install libwebkit2gtk-4.1-0

sudo dnf install webkit2gtk4.1

sudo pacman -S webkit2gtk-4.1

First Launch

  1. Sign in — Enter your Gremia account credentials
  2. Select a manifest — Choose from cloud or paste a manifest ID
  3. Connect — The Shell opens a WebSocket tunnel to Gremia Cloud

Auto-Updater

The built-in updater checks every 6 hours for new versions:

  • Displays a desktop notification when an update is available
  • For .deb installs: downloads and applies the new package
  • For AppImage: downloads the new AppImage and replaces the current file

Manual check: Settings > Check for Updates.

Firewall Configuration

If running a local firewall (e.g., ufw), allow outbound HTTPS:

sudo ufw allow out 443/tcp

Required destinations:

Host Port Purpose
api.gremia.io 443 REST API + WebSocket tunnel
*.supabase.co 443 Authentication

Troubleshooting

WebKitGTK not found

If you see error while loading shared libraries: libwebkit2gtk-4.1.so:

# Ubuntu / Debian
sudo apt install libwebkit2gtk-4.1-0

# Fedora
sudo dnf install webkit2gtk4.1

Blank window on Wayland

If the window appears blank under Wayland, try running with X11:

GDK_BACKEND=x11 gremia-shell

Permission denied on AppImage

chmod +x gremia-shell_*.AppImage

No tray icon

Install the AppIndicator library:

# Ubuntu / Debian
sudo apt install libayatana-appindicator3-1

# Fedora
sudo dnf install libappindicator-gtk3

Connection issues behind a proxy

Set the proxy environment variable before launching:

export HTTPS_PROXY=http://proxy.example.com:8080
gremia-shell