Skip to main content

Server Admin Guide

This page covers the day-to-day decisions you'll make as the operator of a CraftyAI server: what players can do, what you can change, and where to find usage data.

The API key​

The plugin mints an API key on first startup and saves it to plugins/CraftyAI/config.yml. It confirms the save in the console without printing the full key. Treat that configuration file as private.

If you ever need a new one:

  1. Run /crafty apikey as an authorized administrator to check the current setup or mint a missing key.
  2. Use /crafty apikey rotate when replacing the existing key. The plugin saves the replacement and reloads its connection.
  3. For manual configuration edits, run /crafty reload after saving the file.

The Discord bot can also generate keys if you prefer that workflow. Either path produces the same kind of key.

Subscription tiers​

See Tiers & Subscriptions for the four tiers, current source defaults and how to request a subscription from an authorized moderator in our official Discord. Game actions and vision remain available across tiers, subject to server permissions and safety rules.

Check your current tier with /crafty pro status in-game, or /my-sessions in our Discord.

Custom prompts (Pro)​

If you're on Pro or Enterprise, you can change the AI's personality. Tell it to talk like a pirate, a strict teacher, a sarcastic butler, whatever fits your server.

The command is /crafty prompt set <text>. You can set it once per 24 hours, and the change is silent, no announcement to players. View the current prompt with /crafty prompt view.

Permissions​

The defaults are:

  • All players: Can chat with the AI
  • OPs: Can also trigger actions like changing time or giving items

If you want to let non-OP players trigger actions, install a permissions plugin (LuckPerms is the common one) and grant them crafty.actions.

Gamemode changes require the separate crafty.actions.gamemode permission, so you can let trusted players heal themselves without giving them /gamemode creative.

Advanced Configuration (config.yml)​

The plugin configuration (plugins/CraftyAI/config.yml) provides granular control over AI behavior:

  • ai.activation.response-visibility — Controls default chat response scope (default, always-private, always-public).
  • ai.activation.fuzzy-threshold — Maximum edit distance threshold for mention matching (default: 2).
  • ai.activation.anywhere-in-message — Triggers AI when its alias appears anywhere in the message string (default: false).
  • ai.max_give_amount — Maximum item stack size per AI give action (default: 64).
  • ai.require_confirmation — Toggles required player confirmation (/crafty confirm) before executing destructive world changes (default: true).
  • vision.activation — Vision scanner trigger method (item_right_click vs command_only).
  • vision.activation_item — Item required in hand for vision scanning (default: COMPASS).
  • announcements.enabled — Toggle network announcement sync bridge (default: true).
  • halloween_startup_message — Show an October countdown in the server console on plugin startup, or “Happy Halloween!” on October 31 (default: true). Uses the server's local date. Silent checks run every seven hours during October, with an extra wake at Halloween midnight to greet once while the server remains running. Monitoring stops automatically on November 1; outside October, startup creates no holiday timer. Config reload respects this toggle. Config version 7 adds it while preserving existing settings.

What gets blocked​

The AI will refuse to give players:

  • Command blocks, structure blocks, jigsaw blocks
  • Bedrock, end portal frames, barrier blocks
  • Spawners

These are blocked regardless of permissions, because they break servers. The AI tells the player it can't help with that.

Security alerts​

When CraftyAI notices something suspicious, like a client claiming to be a Minecraft mod but sending non-standard headers, it sends an alert to all online operators. The alert looks like:

[CraftyAI Warning] Non-Minecraft client detected from session srv-xxxxxxxx

This usually means a plugin or mod on your network is making requests with the wrong user agent. Check the version of every CraftyAI installation on your network.

Checking usage​

In Discord, /my-sessions shows every server linked to your account, along with today's token usage and request count.

In-game, /crafty status shows the current connection state, your tier, and how many requests you've made in the last hour.

Where to ask questions​

Discord is the fastest way to reach us. Open a ticket in the support channel and we'll respond within a day.