shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

minectl

Deploy and manage Minecraft servers across 16 cloud providers using the minectl CLI. Use when the user wants to create, delete, update, or list Minecraft servers, write minectl YAML manifests, connect via RCON, upload plugins, or choose cloud providers and server editions for Minecraft hosting. Triggers on: Minecraft server deployment, minectl commands, Minecraft manifest files, cloud-hosted game servers, or Minecraft edition selection.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

minectl

minectl creates and manages Minecraft servers on 15 cloud providers via declarative YAML manifests.

Creating a Manifest

Every operation starts with a manifest file:

apiVersion: minectl.ediri.io/v1alpha1
kind: MinecraftServer
metadata:
  name: my-minecraft
spec:
  server:
    cloud: hetzner
    region: fsn1
    size: cx21
    ssh:
      port: 22
      publickeyfile: ~/.ssh/id_rsa.pub
      fail2ban:
        bantime: 1000
        maxretry: 3
    port: 25565
  minecraft:
    java:
      openjdk: 21
      xmx: 2G
      xms: 2G
      rcon:
        password: changeme
        port: 25575
        enabled: true
    edition: papermc
    version: "1.21"
    eula: true
    properties: |
      max-players=20
      difficulty=normal
      motd=My Minecraft Server

Choosing an Edition

| Edition | Best for | |---------|----------| | java | Vanilla experience, no mods | | papermc | Performance + plugin support (recommended) | | spigot | Bukkit plugin ecosystem | | craftbukkit | Legacy Bukkit plugins | | fabric | Lightweight mods | | forge | Large mod packs | | purpur | Paper + extra gameplay tweaks | | bedrock | Cross-platform (mobile/console/PC) | | nukkit | Java-based Bedrock server | | powernukkit | Extended Nukkit |

For proxy setups, use kind: MinecraftProxy with editions: bungeecord, waterfall, or velocity.

Edition-Specific Tuning

Different editions need different server.properties and resource allocations. Getting these wrong causes crashes, kicks, or poor performance — this is where most new server admins struggle.

Forge / Fabric (modded servers):

  • Set max-tick-time=90000 (or -1 to disable). Modded servers regularly exceed the default 60s watchdog, especially during chunk generation or mod initialization. Leaving the default causes the server to kill itself under normal modded load.
  • Set allow-flight=true. Many mods (Botania, Mekanism jetpacks, Elytra mods, etc.) trigger the vanilla flight detection. Without this, modded players get kicked constantly.
  • Allocate generous heap: 8G minimum for light mods, 12G+ for heavy packs (100+ mods). Set xms equal to xmx to avoid expensive heap resizing under load.
  • Always add volumeSize: 50 (or more). Mod packs, world data with modded chunks, and backups consume significant disk. Running out of disk silently corrupts worlds.
  • Upload mods to /minecraft/mods (not /minecraft/plugins).
  • Enable monitoring (monitoring.enabled: true) — modded servers are resource-hungry and benefit from Prometheus metrics to catch memory/CPU issues early.

PaperMC / Spigot / CraftBukkit / Purpur (plugin servers):

  • Default max-tick-time=60000 is usually fine.
  • Keep allow-flight=false unless a specific plugin requires it.
  • 2-4G heap is sufficient for up to 20 players with typical plugins.
  • Upload plugins to /minecraft/plugins.
  • PaperMC is the recommended default — it's the most performant fork and supports all Bukkit/Spigot plugins.

Bedrock / Nukkit / PowerNukkit:

  • No java block needed in the manifest (Bedrock is a native binary, not Java-based).
  • Default port is 19132 (UDP), not 25565.
  • RCON is not available for Bedrock edition.
  • Lower resource requirements: 1-2G RAM is typically sufficient.

Instance Sizing Guide

| Use case | Players | Recommended RAM | Example sizes | |----------|---------|----------------|---------------| | Vanilla / Paper (casual) | 1-10 | 2-4 GB | Hetzner cx21, DO s-2vcpu-4gb | | Paper with plugins | 10-20 | 4-8 GB | Hetzner cpx31, DO s-4vcpu-8gb, AWS t3.large | | Forge/Fabric (light mods) | 1-10 | 8 GB | AWS t3.xlarge, Hetzner cpx41 | | Forge/Fabric (heavy mods) | 5-15 | 16 GB+ | AWS m5.xlarge, Hetzner cpx51 | | Proxy (BungeeCord/Velocity) | N/A | 1-2 GB | Smallest available |

When using spot instances (spot: true), prefer regions with large capacity pools (e.g., us-east-1 for AWS) to minimize interruption risk. Always warn users that spot instances can be terminated with 2 minutes notice — world backups are essential.

Security Recommendations

Always include these in every manifest:

  • fail2ban block under SSH config (prevents brute-force attacks)
  • Strong RCON password (never deploy with "changeme")
  • Consider white-list=true and enforce-whitelist=true for private servers
  • online-mode=true to verify player accounts (prevents unauthorized access)

Optional Features

Add to spec.server:

  • spot: true - Spot/preemptible instances (AWS, Azure, GCE) to save cost
  • arm: true - ARM instances (Hetzner, AWS, GCE)
  • volumeSize: 50 - Extra storage in GB

Add to spec:

  • monitoring: { enabled: true } - Prometheus + Node Exporter

Naming Rules

  • metadata.name must be lowercase alphanumeric with hyphens only
  • SSH port must be 22 or between 1024-65535
  • eula must be true

Server Lifecycle

# Generate a manifest interactively
minectl wizard

# Create a server (waits for startup by default)
minectl create -f server.yaml

# Verify the server is running after creation
minectl list -p hetzner -r fsn1
# Expected: server appears with a valid ID and status. If absent, check credentials and quota.

# List running servers
minectl list -p hetzner -r fsn1

# Connect via RCON for remote commands
minectl rcon -f server.yaml --id <server-id>

# Upload a plugin
minectl plugins -f server.yaml --id <server-id> -k ~/.ssh/id_rsa \
  -p myplugin.jar -d /minecraft/plugins

# Update Minecraft version (edit version in manifest first)
minectl update -f server.yaml --id <server-id> -k ~/.ssh/id_rsa

# Delete the server
minectl delete -f server.yaml --id <server-id> -y

Error Recovery

| Symptom | Likely cause | Action | |---------|--------------|--------| | create exits without a server ID | Authentication failure | Verify provider environment variables are exported (see references/cloud-providers.md) | | create fails with quota/limit error | Cloud account quota exceeded | Switch region, use a smaller size, or request a quota increase from the provider | | create succeeds but server absent from list | Wrong region or provider flag | Re-run minectl list with the exact -p and -r values from the manifest | | Plugin upload fails | SSH key mismatch | Confirm -k points to the private key matching spec.server.ssh.publickeyfile | | RCON connection refused | RCON not enabled or wrong port | Ensure rcon.enabled: true and the port in the manifest matches rcon.port |

Cloud Provider Selection

When helping a user choose a provider, consider:

  • Budget: Civo, Hetzner, and DigitalOcean are cheapest. Use spot: true on AWS/Azure/GCE for savings.
  • Region needs: Check references/cloud-providers.md for available regions.
  • Local testing: Use multipass for local VMs with no cloud account needed.

Each provider requires specific environment variables for authentication. See references/cloud-providers.md for the full list.

References