MurCes

A high-performance, zero-overhead TUI & CLI manager for dedicated Minecraft servers on Linux & Windows.

Why MurCes • Visual Tour • Quickstart • CLI Usage • Hotkeys • Fonts • Architecture & IPC • Build

Why MurCes?

Managing dedicated Minecraft servers on budget VPS nodes or homelabs often forces an uncomfortable compromise:

Heavy Web Panels (Pterodactyl, AMP, MineOS) require Docker daemons, Node.js runtimes, Nginx reverse proxies, MySQL databases, and background web workers, consuming 500MB to 1.5GB of RAM before your Minecraft server even allocates its heap.
Raw Shell Scripts are brittle, lack visual status monitoring, don't handle dependency resolution, and make tweaking server.properties or installing mods a chore.

MurCes delivers the sweet spot:

Native Ahead-of-Time (AOT) Binary: Compiled into a standalone ~30MB Linux executable via GraalVM Native Image. Launches in < 20ms with less than 40MB resident memory and zero JVM warmup.
Portable OpenJDK Provisioning: Zero system Java dependencies required. MurCes automatically downloads and provisions Eclipse Temurin JDKs (Java 8, 17, 21) based on Minecraft game versions on demand.
Detached Process Supervision: Your server runs inside an isolated, background tmux session (mcsv). If your SSH connection drops or MurCes exits, the server remains completely unaffected.
Modern Terminal Aesthetics: Designed with 24-bit TrueColor support, background transparency, and popular developer themes (Catppuccin, Nord, Gruvbox, Tokyo Night, Cyberdream, Rose Pine, Kanagawa).
Built-in Mod Ecosystem & 1-Key Updates: Query both Modrinth and CurseForge directly in your terminal. All mods are stored using canonical <slug>-<version>.jar naming, enabling instant 1-key bulk updates ([U]) with semantic version comparison and automatic legacy jar cleanup.
Safe World State Flushing: Performs live memory flushing (save-off → save-all → tar archive → save-on) to eliminate backup chunk corruption, with automated retention rotation and optional rclone cloud replication.
Zero-Config Port Forwarding: Built-in Playit.gg integration (-p) creates secure public tunnels on demand without touching router NAT tables.

Visual Tour & Features

1. Main Dashboard & Workspace

Unified server management cockpit with dual-panel activity diagnostics and live console log stream.

Navigation Hub: Direct keyboard access to engine installers, mod managers, backups, and configs.
Activity & Diagnostics Panel: Real-time status logs for theme changes, network queries, and download triggers.
Embedded Console: Immediate visibility into the underlying Minecraft server output.

2. Server Control & Command Dispatch

Monitor server lifecycle, toggle Playit.gg tunnels, and dispatch in-game commands directly to the tmux session.

Process Telemetry: Live status indicator with active port reporting ([RUNNING] - Port 25565).
One-Click Actions: Start, restart, or safely terminate the Minecraft daemon with graceful world saves.
In-Game Command Prompt: Dispatch console commands directly into the mcsv session without manually attaching tmux.
Networking Controls: Toggle Playit.gg public tunnels and adjust runtime memory allocations on the fly.

3. Server Engine & Version Setup

Configure and boot server engines with automatic Mojang EULA acceptance and custom RAM allocation flags.

Supported Loaders: Fabric, Paper, Forge, NeoForge, Spigot, and Vanilla.
Dynamic Version Resolver: Queries live version manifests for both game releases and loader builds.
Portable OpenJDK Provisioning: Toggle [J] to automatically download and isolate the exact required Eclipse Temurin Java version (8, 17, or 21) into jdks/ for your selected Minecraft release.
Heap Allocation: Fine-tune -Xms and -Xmx RAM allocations without modifying startup shell scripts.

4. In-TUI Mod & Modpack Browser (Dual-Tabbed)

Search, inspect, and install mods and full modpacks from Modrinth and CurseForge without leaving your terminal.

Dual Tab Switcher: Effortlessly switch between [1] Single Mods and [2] Modpacks inside a unified interface.
Universal Index: Search Modrinth and CurseForge API providers on the fly.
Smart Filtering: Automatically filters releases by your active server loader (Fabric, Forge, NeoForge, Quilt) and game version.
Canonical Naming: Downloads are automatically named <slug>-<version>.jar, making tracking and version management effortless.
Modpack Dependency Inspector: Inspects modpack manifests, queries dependencies, excludes client-only mods by default, and unpacks config overrides (overrides/).
Atomic Telemetry: Real-time progress bar downloads into .tmp staging before atomic deployment to mods/.

5. Dedicated Plugin Workspace (Paper, Spigot, Bukkit)

Search, inspect, download, and manage Minecraft plugins stored cleanly in plugins/.

Platform Support: Browse plugins on both Modrinth (project_type:plugin) and CurseForge (Bukkit Plugins).
Server Engine Compatibility: Verifies server type from jar metadata (allows Paper/Spigot, rejects Vanilla or Fabric/Forge with diagnostics logging).
Dual Tabs:
- [1] Browse & Download: Live search, pagination, detailed descriptions, version selector, and animated pickaxe progress bar.
- [2] Installed Plugins Manager: Lists all .jar files in plugins/, parses plugin YAML metadata (plugin.yml / paper-plugin.yml), and supports 1-key deletion ([D]).

6. Installed Mods Manager

Audit, update, and maintain your active server mods directory cleanly.

One-Key Bulk Updates: Press [U] (Update All Mods) to query Modrinth/CurseForge for every installed mod, compare versions, install latest compatible jars, and prune obsolete versions.
Inspect Installed Mods: View all .jar files present in mods/ with parsed slug and version info.
Instant Removal: Instant single-key mod removal ([D]elete Mod) with confirmation safety.
Live Re-indexing: Live file system re-indexing ([R]efresh).

7. Searchable `server.properties` Editor

Tweak server configuration with a keyboard-driven visual inspector.

Live Fuzzy Filter: Press [Q] to filter across all available properties instantly.
Categorized Sections: Grouped into Gameplay, World, Network, Security, and Performance.
One-Key Enum Cycling: Press [Enter] on boolean or enum flags (gamemode, difficulty, pvp, spawn-monsters) to cycle values immediately.
Safe Persistence: Built-in validation with [S]ave, [R]eload, and Reset [D]efaults actions.

8. World Backups & Live Memory Flushing

Safe level snapshots that flush memory buffers first to guarantee zero world corruption.

Automated Memory Flushing: Issues save-off and save-all to disk before packaging the tarball, re-enabling auto-saving (save-on) on exit.
Archive Management: View timestamped .tar snapshots with file sizes directly in the TUI.
Retention & Cloud Replication: Automatically retains the latest snapshots and optionally syncs archives offsite via rclone.

Configuring Google Drive & World Backups

The orchestrator handles automated save flushing, tar archiving, snapshot rotation, and cloud synchronization via rclone natively without external scripts.

Install rclone (for optional cloud sync):

sudo apt install rclone
# or: curl https://rclone.org/install.sh | sudo bash

Configure the Google Drive remote: Run the interactive configuration wizard:
```
rclone config
```
- Press n for a new remote.
- Name the remote minecraftdrive (or any custom name).
- Select drive for Google Drive.
- Leave client ID and secret blank for defaults, or provide your own OAuth credentials.
- Select access scope 1 (full access).
- Complete browser authentication when prompted.
Verify the connection:
```
rclone lsd minecraftdrive:
```
Customize backup settings directly in MurCes TUI: Open World Backups ([B] from Main Menu) to configure options:
- Source World: Directory to archive (default world).
- Target Dir: Folder for .tar snapshots (default backup).
- Retain Count: Maximum snapshot quota to keep locally (default 3).
- Cloud Sync: Checkbox toggle to automatically replicate archives via rclone.
- Remote: Target rclone remote name (default minecraftdrive).
- Press [S]ave Options to persist your configuration to murces.json.
Trigger a backup:
- In the TUI: Press [K] Backup Now in the World Backups view.
- Or via MurCes CLI:
```
./murces backup
```

9. Player UUID & Data Migration

Seamlessly transfer inventories, stats, and advancements between player UUIDs.

Identity Mapping: Migrate stats, advancements, and playerdata from an old player name or UUID to a new one.
Automatic Backup Safeguard: Bundles existing playerdata, usercache, stats, and advancements into a safety archive before modifying files.
Offline/Online Migration: Resolve UUID discrepancies caused by switching between offline-mode and Mojang authentication.

10. Themes, Transparency & Glyphs

Complete visual customization to match your personal terminal setup.

Curated Theme Palettes: Catppuccin (Mocha, Macchiato, Frappé, Latte), Tokyo Night, Nord, Gruvbox Dark, Rose Pine, Kanagawa, Cyberdream, Solarized Osaka, and Minecraft Classic.
Terminal Transparency: Adjustable from 0% (solid opaque) to 100% (full terminal background passthrough).
Glyph Engine: Native Nerd Font icon support with automatic graceful fallback for bare Linux TTYs.
Aesthetic Touches: Optional 24-bit TrueColor rendering and animated pickaxe dirt-breaking loading spinner.

11. Active Tasks & Job Telemetry

Monitor asynchronous background operations in real time.

Real-time tracking of non-blocking server installations, engine updates, and mod downloads.
Detailed task telemetry showing active step, bytes transferred, and speed.
Emergency controls to cancel selected jobs ([C]) or terminate all workers ([K]).

Quickstart

1. Interactive Automated Installers

Linux / macOS / WSL (Bash)

Run the interactive installer to set up system dependencies (tmux, curl, tar, optional rclone, playit) with per-package consent prompts and fetch the latest murces standalone executable:

# Run the interactive installer (authenticates sudo upfront, prompts for each tool, and installs murces to ~/.local/bin)
curl -sSL https://raw.githubusercontent.com/DeployedReject/murces/main/install.sh | bash

# Launch the interactive dashboard from any folder
murces

Windows (PowerShell)

Run the native Windows installer in PowerShell to install psmux (terminal multiplexer), playit.exe, tar, curl, and murces.exe to %LOCALAPPDATA%\MurCes:

# Run the automated PowerShell installer
irm https://raw.githubusercontent.com/DeployedReject/murces/main/install.ps1 | iex

# Launch the interactive dashboard from any folder
murces

Alternatively, to download the precompiled binary directly without the installer:

# For Linux x86_64 / amd64:
curl -sSL -o murces https://github.com/DeployedReject/murces/releases/latest/download/murces-linux-amd64
chmod +x murces && ./murces

# For Linux arm64 / aarch64 (Raspberry Pi, ARM VPS, Apple Silicon VM):
curl -sSL -o murces https://github.com/DeployedReject/murces/releases/latest/download/murces-linux-arm64
chmod +x murces && ./murces

# For Windows x86_64 (PowerShell / cmd):
curl.exe -sSL -o murces.exe https://github.com/DeployedReject/murces/releases/latest/download/murces-windows-amd64.exe
.\murces.exe

Portable Packages (Zero-Installation Archives)

Each release also provides pre-packaged portable .tar.gz and .zip archives containing the standalone executable and documentation ready to unpack and run anywhere:

Linux x86_64 Portable: murces-linux-amd64-portable.tar.gz
Linux arm64 Portable: murces-linux-arm64-portable.tar.gz
Windows x86_64 Portable: murces-windows-amd64.exe-portable.zip

Uninstallation

MurCes provides clean, consent-driven uninstall scripts that remove binaries, configuration data, and PATH entries:

Linux / macOS:

curl -sSL https://raw.githubusercontent.com/DeployedReject/murces/main/uninstall.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/DeployedReject/murces/main/uninstall.ps1 | iex

Note

Standalone native executables can also simply be deleted directly from your bin directory at any time without leaving registry or daemon residue.

CLI Commands

MurCes functions both as an interactive TUI and as a fast, scriptable CLI tool:

./murces [command] [options]        # Linux / macOS
.\murces.exe [command] [options]    # Windows

Command	Description	Flags / Arguments
`./murces`	Launches the interactive Lanterna TUI dashboard	None
`./murces start`	Starts Minecraft in a detached `tmux`/`psmux` session	`-p`, `--public` (starts Playit.gg tunnel)
`./murces stop`	Sends graceful `stop` command and terminates the session	None
`./murces status`	Checks if the Minecraft server daemon is active	None
`./murces server-name [name]`	Gets or sets the server name & synchronized background session name	`[name]` (optional)
`./murces search-modpacks <query> [ver] [loader]`	Searches Modrinth/CurseForge modpacks by game version and loader	`[query] [version] [loader]`
`./murces install-modpack <slug> [ver] [loader]`	Resolves dependencies, downloads jars, & extracts modpack overrides	`[slug-or-id] [ver] [loader] [--include-client]`
`./murces search-plugins <query> [ver] [engine]`	Searches Modrinth/CurseForge Paper & Bukkit plugins	`[query] [version] [server-type]`
`./murces install-plugin <slug> [ver] [engine]`	Downloads & installs plugin jar into `plugins/`	`[slug-or-id] [version] [server-type]`
`./murces list-plugins`	Lists all installed `.jar` plugins in `plugins/`	None
`./murces delete-plugin <filename>`	Deletes a plugin from `plugins/`	`<filename>`
`./murces backup`	Flushes world memory, creates a `.tar` snapshot, and cleans old backups	None
`./murces update-mods [version] [loader]`	Upgrades all installed server mods to latest compatible versions	`[gameVersion] [loader]` (optional)
`./murces install-jdk [version]`	Downloads and provisions portable OpenJDK for target MC/Java version	`[mcVersion]` or `8
`./murces --test-tui`	Runs headless self-test across all TUI screens and exits	None
`./murces --help`	Displays available command options and syntax	None
`./murces --version`	Outputs current release version information	None

Hotkeys & Navigation

Keybinding	Action
`[TAB]` / `[Shift+TAB]`	Cycle focus between Workspace, Activity Log, and Live Console
`[ESC]` / `[B]`	Return to previous view / Back to Main Menu
`[A]`	Toggle / Jump focus directly to Activity & Diagnostics Log
`[L]`	Toggle / Jump focus directly to Server Live Console
`[J]`	Open Active Tasks & Job Manager (from main) / Toggle Portable JDK (in Setup)
`[S]`	Open Server Control & Console
`[I]`	Open Install Server Engine
`[C]`	Open Configure Properties (`server.properties`)
`[B]`	Open World Backups
`[P]`	Open Player UUID Migration
`[D]`	Open Download & Browse Mods (Mods & Modpacks Tabs)
`[M]`	Open Manage Installed Mods
`[G]`	Open Plugins (Browse & Manage)
`[1]` / `[2]`	Switch tabs in Mods (`[1] Single Mods` / `[2] Modpacks`) and Plugins (`[1] Browse` / `[2] Installed`)
`[U]`	Update All Mods (inside Manage Installed Mods view)
`[Z]`	Open Customization & Themes
`[N]`	Edit Server Name / Session (in Server Control & Setup)
`[E]`	Exit MurCes

System Requirements

Component	Requirement	Details
Operating System	Linux (x86_64, arm64) or Windows 10/11 (x64)	Tested on Ubuntu, Debian, Arch Linux, Alpine, Fedora, WSL2, & Win
Terminal Multiplexer	`tmux` (Linux/macOS) or `psmux` (Windows)	Required for detached background session supervision
HTTP Downloader	`curl` or `wget` (built-in on Windows 10+)	Required for dependency and package fetching
Archive Bundler	`tar` (built-in on Windows 10 build 17063+)	Required for world backups and player migration snapshots
Terminal Font	Nerd Font (v3.0+)	Required for icons, navigation glyphs, and status indicators
Cloud Sync (Optional)	`rclone`	Required only if using Google Drive/S3 offsite world backups
Public Tunnels (Optional)	`playit`	Required only if running public servers without port forwarding
Runtime Environment	None	The native binary runs out of the box with zero Java dependencies

Terminal Rendering & Fonts

MurCes features rich icons and glyphs powered by Nerd Fonts.

Automatic Fallback (Zero Setup Needed)

You do not need a Nerd Font to use MurCes.

If you are connected from a basic terminal emulator, standard Linux virtual console (/dev/tty*), or an SSH client without patched font glyphs:

MurCes automatically detects terminal capabilities at startup.
It seamlessly downgrades all UI icons to clean, standard ASCII / Unicode glyphs.
No missing glyph boxes (``), character overflow, or corrupted line wraps.

Manual Overrides

In-App: Press [Z] Customization & Themes → toggle [G]lyphs between Auto-detect, Force Nerd Fonts, or Basic (Fallback).

Environment Variables:

NO_NERD_FONT=1 ./murces      # Force basic ASCII fallback
FORCE_NERD_FONT=1 ./murces   # Force full Nerd Font icons

Installing Nerd Fonts with `getnf`

If you want the full icon experience, install any patched Nerd Font in seconds:

# Install getnf
curl -fsSL https://raw.githubusercontent.com/getnf/getnf/main/install.sh | bash

# Browse and install your preferred font (e.g. JetBrains Mono, Fira Code, Hack)
getnf

Decoupled Orchestrator (IPC)

MurCes is architected around a decoupled backend engine: murces-orchestrator.

The orchestrator communicates over standard I/O (stdin/stdout) via structured JSON IPC messages. This allows you to embed MurCes into custom Discord bots, custom web frontends, CLI automation scripts, or remote administration sidecars.

flowchart LR
    subgraph Clients["Frontend Clients"]
        TUI["MurCes Native TUI\n(Lanterna / GraalVM)"]
        CLI["CLI Subcommands\n(Bash / Scripts)"]
        EXT["Custom Integrations\n(Discord Bot, Web UI)"]
    end

    subgraph Core["Backend Orchestration Layer"]
        IPC["JSON IPC (stdin / stdout)"]
        ORCH["murces-orchestrator\n(Lifecycle & Package Engine)"]
    end

    subgraph Systems["System Services & External APIs"]
        TMUX["tmux Session ('mcsv')\nMinecraft Daemon"]
        MODS["Modrinth & CurseForge\nREST APIs"]
        MOJANG["Mojang Version Manifests\n& Paper/Fabric APIs"]
        BAK["Safe tar Snapshot Engine\n& rclone Cloud Sync"]
    end

    TUI <--> IPC
    CLI <--> IPC
    EXT <--> IPC
    IPC <--> ORCH
    ORCH --> TMUX
    ORCH --> MODS
    ORCH --> MOJANG
    ORCH --> BAK

IPC Examples

Bash / Shell

Pipe JSON payloads straight into standard input:

# 1. Query supported server engines
echo '{"type": "server", "serverType": "none", "gameVersion": "none", "loaderVersion": "none", "ram": 0, "job": 3}' | java -jar murces-orchestrator-1.2.jar

# 2. Download and boot Paper 1.20.4 with 4GB RAM
echo '{"type": "server", "serverType": "paper", "gameVersion": "1.20.4", "loaderVersion": "none", "ram": 4, "job": 1}' | java -jar murces-orchestrator-1.2.jar

# 3. Search Modrinth for "sodium" on Fabric 1.20.4
echo '{"type": "modding", "modBrowser": "modrinth", "subType": "search", "modName": "sodium", "version": "1.20.4", "modLoader": "fabric", "modId": "0"}' | java -jar murces-orchestrator-1.2.jar

Python Integration (Bots or Web Backends)

import subprocess
import json

proc = subprocess.Popen(
    ["java", "-jar", "murces-orchestrator-1.2.jar"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
    bufsize=1
)

def send_ipc(payload):
    proc.stdin.write(json.dumps(payload) + "\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

# Query live server running state
response = send_ipc({
    "type": "server",
    "serverType": "none",
    "gameVersion": "none",
    "loaderVersion": "none",
    "ram": 0,
    "job": 4
})

print(f"Server Active: {response.get('running')}")

Tip

For detailed IPC payload schemas, job IDs, and response formats, refer to the full specification in doc/API-SPEC.md.

Building from Source

If you prefer to compile MurCes from source rather than using the official native release:

Prerequisites

JDK 21+
Apache Maven 3.9+
GraalVM Native Image (native-image toolchain installed)

1. Compile the Orchestrator

cd java/orchestrator
mvn clean install
cd ../..

2. Build the Java TUI (JAR)

cd java/tui
mvn clean package
# Artifact generated at java/tui/target/murces-tui-1.2.jar
cd ../..

3. Compile Standalone Native Binary (GraalVM)

cd java/tui
mvn clean package -Pnative
cp target/murces ../../
cd ../..

Configuration & API Keys

Release Binaries: Precompiled releases (murces.zip) have the CurseForge API client credentials pre-configured and baked in. Mod browsing works out of the box with zero configuration required.
Source Builds & Custom Keys: If you are compiling from source or wish to provide your own developer credentials, create a .env file in the root directory:

curseAPI="YOUR_CURSEFORGE_API_KEY"
email="your_developer_email@example.com"

Branches

main: Active production branch containing the Lanterna TUI, decoupled orchestrator backend, and GraalVM build configuration.
archived: Historical C prototype and initial proof-of-concept codebase preserved for reference.

Contributing & Community

Contributions, bug reports, and feature proposals are warmly welcome!

Found a bug? Open an issue on the GitHub Issue Tracker.
Want to contribute code? Fork the repository, create a topic branch, and submit a Pull Request.

License

MurCes is free and open-source software licensed under the GNU General Public License v3.0.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
doc		doc
java		java
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

Latest commit

History

Folders and files

Repository files navigation