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. The line in your console looks like:

[CraftyAI] Your new API key: cai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That key is shown once. Copy it immediately and put it in config.yml (plugin) or craftyai.json (mod).

If you ever need a new one:

1. Run /crafty apikey in-game. The new key prints to the console.
2. Update your config file with the new key.
3. Restart the server (or run /crafty reload if you're on the plugin).

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

Subscription tiers

CraftyAI has four tiers. Higher tiers increase rate limits, memory capacity, and unlock custom prompts and expanded block scan radii.

Tier	Per-minute	Per-day	Tokens/day	Custom prompts
Free	30	100	50,000	No
Starter	100	1,000	500,000	No
Pro	200	5,000	2,500,000	Yes, once per day
Enterprise	500	100,000	10,000,000	Yes

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).

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.