MineShell

A self-hosted web control panel for modded Minecraft servers on Linux.

MineShell brings modpack installation, server management, diagnostics, world administration, and player data editing into one web interface. It runs each Minecraft server as a systemd service, with per-server configuration, resource limits, snapshots, and automation.

Manage your own servers from a browser, or give friends access to specific servers and features through granular account permissions.

Highlights

• Modpacks from Modrinth, CurseForge and FTB, or a loader of your choice: installed, updated with your config changes kept, and rolled back if an update goes wrong.
• Snapshots and backups that share unchanged files, on a schedule or before anything risky, copied to another disk if you want, and restored whole, by dimension or by chunk.
• Crash diagnosis that names the likely mod, with a one-click fix, and a bisect assistant for the crashes it cannot name.
• Player and inventory editing, modded items included, with their real item pictures.
• A map of your world in the browser, on Minecraft 1.13 and newer without adding a mod to the server.
• Accounts for friends, each limited to the servers and features you give them.

Features

Modpack & instance management

Install and maintain modded Minecraft servers without having to manage every step manually.

• Multiple sources: Browse Modrinth, CurseForge, and FTB, upload .mrpack or CurseForge archives, or create a server from a Minecraft version and loader.
• Loader support: Vanilla, Fabric, Quilt, Forge, NeoForge, and Cleanroom.
• Pack updates: Update to a different pack version, including packs originally installed from uploaded files. Configuration changes are preserved or merged, with side-by-side review when both you and the pack changed the same lines. The preview lists files you added to the pack's folders and lets you keep yours where the new version ships its own. A pack change can be cancelled while it runs, which puts the server back exactly as it was; a cancelled pack install removes the half-made server.
• Update notices: Each server is checked for a newer pack version (pack servers) or loader build and mod updates (servers set up from a loader), and for newer builds of the data packs added from the mod browser (any server, vanilla included), on a schedule you pick, with betas and alphas optional. The overview shows what is out, with a button to review and install it or to skip that version (a mod can also be held at its version for good), and the server list marks the servers that have one.
• Rollback: Revert the last pack change, restoring the previous configuration and optionally the world from its pre-update snapshot.
• Minecraft and loader migrations: Move eligible non-pack servers between Minecraft versions or loaders. Compatible mod builds are selected where available; unsupported mods are disabled and listed. Going to an older Minecraft is possible with a warning, and by default starts a new world for it, the old one kept.
• Forge 1.12.2 / Cleanroom migration: Switch between Forge and Cleanroom, including handling the compatible Fugue version required by Cleanroom.
• Safe experimentation: Copy an entire server to test changes separately.
• Move between machines: Export a server to one file and import it into another MineShell, with its world, configs, settings and mod records. Mods from Modrinth and CurseForge are downloaded again on import instead of being packed, and the loader is installed again, so exports stay small.
• Installation recovery: Failed downloads are reported with manual download links and retry options. Long-running operations report progress and recover interrupted changes after a MineShell restart.
• Server icons: Pack icons are used automatically and can be replaced in server settings.

Server operations & monitoring

Control server lifecycles and monitor what is happening without leaving the browser.

• Start, stop, restart, and force-stop servers, including delayed shutdowns with in-game warnings.
• Perform graceful shutdowns using RCON to save the world before stopping Java, with signal-based fallbacks.
• Configure crash recovery, restart attempt limits (a crash while starting that a restart would only repeat, like a missing dependency, is not restarted but shown with its fix at once), scheduled restarts (daily, or every few hours on the clock: every 6 hours is 0:00, 6:00, 12:00, 18:00), and scheduled console commands (on the clock too, or daily at a time).
• Delay scheduled operations while players are online.
• Let Minecraft 1.21.2+ pause an empty server (its pause-when-empty-seconds, in settings and new-server defaults); the status shows it paused until someone joins, or pre-generating while Chunky goes on working.
• See every server's ports (game, RCON, query, voice chat, map) and what listens on each, with clashes between servers and ports other programs hold, and move one to a free port. Where new ports start can be changed for setups that need it.
• Set per-server CPU and memory limits, and a cap on all servers together (a soft memory cap that slows the servers down instead of killing one), and detect servers that never finish starting.
• Get notified on Discord, on your phone (ntfy) or through a webhook when a server crashes, is killed for its memory, gets stuck starting, misses a scheduled snapshot or fails to copy one to the backup folder, runs low on disk space or has an update, and optionally on restarts, starts, stops and players joining or leaving. Quiet hours keep the optional ones back overnight and update news until the morning, while problems still come through. A server can send to its own channel instead or as well.
• Get a warning before starting a server the machine may not have the memory for, counting what the running servers can still grow into.
• Choose which servers start after a machine reboot: restore their previous state, always start, or never start automatically.
• Monitor uptime, startup duration, online players, player session times, daily player peaks, CPU and memory usage, disk consumption, and tick rate where available (per dimension on Forge and NeoForge).
• Inspect Java heap usage and receive guidance when memory allocation seems insufficient or excessive.
• View server addresses and manage players directly from the overview.
• See on the Activity page how the outside services MineShell uses (Modrinth, the modpacks.ch mirror, Mojang, Java and loader sites) answered since it started, with a warning while one is not answering.

Console, logs & crash diagnostics

Find out what went wrong without manually digging through files and terminal output.

• Live console output streamed from the systemd journal, with commands sent through RCON.
• Filter log levels, search output, expand or collapse stack traces, and highlight player joins and departures.
• Command history, saved commands, and a dedicated chat view.
• Search previous server runs, server logs, and crash reports together, including archived logs.
• Analyze logs with mclo.gs for a second opinion, or share them through a link that MineShell can subsequently delete.
• Diagnose crashes and identify likely problematic mods, with one-click mod disabling where supported, and for a missing dependency a button that installs it from Modrinth. Old crashes can be cleared from the overview once the server starts cleanly again, and clear on their own when a one-click fix worked. A server the kernel killed for its memory (its limit, or the machine running out) is named as such. So is one the watchdog ended for a tick that ran too long, with a button to allow longer ticks (3, then 10 minutes).
• Detect crashes where the Java process remains alive but the server has stopped functioning.
• Run timed Spark profiles and view uploaded results. If Spark's upload fails, download the saved profile or upload it again.
• Mod bisect assistant: When ordinary diagnosis cannot identify the cause, systematically test individual mods or pairs of mods using a throwaway world, then restore the original server configuration.

Mod management & client exports

Manage server mods and prepare matching client installations from the same interface.

• Search Modrinth and CurseForge, resolve mod dependencies, install updates, or upload JARs manually.
• Enable, disable, delete, and change mod versions. Each mod shows which mods need it, and disabling or deleting one that others need asks first.
• See each installed mod with its picture, size and when it was added or updated, sorted by any of them either way, and filtered to the enabled, disabled, client-only or those that need attention.
• Detect mods added outside MineShell and identify them rather than silently ignoring them.
• Spot the same mod installed twice (for example once from Modrinth and once from CurseForge under another file name) by the mod ids inside the jars, and disable one copy.
• Detect and disable client-only mods after pack installation.
• Browse and install data pack releases directly into a world's datapacks/ directory, and update them (a world-generation pack the world uses only with the server stopped, after a snapshot).
• Export client installations as Modrinth .mrpack files, CurseForge ZIP archives, or Prism Launcher instances.
• Put the server in the exported pack's multiplayer list, so players join without typing the address.
• Export the mod list as Markdown, plain text, HTML, CSV or JSON, with versions, authors, links or file names, to copy or download.
• Choose which mods and folders to include in an export. For servers installed from modpacks, include the original pack's client-side files that were not needed on the server.

World management & snapshots

Manage worlds, recover from mistakes, and automate routine maintenance.

• Create snapshots manually, on a schedule, or automatically before risky operations.
• Snapshot a running server with saving paused, or stop and restart it around the operation.
• Configure retention by snapshot count and storage usage. Pin, name, tag, and filter snapshots. Snapshots share the files that did not change between them, so ten of a big world take little more than one.
• Restore a snapshot, reset a world, replace it with an uploaded world, or download a world as a ZIP archive.
• Keep several worlds per server: start a new one without deleting the old, upload one, switch between them, and turn any snapshot into a world of its own. Each world keeps its seed, data packs and map.
• Reset or restore individual dimensions.
• Restore chosen chunks from a snapshot, picked on a map of the dimension drawn from the world's own files (top blocks with their textures' colours, modded blocks too).
• Prune chunks that have not actually been visited, previewed on a heatmap of where players spent time, with chunks to keep picked on the map, or saved as named areas (a base, a town) that every prune skips.
• Pre-generate terrain with Chunky (installed from the World tab, with Fabric API where needed; Minecraft 1.16 and newer) and monitor its progress: plan the area on a map of the world (square, rectangle, circle or ellipse, centered on spawn, the world border or any point), which shows how many chunks are new and about how much disk they take; it can pause while players are online and continue by itself after a restart.
• Coordinate snapshots and scheduled restarts so they do not interfere with each other.
• Copy snapshots to a backup folder on another disk, a mounted network share or a USB drive, right after each one is taken, with its own retention, compressed (about a third smaller) or as plain folders. Copy one back to restore it, also into a server made again after the old one was lost. A missing or full folder is reported (and notified), never created on the system disk underneath.

Backup limitation: Backup folders are folders on this machine; cloud and remote destinations (S3, SFTP, rclone) are not implemented yet.

Player management & inventory editing

Administer players and inspect their saved data, including inventories containing modded items.

• Manage whitelists, operators and operator levels, bans with reasons, and IP bans.
• Remove a player from a world (their player file, stats and advancements go to the trash), for someone who joined once and should not stay in the list.
• Update player lists through RCON while the server is running, or edit the relevant JSON files while it is stopped.
• Resolve player names to UUIDs through Mojang and identify players in imported worlds using their current account names.
• Inspect offline player inventories, effects, and other saved data.
• See each player's statistics (time played, deaths, kills, distance, blocks mined and every item, block and mob the game counts) with readable times and distances, and rank players by any of them.
• Edit modded inventories, including backpacks and Curios or Trinkets equipment slots, with slots grouped and named where supported.
• Select enchantments by name from the world's own enchantment table, including modded enchantments on Minecraft 1.12 and older.
• Browse vanilla and modded items by name instead of having to type their identifiers.
• View item icons and 3D block models sourced from Minecraft and installed mod JARs.
• Render supported special models, including chests, shulker boxes, beds, banners, heads, shields, conduits, decorated pots, and additional model-based variants.
• Inspect item tooltips containing information such as enchantments, durability, energy, and item identifiers.

Item rendering can be disabled in MineShell settings, leaving names and data available without loading or drawing item models.

World maps

Explore your worlds through an integrated browser-based map.

• Minecraft 1.13 and newer: BlueMap renders a 3D map directly from world files, including modded blocks using models from the installed mods.
• Update the map manually or on a schedule.
• View the map without adding a rendering mod to the Minecraft server. Add the BlueMap mod when a live map with player positions is desired.
• Forge 1.12.2: Install Dynmap and DynmapBlockScan through the Map tab for a live map.

Networking & public access

Let players join from outside your local network without manually configuring port forwarding.

• Integrate a playit.gg account through an approval flow; MineShell does not receive your playit.gg password.
• Enable public access for individual servers.
• Automatically manage the tunnel agent and server tunnel, keeping the tunnel associated with the server's port.
• Display the public address in the server interface and remove the tunnel when the server is deleted.
• Access the agent's playit.gg page and choose its connection location where supported by the account plan.

Settings, files & Java

Manage server configuration and files without needing direct shell access for routine tasks.

• Searchable, tabbed settings for general options, gameplay, players, networking, performance, Java and memory, automation, snapshots, and advanced configuration.
• Typed controls for common server.properties options, alongside an editor for additional keys and a raw configuration editor. Unrecognized properties are preserved.
• Port availability checks, with options to swap ports with another server or move to a free port.
• Browse, upload, download, rename, delete, and edit text files within an instance directory. The editor has line numbers and colours for JSON, TOML, YAML, Forge .cfg, .properties, scripts and shell files, marks a syntax error as you type, and before saving a broken JSON (with comments too: .jsonc), JSON5, TOML or YAML file names the line and asks (with "Save anyway").
• Every save in the editor keeps the version it replaced (the last 20 per file, up to 90 days), to load back and save again.
• Search a server's configs and scripts for some text, or a folder of them, and open each matching line in the editor; file and folder names are matched too, mods and logs included.
• Upload files and folders by dragging them into the file browser.
• Unpack an uploaded zip where it lies or into a folder named after it (asking before replacing anything, which goes to the trash), and download any folder as a zip; a running server's world folder pauses saving while it downloads.
• Recover deleted files from a per-server trash, with configurable automatic cleanup.
• Open server directories in a file manager through SFTP links, with the address to copy and what to change when the browser opens nothing.
• Inspect disk usage, including world-map data stored outside the server directory, and delete archived logs and crash reports after a chosen number of days.
• Spot a pack's own backup mod (AromaBackup, Simple Backups, FTB Backups, Textile Backup) copying the world beside MineShell's snapshots, with the folder it fills.
• Discover installed Java runtimes or download Eclipse Temurin and Azul Zulu builds.
• Match Java versions to individual servers using Minecraft's version metadata, with configurable defaults when multiple runtimes are available.

MineShell itself

Keep MineShell up to date without replacing the installation by hand, and comfortable to use.

• Updates from the browser: MineShell checks for new releases every 12 hours or on demand, shows their notes, and installs one with a click, restarting itself while the Minecraft servers keep running. Betas of the next version are offered too if you turn them on. An update waits for running tasks; if it fails, the old version keeps running and the installer's log is shown.
• Going back: Browse every release with its notes, and go back to an older one of the same major version, or the last one before it, when a release brings a problem (with warnings, a database copy first, and a refusal where the older version could not work with the database).
• Database copies: MineShell copies its own database (accounts, settings, history) before every update and once a day, keeping the last seven daily copies. Settings > Updates puts one back, showing first which servers it lacks or brings back, and keeps the database as it was as a copy of its own; an installed MineShell restarts itself to finish.
• Themes: Deep Slate, Midnight, or the light Daylight.
• Phones and tablets: Every page works on a narrow screen, and MineShell can be installed as an app when it is reached over https.

Multi-user access & permissions

Share MineShell with friends while controlling which servers and features each account can access.

• Global administrators: The owner and MineShell administrators can manage the entire application.
• Per-server access: Grant full administrative access to a server or assign individual permissions for operations such as starting and stopping, console access, mods, settings, files, and snapshots.
• Player-data restrictions: Limit access to all players or specific players.
• Automatic ownership: The account that creates or copies a server becomes its administrator. Access to copied servers is not automatically granted to everyone who could access the original.
• Account management: Create accounts, issue one-time passwords, require password replacement on first login, disable accounts, and sign them out everywhere.
• Permission-aware interface: Accounts see only their permitted servers, tabs, and controls. Settings that are readable but not editable are marked accordingly.
• Log: Review recent actions and the account responsible for each one.
• Protected integrations: Only the owner can manage the playit.gg and CurseForge connections or update MineShell.

Requirements

• Linux with systemd.
• Node.js 22.19 or newer.
• journalctl, provided by systemd.
• A compatible Java runtime for each Minecraft version. MineShell can discover or download supported runtimes.

Tested on Debian 12, Ubuntu 24.04, Fedora 44 and Arch Linux, on x86-64. ARM machines and musl-based distributions such as Alpine are untested.

MineShell is intended for self-hosted use on a Linux machine. It is not a multi-tenant hosting panel: Minecraft servers run under the same Linux account as MineShell. Users granted access to files, mods, or Java and loader settings may be able to execute programs as that account. Only grant those permissions to people you trust.

Installation

Run the installer as the Linux account that should own and run the Minecraft servers, not as root.

curl -fsSL https://github.com/Manyullyn17/MineShell-Reloaded/releases/latest/download/install.sh | bash

The installer installs MineShell into ~/mineshell, writes configuration to ~/.config/mineshell/mineshell.env without overwriting an existing settings file, and sets up a systemd user service that starts at boot. The default port is 3000. Running the installer again updates an existing installation.

Open MineShell in your browser and set the owner account's password on first visit. The initial account name is admin.

To update, use the Update button under MineShell settings > Updates, or run the installer again. See Upgrading.

For installation options, directory layout, and uninstall instructions, see Deployment.

Reaching it from outside your network

MineShell is designed for your local network. To use it from elsewhere, connect through Tailscale: MineShell settings > System serves it at an https address only your own devices reach, in one click. A public address is possible but not recommended; scripts/caddy.sh <domain> puts it behind Caddy with an automatic certificate. Never forward port 3000 itself through your router: it is plain http, passwords included. See Remote access.

Development

To work on MineShell itself, see Contributing: setup, tests, the project layout and adding a theme.

Configuration

MineShell is configured through environment variables. Installed instances read them from their settings file; development instances use .env.

See .env.example for the complete list.

Variable	Default	Purpose
MINESHELL_DATA	~/.local/share/mineshell	Data directory for server instances and application data.
MINESHELL_AUTH	on	Authentication toggle. Disable only on a network you fully trust.
MINESHELL_HOSTS	Unset	With MINESHELL_AUTH=off only: host names besides addresses and local names to answer to, comma-separated (an authenticating reverse proxy's).
MINESHELL_UNIT_PREFIX	minecraft in development; mineshell in the installer	Prefix for systemd instance units.
CURSEFORGE_API_KEY	Unset	Optional CurseForge API key for improved metadata access. Can also be configured in MineShell.
PORT, HOST	3000, 0.0.0.0	Where the web interface listens. HOST=127.0.0.1 answers only on this machine (behind a reverse proxy or Tailscale serve).
ADDRESS_HEADER, XFF_DEPTH	Unset, 1	Behind a reverse proxy: read the client's address from X-Forwarded-For, so the login throttle works per client. See Remote access.
BODY_SIZE_LIMIT	Infinity in the example configuration and installer settings	Controls request body size. Production rejects uploads larger than 512 KB when this is unset.

Documentation

• Deployment guide — installation, configuration, and maintenance.
• Architecture — implementation details and design decisions.
• Roadmap — planned work and deferred features.
• Test documentation — test setup and behavior.
• Contributing — development setup, conventions, and project layout.

Credits

MineShell stands on a lot of other people's work. Thank you to everyone behind these. The same list is on MineShell's About page.

Libraries

Open source code that ships inside MineShell. Their license texts are in THIRD-PARTY-NOTICES in every release.

• Svelte and SvelteKit — The web interface and the server behind it. (MIT)
• better-sqlite3 — MineShell's database, with SQLite inside it. (MIT)
• SQLite — The database engine. (Public domain)
• Drizzle ORM — Database queries and schema migrations. (Apache-2.0)
• marked — Mod and pack descriptions and release notes, from Markdown. (MIT)
• DOMPurify — Cleans those descriptions before they are shown. (Apache-2.0 or MPL-2.0)
• node-tar — Unpacks Java downloads. (BlueOak-1.0.0)
• yauzl and yazl — Reads and writes zip files: packs, world downloads, client exports. (MIT)

Built with

Tools used to make MineShell, not shipped with it.

• Vite — Builds MineShell and runs it while developing. (MIT)
• TypeScript — The language most of MineShell is written in. (Apache-2.0)
• Vitest — The test suite. (MIT)
• Drizzle Kit — Generates the database migrations. (MIT)

Programs

Downloaded and run by MineShell when a server needs them.

• Eclipse Temurin — Java builds MineShell downloads for servers.
• Azul Zulu — Java builds MineShell downloads for servers.
• Fabric — Mod loader: its installer and server launcher.
• Quilt — Mod loader: its installer.
• Minecraft Forge — Mod loader: its installer.
• NeoForge — Mod loader: its installer.
• Cleanroom — Mod loader for 1.12.2 packs: its installer, and the client instance for exports.
• BlueMap — Renders the Map tab for Minecraft 1.13 and newer.
• playit.gg agent — Gives servers a public address without opening ports.

Mods

Installed by MineShell or worked with when a server has them.

• Dynmap and DynmapBlockScan — The live map for 1.12.2 Forge and Cleanroom servers.
• BlueMap (mod) — A live map with players on it, offered beside the rendered one.
• Fugue — Added to every Cleanroom server, so older mods run on it.
• Scalar Legacy — Added to every Cleanroom server: the Scala libraries Forge bundled.
• spark — Profiling from the server's overview, and its viewer.
• Chunky — Pre-generating worlds from the World tab.
• Simple Voice Chat — Its port is kept free and tunnelled with the server.

Services

Asked by MineShell over the internet.

• Modrinth — Mod and pack search, downloads, updates and which mods are client-only.
• CurseForge — Mods and packs, and the files on its CDN.
• Feed The Beast (modpacks.ch) — FTB packs, and CurseForge mods and packs without an API key.
• Mojang — Game versions, server jars, the Java each version needs, player names and skins.
• Adoptium and Azul — Lists of their Java builds.
• Fabric and Quilt meta — Loader versions per Minecraft version.
• mclo.gs — Sharing and analysing logs.
• spark's bytebin — Uploading profiles spark could not upload itself.
• playit.gg — Tunnels for public access.
• GitHub — MineShell updates and BlueMap downloads.

Thanks

Work MineShell builds on.

• Aikar's flags — The recommended JVM preset.
• Prism Launcher — The instance format client exports follow.

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.

License

See the repository's LICENSE file for licensing information.