SECURITY!!

Hello People! Im not responsible for any server destruction used accidently with this plugin, your server MUST have luckperms plugin. Without this, ANY NON OPERATOR PERSON WILL BE ABLE TO USE THIS PLUGIN AND RUN RM -RF!! luckperms disables every plugin's command, except when you enable them seperatly if plugin supports removing and adding permissons to use luckperms. LUCKLILY, you can install our latest plugin version to get the fix that only op people can use the plugin, which will NOT need luckperms. still use luckperms for like optional support permissons. Bye!

WARNING

IMPORTANT: Many free hosting services (like freemcserver.net) strictly block process execution, resulting in bash: Exec failed, error: 13 (Permission denied) errors when attempting to run shell commands.

Custom Plugin Support: You need a host that allows custom .jar uploads (or SFTP access) to install this tool. Hosters without custom plugin support won't offer tools like this in their default plugin lists!

IMPORTANT 2: Always use version 5.0 or newer unless you are an advanced user with a specific configuration requirement. Versions 4.0 and lower permit unrestricted terminal command execution for all connected players if the LuckPerms plugin is missing or unconfigured.

Starting with Version 5.0, a built-in security patch is included that restricts command execution exclusively to Operator (OP) accounts by default, protecting your server even without an external permissions plugin installed.

Working and not working hosters from my testing.

freemcserver.net - X
Aternos (Free Tier) - X
Minehut (Free Tier) - Kinda X
PowerupStack - X
ScalaCube (Free Tier) - X
Server.pro (Free Tier) - X
MineKeep - X
McServerHoster (Free Tier & More) - V

CRITICAL SECURITY WARNING

IMPORTANT: Always use version 5.0 or newer unless you are an advanced user with a specific configuration requirement. Versions 4.0 and lower permit unrestricted terminal command execution for all connected players if the LuckPerms plugin is missing or unconfigured.

Starting with Version 5.0, a built-in security patch is included that restricts command execution exclusively to Operator (OP) accounts by default, protecting your server even without an external permissions plugin installed.

Usage Warnings and Policies

IMPORTANT: This plugin is strictly intended for administrative and system diagnostic purposes. Using this tool to bypass host limitations, run background cryptominers, or abuse free tier system resources is a direct violation of most hosting Terms of Service (ToS). Doing so will likely result in immediate suspension of your hosting account.

Overview

An ultra-lightweight, efficient cross-platform server administration plugin designed to establish a direct, real-time command pipeline into your host operating system directly from your server console or game chat.

Whether your server runs on Linux, Windows, or macOS, MCLinuxBridge automatically detects the underlying operating system and routes commands cleanly through native system shells (bash, /bin/sh, cmd.exe, or zsh).

Key Features

Multi-OS Execution Engine: Automatically detects host operating system properties at runtime and invokes the correct native shell (Command Prompt on Windows, Zsh on macOS, or Bash/SH on Linux).
Native Java File System Fallbacks: Includes built-in Java file readers (/mclinux list, /mclinux disk) that bypass OS-level binary blocks on restricted containers.
Auto-Embedded Fastfetch: Bundles a portable fastfetch binary directly inside the JAR file that automatically extracts and installs into plugins/MCLinuxBridge/bin/ upon initial server boot.
Configurable Command Whitelist: Generates a local config.yml file allowing server owners to enable security filters and restrict execution rights to explicitly approved base commands.
Dynamic Tab-Completion Dropdowns: Pressing Tab in game chat opens an interactive option box suggesting base commands (help, web, disk, reload, cancel, free, df, uname, ls).
Built-in Java Web File Browser: Hosts a zero-dependency, dark-mode HTTP file explorer directly on port 12732 for browser-based directory inspection.
Live Asynchronous Streaming: Spawns background worker threads to capture terminal logs line-by-line without freezing your primary game tick loop.
Process Interruption Control: Includes a /mclinux cancel sub-command to forcefully terminate active or hanging background tasks on demand.
Watchdog Protection: Applies an automatic 30-second execution cutoff to protect host hardware resources from hanging processes.

Usage Guide

Ensure your user account has appropriate operator privileges, or execute commands directly through your server web panel:

/mclinux help - Displays the in-game command guide and usage overview.
/mclinux web - Displays the link to your built-in Java Web File Browser.
/mclinux disk - Runs native Java storage diagnostics (bypasses shell permission locks. these are made for easier use and hosters that DONT let you use bash on terminal.)
/mclinux reload - Hot-reloads your config.yml whitelist settings.
/mclinux cancel - Forcibly terminates any currently running background process.
/mclinux <command> - Executes raw terminal or command prompt entries (if permitted by config.yml).

Quick System Diagnostics

/mclinux free -h (RAM footprint and memory pool analysis)
/mclinux df -h (Hard drive space allocation tracking)
/mclinux uname -a (Kernel distribution and OS architecture details)

Configuration Guide (config.yml)

When you first install McLinuxBridge, a config.yml file is automatically generated in your plugins/McLinuxBridge/ folder.

By default, security protection is enabled out of the box (whitelist-enabled: true). This restricts in-game execution exclusively to a safe list of diagnostic and utility commands, preventing any accidental system or file destruction.

Default Configuration File

# Set to true to restrict execution strictly to the commands listed below.
# Set to false to allow full, unrestricted terminal command execution (Admins/OPs only).
whitelist-enabled: true

# The explicit list of allowed base commands when the whitelist is enabled.
whitelisted-commands:
  - "help"
  - "fastfetch"
  - "cancel"
  - "free"
  - "df"
  - "uname"
  - "ls"
  - "cat"

How to Safely Add New Commands

If you want to grant your server administrators access to specific terminal tools without completely opening up your entire operating system, keep the whitelist enabled and follow these steps:

Open the file: Locate and edit plugins/McLinuxBridge/config.yml.
Add your command: Add the base name of the tool under whitelisted-commands inside quotation marks.
```
whitelisted-commands:
  - "help"
  - "fastfetch"
  - "ping"
  - "mkdir"
```
Save and Apply: Save the file and run /mclinux reload in-game to instantly apply your changes without restarting the server.

Important Security Note: Only add commands to the list that you completely trust. For example, adding base tools like rm or del to the whitelist will allow anyone with plugin permissions to delete files. Keep whitelist-enabled: true for the safest deployment.

Security Warning

This plugin exposes direct underlying operating system execution access. It should only be deployed on private local testing networks or trusted standalone nodes. Server administrators should utilize the built-in config.yml whitelist to restrict available commands when operating in multi-user environments.