System Installation

Install Crateria packages directly using signed repositories for APT and DNF package managers.

Fedora (DNF Setup)

Step 1: Download the repository configuration

sudo curl -fsSL https://crateria.github.io/packages/rpm/crateria.repo -o /etc/yum.repos.d/crateria.repo

Step 2: Install the packages

sudo dnf install trance morphball

Debian / Ubuntu / Pop!_OS (APT Setup)

Step 1: Create the keyrings directory

sudo mkdir -p /etc/apt/keyrings

Step 2: Download the GPG keyring

sudo curl -fsSL https://crateria.github.io/packages/apt/crateria-keyring.gpg -o /etc/apt/keyrings/crateria.gpg

Step 3: Register the repository source list

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/crateria.gpg] https://crateria.github.io/packages/apt stable main" | sudo tee /etc/apt/sources.list.d/crateria.list

Step 4: Update package lists

sudo apt update

Step 5: Install the packages

sudo apt install trance morphball

About Crateria

Crateria is a project dedicated to building a memory-safe, security-hardened Linux desktop utility suite. All core components are written in Rust and follow a strict privilege-separation model.

Organization Map

The Crateria ecosystem is divided into the following specialized repositories:

Contributing & Policies

Development is hosted publicly on GitHub. Please submit pull requests to the individual project repositories. Contributions are governed by the Apache-2.0 license and the organization contributing guides.

Trance Command Line (CUI)

The trance CLI tool is a non-interactive client designed for scripting, quick configuration edits, and querying daemon metrics directly from a terminal or system hooks.

Command Reference

Trance Terminal UI (TUI)

Trance includes an interactive terminal user interface for real-time monitoring and layout configuration, avoiding the need to remember manual commands.

Launching the TUI Dashboard

To run the full terminal user interface console, execute:

trance-tui

TUI Features

• Interactive Panels: Switch focus between general settings and screensaver listings.
• Live Control: Toggle idle activations, adjust idle timeouts, and change rendering scales with instant D-Bus feedback.
• Status Bar: Visual markers showing power states, GPU status, and session inhibitors.

Configuration Helper

Why Configure Trance?

Trance is designed to run silently as a background service. Adjusting configurations allows users to optimize performance (such as lowering rendering scale on low-end GPUs), customize idle timeout triggers, choose specific screensaver plugins, or toggle the FPS counter overlay for debugging.

Configure Trance by editing ~/.config/trance/config.toml or generate a config dynamically using the wizard below:

D-Bus API Reference

Why Expose a D-Bus Interface?

Exposing control interfaces over D-Bus allows Trance to integrate seamlessly with the rest of the desktop environment. It allows:

• Lock Screens (like Wayland compositor locks) to securely request screensaver activation or check status.
• Panel Applets (like the COSMIC Desktop panel widget) to toggle settings or change active screensavers.
• CLI clients (like trance and trance-tui) to control settings dynamically without direct file writes or process restarts.

The daemon registers the io.github.crateria.trance service on the Session Bus:

Plugin Development

Custom screensavers are compiled as dynamic shared libraries and loaded at runtime. Implement the interface defined in the trance-api crate.

// src/lib.rs
use trance_api::{Plugin, PluginContext, RegisterPlugin};

struct CustomEffect;

impl Plugin for CustomEffect {
    fn render(&mut self, ctx: &mut PluginContext) {
        // Draw directly to the Wayland surface context
    }
}

// Register the entry point hook
trance_api::register_plugin!(CustomEffect);

Morphball Command Line (CUI)

Morphball is designed as a secure, high-performance command-line utility for compression, extraction, and integrity validation on Linux systems.

Command Reference

Morphball Terminal UI

Morphball features an interactive terminal application (TUI) to browse and manage archive operations without manual commands.

Launching the TUI

To start the interactive console explorer, execute:

morphball-tui

TUI Features

• Visual Explorer: Navigate files and folder structures inside archives dynamically.
• Single-Key Extraction: Unpack individual files or directories directly from the interactive view.
• Compression Wizard: Step-by-step guides to compress paths with preset configurations.

Sandboxing Engine

Why Sandboxing is Necessary

Decompression libraries (e.g., zip, 7z, and gzip engines) are historically written in complex C/C++ code, presenting a large attack surface for buffer overflows, directory traversal exploits (e.g., extracting to ../../etc/shadow), and dynamic memory bugs. If a developer or automated daemon decompresses an untrusted archive, the entire host environment could be compromised.

Defense-in-Depth with Landlock LSM

Morphball leverages the Linux Landlock Security Module (LSM) to enforce kernel-level restrictions on the worker thread handling decompression. This guarantees that even if a zero-day vulnerability in the decompression engine is exploited:

• Directory Lockdown: The process is physically blocked from writing any files outside the designated output directory, neutralizing directory traversal attacks completely.
• Information Concealment: Read access is blocked for all sensitive user files, restricted exclusively to the target output directory, the input archive, and essential system dynamic library paths (like /lib, /lib64, and /usr/lib) required for execution.
• Resource Containment: The worker thread has no network permissions, file socket capabilities, or process management rights, preventing remote code execution (RCE) callbacks.