Offline & Singleplayer

CraftyAI works in singleplayer worlds and keeps working (in a limited way) when your connection drops. This page explains exactly what works in each situation.

Singleplayer worlds

The Fabric and Forge mods include a client-side chat module that intercepts @crafty (or your configured alias) messages only in singleplayer worlds. On a multiplayer server the client module stands down and the server-side plugin handles the chat instead.

In singleplayer you get the full experience:

• Natural AI chat with your AI companion
• Vision scanning, block scanning, and game state awareness (biome, time, weather, health)
• Agentic actions (time, weather, gamemode, items, teleport) — gated by your cheats/OP setting
• The settings screen (press K) with API key, AI name, and mode toggles

Everything runs against the CraftyAI cloud backend over HTTPS, exactly like a server.

The Spigot/Paper plugin is server-side software. It runs on a dedicated server, so "singleplayer" doesn't apply to it — but the offline fallback below does.

When you lose internet (or have no API key)

If there's no connection to the CraftyAI gateway, or no API key is configured, the mods and plugin automatically switch to LocalBrain — a built-in offline assistant.

You'll see one of these prefixes in chat:

Prefix	Meaning
[OFFLINE]	No API key or the connection failed. Set a key to go online.
[FORCED-LOCAL]	You enabled Local Mode on purpose (see below).

LocalBrain can handle a few common things without the cloud:

• Greetings and small talk
• Basic Minecraft tips and game knowledge
• Jokes and light banter
• Simple status questions

It matches your question against keywords to pick a response. The plugin's local brain also draws on the game knowledge corpus (crafting recipes, game rules), while the mods use this compact built-in set. Either way, it is not the full AI: it can't run actions, scan the world, or reason about your game state.

Enabling Local Mode on purpose

If you want to force the offline assistant even when you have a valid key:

• Mod: Settings screen (K key) → toggle Mode: Local Only, or set force_local_mode: true in craftyai.json
• Plugin: ai.force-local-mode: true in config.yml

Queued requests are saved for later

Nothing you ask is silently dropped. When LocalBrain can't answer a question, it saves the request to a local encrypted queue (craftyai_queue.enc, max 50 requests, AES-GCM encrypted at rest). The queue is persisted to disk, so it survives restarts.

LocalBrain exposes a replay mechanism (processQueuedRequests) designed to resend these requests to the full AI once connectivity is restored. Note that this applies to the connection-failure path: if you deliberately force Local Mode, questions are answered locally and not queued.

True offline AI: run a local provider

If you want real AI responses with zero internet, point CraftyAI at an AI provider running on your own machine (Ollama, LM Studio, GPT4All, or any OpenAI-compatible endpoint).

Mod (craftyai.json or the settings screen):

{
  "custom_provider_enabled": true,
  "custom_provider_url": "http://localhost:11434/v1",
  "custom_provider_key": "ollama",
  "custom_provider_model": "llama3.2"
}

Plugin (config.yml):

server:
  custom_provider:
    enabled: true
    url: "http://localhost:11434/v1"
    api_key: "ollama"
    model: "llama3.2"

When a custom provider is enabled, the client sends requests directly to that endpoint (/v1/chat/completions) — the CraftyAI cloud is not involved at all. This is the only way to get full, real LLM responses while completely offline.

Comparison

Scenario	AI chat	Actions	Vision / scan	Notes
Singleplayer, online, key set	Full AI	Yes	Yes	Best experience
Server, online, key set	Full AI	Yes	Yes	Standard setup
Offline (no internet)	LocalBrain fallback	No	No	Requests queued for later
Offline + local provider	Full AI (local)	Yes	Yes	Requires Ollama/LM Studio etc.

See the BYOK guide for more on custom providers.