MurCes

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

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

Could not find a higher resolution gif. Please refer to the assets folder to view demo.webm for a better quality demo.

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.
Player Access Control: Manage the whitelist and blacklist (bans) of your server straight from the dashboard. Toggles, additions, pardons, and reason tracking are written to whitelist.json / banned-players.json and pushed live into the running server console.
Native Playit.gg Tunnel Console: Claim and link a Playit agent without ever leaving the TUI, inspect the live route table, sync server.properties to the tunnel port, and toggle the background tunnel daemon with one key.
Multi-Server Profiles: Keep several servers side by side (each with its own directory, tmux session, port, loader, and RAM budget) and switch between them from the CLI with a single command.
Bring Your Own Server: Import an existing server distribution from a .zip on disk or a direct download URL, with automatic loader detection (Fabric, Forge, NeoForge, Paper, Purpur, Spigot, Quilt, Vanilla).

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.
Twelve-Way Quick Launch: Jump straight to Server Control, Engine Installer, Properties, Playit Tunnel, Backups, Player Access, Mods, Modpacks, Plugins, Themes, Jobs, or Exit.

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.
Session Identity: Rename the server and its backing tmux session inline, then persist it with [S]ave.

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, Spigot, and Vanilla from the picker — NeoForge and Quilt distributions are auto-detected when you import them.
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.
Direct Import: Press [M] to import a pre-built server distribution from a .zip file or a direct HTTP(S) URL without leaving the installer.

4. Network & Playit.gg Tunnel

Claim, link, and supervise public tunnels without touching your router's NAT table.

Agent Claim & Link: Press [C] to mint a claim URL and match code, then link the agent from the Playit.gg dashboard.
Daemon Supervision: [T] toggles the background playitd tunnel runner inside its own detached session.
Live Route Table: [R] refreshes the active tunnel routes and public domains mapped onto your local port.
Port Sync: [S] rewrites server-port in server.properties so it always matches the tunnel's local port.
Credential Reset: [X] wipes the cached playitagent.txt credentials so you can re-link from scratch.

5. 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.
Atomic Telemetry: Real-time progress bar downloads into .tmp staging before atomic deployment to mods/.

Modpack Browser Tab

Modpack Dependency Inspector: Inspects modpack manifests, queries dependencies, excludes client-only mods by default, and unpacks config overrides (overrides/).
Bundled Server Detection: Modpacks that ship their own engine (Forge / NeoForge / GTNH style packs) are detected and installed automatically.
Pagination & Description Modes: Page through the catalogue with [ / ] and flip between summary and full description views.

6. 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]).

7. 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.
Repair Existing Entries: Re-add a player to replace an incorrect UUID. Offline names must match the client’s capitalization; proxy/Bedrock users can supply their server UUID directly.
Instant Removal: Instant single-key mod removal ([D]elete Mod) with confirmation safety.
Live Re-indexing: Live file system re-indexing ([R]efresh).

8. Player Access: Whitelist, Bans & UUID Migration

One workspace for every player-facing control: whitelist entries, bans with reasons, and identity migration.

Three-Tab Layout: [1] Whitelist, [2] Blacklist / Bans, and [3] UUID Migration share a single workspace.
Whitelist Toggle: Flip white-list in server.properties and MurCes immediately dispatches whitelist on / whitelist off plus a whitelist reload into the live server console.
1-Key Membership: [A]dd Player accepts a username or UUID, resolves the server-cached UUID first, uses Mojang profiles for online-mode servers, and generates case-sensitive offline UUIDs for offline-mode servers, and writes a canonical whitelist.json entry.
Repair Existing Entries: Re-add a player to replace an incorrect UUID. Offline names must match the client’s capitalization; proxy/Bedrock users can supply their server UUID directly.
Instant Removal: [R]emove Player drops the selected entry (or prompts for a name) and syncs the running server with whitelist remove.
Duplicate Safe: Adds are idempotent — re-adding an existing player is a no-op instead of a corrupt file.

Blacklist / Bans Tab

Reasoned Bans: [A]dd Ban captures an optional reason and stores it in banned-players.json with source and expires metadata.
Live Ban Dispatch: Bans are pushed to the running server with ban <player> <reason> the moment you confirm.
One-Key Pardon: [P]ardon / Remove issues pardon <player> and cleans the ban record.

UUID Migration Tab

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.

9. 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.

10. 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
```

11. 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.
Runtime Guards: Enforce a minimum window size (>= 70x18), point the asset directory at any folder, and auto-download portable JDKs for the Minecraft versions you use.

12. 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]).

13. Multi-Server Profiles & Custom Server Import

Run several servers from one binary, or adopt an existing distribution you already trust.

Profile Per Server: Every profile stores its own directory, tmux session, game version, loader, RAM budget, and port inside murces.json.
Zero-Config Switching: murces servers lists what you have, murces switch <profile> re-points the dashboard at another one.
Directory Agnostic Startup: --dir and --session flags let scripts start a server that lives outside the current folder.
Bring Your Own Distribution: murces import-server <url|file> unpacks a .zip (or downloads one), auto-detects the engine, records metadata, and refuses to guess when nothing recognizable is found (override with --force).
Script-Aware Launching: Detects run.sh, startserver.sh, launch.sh, run.bat, startserver.bat and friends, then falls back to auto-detecting fabric-server-launch.jar, quilt-server-launch.jar, Forge universal jars, or Paper/Purpur/Spigot jars.

Quickstart

1. Interactive Automated Installers

Linux / WSL2 (Ubuntu / Debian / Arch / Fedora / Alpine)

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 Users (Windows Subsystem for Linux - WSL2)

Native Windows console does not support the low-level POSIX pseudo-terminal / tmux environment required by MurCes. Windows users can run MurCes seamlessly inside WSL2:

Install WSL2 (if you haven't already, run in PowerShell as Administrator):
```
wsl --install
```
Open your WSL2 terminal (e.g. Ubuntu).

Run the MurCes installer:

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

Launch the TUI:
```
murces
```

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

# For Linux x86_64 / amd64 (and WSL2):
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

Portable Packages (Zero-Installation Archives)

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

Linux x86_64 / WSL2 Portable: murces-linux-amd64-portable.tar.gz
Linux arm64 Portable: murces-linux-arm64-portable.tar.gz

Uninstallation

MurCes provides a clean, consent-driven uninstall script that removes binaries, configuration data, and PATH entries:

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

Note

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

2. Bringing Your Own Server

Already running a server distribution you like? Import it instead of reinstalling:

# Import from a local archive
./murces import-server ~/downloads/my-server.zip

# Import straight from a URL
./murces import-server https://example.com/my-server.zip

# Force the install even if no engine files are recognised
./murces import-server ~/downloads/my-server.zip --force

The archive is unpacked into the active server profile's directory, the loader is auto-detected, and the engine metadata is recorded so the TUI can manage it like any other installation.

CLI Commands

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

./murces [command] [options]        # Linux / WSL2

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), `--session <name>`, `--dir <path>`
`./murces stop`	Sends graceful `stop` command and terminates the session	`--session <name>`
`./murces status`	Checks if the Minecraft server daemon is active	`--session <name>`
`./murces server-name [name]`	Gets or sets the server name & synchronized background session name	`[name]` (optional)
`./murces servers`	Lists all configured server profiles and the active one	None
`./murces switch <profile>`	Switches the active server profile (directory, session, port, loader)	`<profile-name>`
`./murces server-port <port>`	Updates `server-port` inside `server.properties`	`[dirOrFile]` (optional)
`./murces tunnel <setup\|status\|reset>`	Manages the Playit.gg agent & tunnel lifecycle natively	`setup`, `status`, `reset`
`./murces search-modpacks <query> [ver] [loader]`	Searches Modrinth/CurseForge modpacks by game version and loader	`[query] [version] [loader] [platform]`
`./murces install-modpack <slug> [ver] [loader]`	Resolves dependencies, downloads jars, & extracts modpack overrides	`[slug-or-id] [ver] [loader] [--include-client]`
`./murces search-mods <query> [ver] [loader]`	Searches Modrinth/CurseForge for individual mods	`[query] [version] [loader] [platform]`
`./murces install-mod <slug> [ver] [loader]`	Downloads & installs a single mod into `mods/`	`[slug-or-id] [ver] [loader] [--force]`
`./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 import-server <url\|file>`	Imports a server distribution from a `.zip` file or direct URL	`--force` (optional)
`./murces whitelist [on\|off\|add\|del] [player]`	Toggles the whitelist and manages `whitelist.json` entries	`on`, `off`, `add`, `remove`, `list`
`./murces ban <player> [reason]`	Bans a player (adds to `banned-players.json`)	`[reason]` (optional)
`./murces pardon <player>`	Pardons / unbans a player	`<player-name-or-uuid>`
`./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\|17\|21`
`./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

Access Control Recipes

# Turn the whitelist on, then let two players in
./murces whitelist on
./murces whitelist add Notch
./murces whitelist add Dinnerbone

# Review the roster
./murces whitelist list

# Ban a griefer with a reason, then undo it if needed
./murces ban Griefer99 "Griefing spawn area"
./murces pardon Griefer99

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`)
`[N]`	Open Network & Playit Tunnel (from Main Menu)
`[B]`	Open World Backups
`[P]`	Open Player Access (Whitelist, Bans, Migration)
`[D]`	Open Download & Browse Mods (Mods & Modpacks Tabs)
`[M]`	Open Manage Installed Mods
`[G]`	Open Plugins (Browse & Manage)
`[1]` / `[2]` / `[3]`	Switch tabs in Mods (`[1] Single Mods` / `[2] Modpacks`), Plugins (`[1] Browse` / `[2] Installed`), and Player Access (`[1] Whitelist` / `[2] Blacklist` / `[3] UUID Migration`)
`[U]`	Update All Mods (inside Manage Installed Mods view)
`[Z]`	Open Customization & Themes
`[N]`	Edit Server Name / Session (in Server Control & Setup)
`[Q]` / `[E]`	Exit MurCes (from any view)
`[Ctrl+C]` / `[Ctrl+Q]`	Immediate emergency shutdown and terminal restore

View-Specific Hotkeys

View	Keys
Network & Playit Tunnel	`[C]` Claim agent • `[T]` Toggle daemon • `[R]` Refresh routes • `[S]` Sync port • `[X]` Reset credentials
Server Control	`[S]` Start • `[T]` Terminate • `[R]` Restart • `[U]` Update status • `[D]` Dispatch command • `[M]` Cycle RAM • `[K]` Open tunnel config • `[N]` Edit server name
Engine Installer	`[I]` Install only • `[S]` Start & install • `[M]` Direct import (ZIP/URL) • `[X]` Cancel • `[E]` Cycle engine • `[V]` Cycle version • `[O]` Loader version • `[D]` Install dir • `[J]` Portable JDK
Player Access	`[A]` Add player / ban • `[R]` Remove whitelist entry • `[P]` Pardon • `[M]` Migrate
Mods & Modpacks	`[S]` Search • `[D]` Download • `[I]` Install modpack • `[P]` Cycle platform • `[O]` Cycle loader • `[V]` Cycle version • `[K]` Cycle file version • `[M]` Toggle description mode • `[X]` Cancel
Plugins	`[S]` Search • `[D]` Download (browse) / Delete selected (installed) • `[Y]` Cycle server type • `[K]` Cycle plugin version • `[M]` Toggle description mode • `[R]` Refresh installed • `[X]` Cancel download
Installed Mods	`[U]` Update all • `[D]` Delete mod • `[R]` Refresh
World Backups	`[K]` Backup now • `[D]` Delete backup • `[R]` Refresh • `[S]` Save options
Active Tasks	`[C]` Cancel selected job • `[K]` Kill all jobs • `[R]` Refresh

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"

Runtime Configuration File

Every persistent preference lives in murces.json next to your server directory:

{
  "theme": "Gruvbox Dark",
  "transparencyPercent": 0,
  "trueColor": true,
  "enforceMinSize": true,
  "pickaxeAnimation": true,
  "nerdFontMode": "auto",
  "sessionName": "mcsv",
  "serverDir": "server",
  "activeServer": "survival",
  "serverProfiles": {
    "survival": {
      "name": "survival",
      "directory": "server",
      "sessionName": "mcsv",
      "gameVersion": "1.21.1",
      "loader": "fabric",
      "ram": "4G",
      "port": 25565
    }
  },
  "portableJdk": false,
  "gameVersion": "1.21.1",
  "loader": "fabric",
  "backupSourceFolder": "world",
  "backupTargetFolder": "backup",
  "backupRetentionLimit": 3,
  "backupCloudSync": false,
  "backupCloudRemote": "minecraftdrive"
}

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.sh		install.sh
uninstall.sh		uninstall.sh

Latest commit

History

Folders and files

Repository files navigation