MineSSH

MineSHH

MineSHH gives Paper server owners a secure, password-protected SSH console. Connect with Terminus, OpenSSH, PuTTY, or another SSH client and run Minecraft console commands remotely—without installing a web panel.

The plugin starts its own SSH server and mirrors new Paper console messages to connected SSH sessions in real time.

Features

• Remote SSH access to the Paper console
• Compatible with Terminus, OpenSSH, PuTTY, and standard SSH clients
• Configurable bind address and TCP port
• Password-protected login with a configurable username
• Live stream of new Paper console output in every connected SSH session
• Commands are executed as the Minecraft server console
• Visible command input, Backspace support, and prompt restoration when a log interrupts typing
• Automatically generated SSH host key, kept in the plugin data folder
• No external database or proxy required

Requirements

Requirement	Version
Server software	Paper 1.21.6 (including build 87)
Java	Java 21
Network protocol	TCP

MineSHH is a server-side plugin. Players do not need to install anything.

Installation

1. Download the latest MineSHH-*.jar file from the Modrinth version page.
2. Stop your Paper server.
3. Put the JAR in the server's plugins folder.
4. Start the server once. MineSHH creates plugins/MineSHH/config.yml and an SSH host key.
5. Stop the server and change the default SSH password in the configuration.
6. Start the server again.

When MineSHH is ready, Paper prints:

[MineSHH] started

Configuration

Configuration file: plugins/MineSHH/config.yml

 **A TCP port is required.**
 **Restart the server after changing this file.**
ssh:
   **Address on which the SSH server listens.** Use 127.0.0.1 for local access only.
  bind-address: "0.0.0.0"
  port: 2222
  username: "admin"
   **Change this before exposing the port to a network.**
  password: "change-this-password"

Option	Description
bind-address	0.0.0.0 accepts connections from any network interface. Use 127.0.0.1 to allow only local connections or a proxy/tunnel on the same machine.
port	The SSH listening port. It must be an unused TCP port from 1 to 65535. The default is 2222.
username	Username required for SSH login.
password	Password required for SSH login. Change the default value before allowing remote access.

Restart the server after every configuration change.

Connecting

Allow the configured TCP port in the server firewall and, if applicable, in your hosting provider's firewall panel.

OpenSSH

ssh -p 2222 admin@YOUR_SERVER_IP

Replace 2222, admin, and YOUR_SERVER_IP with your own values. Enter the password from config.yml when prompted.

Terminus

Create a new SSH connection with these values:

Field	Value
Host	Your server IP address or domain
Port	The configured ssh.port (default: 2222)
Username	The configured ssh.username
Password	The configured ssh.password

The first connection can display an SSH host-key confirmation. This is normal: MineSHH generates its host key on its first startup. Confirm it only when you are connecting to the correct server.

Using the Remote Console

After connecting, MineSHH displays a MineSHH > prompt. Type Minecraft console commands without a leading /.

MineSHH > say Hello from SSH
MineSHH > list
MineSHH > whitelist add PlayerName
MineSHH > stop

The command is sent to Paper with console permissions, so it has the same power as typing directly in the server terminal. New server logs are displayed in the SSH connection while it is open.

Type one of the following to end only the SSH connection:

exit
logout

exit and logout close the SSH session only. To stop the Minecraft server, use the stop console command.

Security

SSH console access is powerful: anyone who knows the credentials can run administrative server commands. Keep it private.

• Change the default password before exposing the port.
• Use a long, unique password.
• Do not share the SSH credentials with untrusted people.
• Restrict the port in your firewall to trusted IP addresses whenever possible.
• Use 127.0.0.1 as bind-address if you connect through an SSH tunnel, VPN, or local panel integration.
• Do not use the Minecraft game port (25565) as the MineSHH port.
• Keep the generated plugins/MineSHH/ssh-host-key.ser file private. Do not delete it unless you intentionally want clients to see a new host key.

Troubleshooting

Connection refused

Check that the server is running, MineSHH printed [MineSHH] started, the configured TCP port is allowed by the operating-system firewall, and the port is open in your hosting provider panel.

Address already in use

Another application is using the selected port. Change ssh.port to a free TCP port and restart the Paper server.

Authentication failed

Verify ssh.username and ssh.password in plugins/MineSHH/config.yml. Restart the server after changing either value.

The SSH client reports a changed host key

This normally means the server host key was regenerated, the server was moved, or the client is connecting to a different machine. Verify the server identity before accepting the new key.

I can connect, but no command works

Commands must not start with /. For example, enter list, not /list.

Building from Source

This repository includes a GitHub Actions workflow that builds the plugin automatically on every push, pull request, and manual workflow run. Download the MineSHH artifact from the completed workflow run.

Local builds require Java 21 and Maven:

mvn package

The built JAR is placed in the target directory.

Support

When reporting a problem, include your Paper version, Java version, MineSHH version, and the relevant console error (remove passwords, IP addresses, and other private information first).