Skip to main content

Spigot / Paper Plugin Installation

This guide covers Spigot, Paper, Folia, and Purpur. The plugin is the same across all four.

Requirements​

| Minecraft | 1.8 through 1.21.x & 26.x | Java Edition & Bedrock (via GeyserMC) | | Bedrock Edition | Supported via GeyserMC / Floodgate | Floodgate prefixes (., *, -, spaces) & gamertags up to 36 chars | | Java | 8 or newer | Java 17+ required for Folia or MC 1.20.4+ | | Server software | Spigot, Paper, Folia, or Purpur | Any one of them |

Install​

  1. Download craftyai-spigot-1.3.0.jar from Modrinth.
  2. Drop it into your server's plugins/ folder.
  3. Start the server.

CraftyAI v1.3.0+ auto-saves the API key to your config on first start — no manual copying needed. Just start the server and the plugin handles everything.

Older versions: The plugin prints the key to the console once. Copy it, open plugins/CraftyAI/config.yml, paste it under server.secret, then run /crafty reload.

That's it. Players can start talking to CraftyAI in chat.

What's in config.yml​

The plugin generates a default config on first run. The fields that matter:

server:
  secret: "your-api-key"

ai:
  # What the AI is called in chat
  name: "Crafty"

  # Names players can use to address the AI
  aliases:
    - crafty
    - craftyai
    - ai
    - helper

  # Set to true to let the AI change time, weather, etc.
  enable_actions: true

  # Set to true to let the AI scan nearby blocks when asked
  allow_block_scanning: true

You probably won't need to change any of this. The defaults work for most servers.

Commands​

| Command | What it does | |---|---|---| | /crafty | Show plugin info | | /crafty status | Check connection | | /crafty reload | Reload config (admin only) | | /crafty learn Q \| A | Teach the AI (admin only) | | /crafty ask <question> | Ask AI privately | | /crafty scan | Scan nearby area | | /crafty confirm | Confirm a destructive action | | /crafty pro help | Show Pro key instructions | | /crafty pro status | Show your current tier | | /crafty pro redeem <key> | Redeem a Pro key | | /crafty memory | View your stored memories | | /crafty forget [n] | Forget a specific memory or all | | /crafty privacy <on\|off> | Toggle server-wide RAG memory opt-out (admin only) | | /crafty mode <local\|cloud> | Toggle between cloud and forced local offline mode (admin only) | | /crafty prompt view | View your custom prompt (Pro only) | | /crafty prompt set <text> | Set a custom AI prompt (Pro only) | | /crafty prompt reset | Reset to default prompt (Pro only) | | /crafty apikey | View or auto-mint API key | | /crafty apikey rotate | Rotate existing API key | | /crafty link | Get a code to link this server to your Discord |

Permissions​

The default permissions are designed so most servers don't need a permissions plugin. OPs get everything. Standard players get only crafty.chat, which lets them talk to the AI but not trigger actions like time changes.

If you want to grant actions to specific players, install LuckPerms and add crafty.actions.

GeyserMC / Bedrock support​

CraftyAI works with Bedrock players through GeyserMC and Floodgate. Place the CraftyAI plugin JAR in your plugins/ folder alongside GeyserMC. Floodgate automatically appends a prefix (such as .) to Bedrock player names, and CraftyAI handles those correctly for chat, scanning, and actions. No additional configuration needed.

Config migration​

When you update CraftyAI, your config is automatically migrated to the latest version. Your existing settings are preserved. A backup of the pre-migration config is saved as config.yml.bak in the plugin folder.

Folia note​

Folia splits the server into multiple threads and regions. CraftyAI supports Folia but Java 17 is required, regardless of your Minecraft version.

Help​

If something doesn't work, check Common Issues or ask on Discord.