SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsminectl

minectl

Deployment & operations

View repository

Updated 10-15 21:10

About this skill

minectl

minectl creates and manages Minecraft servers on 16 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.

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