Viper LLM

ViperLLM

ViperLLM is an advanced, high-performance Server-Side ONLY Fabric mod for Minecraft 1.21.x, 26.1.x, and 26.2.x. It connects vanilla Minecraft chat to compatible Large Language Model providers with automatic endpoint detection, isolated per-player profiles, conversation memory, endpoint fallback, and a live @tool system. No client mod is required.

Supported Versions

Purpose & Function

ViperLLM allows players to communicate with AI agents through standard Minecraft chat while granting those agents controlled access to live server information.

• Universal Endpoint Detection: Detects OpenAI, OpenRouter, LM Studio, Ollama, Anthropic, and compatible proxy layouts.
• Isolated Player Environments: Each player owns separate instances, models, API keys, prompts, settings, and memory at world/viperllm/players/<UUID>.json.
• Live State Tools: The LLM can request recipes, inventory, player status, nearby entities, weather, time, statistics, advancements, book/chest contents, and permitted commands.
• Memory Management: Combines short-term conversation history with asynchronous long-term summaries.
• Vanilla-Compatible Pipeline: Uses Fabric Mixins and Brigadier entirely server-side. Vanilla clients require no installation.

Key Features

Enhance your server setup! Check out my other server-side mods over at : Fabric Server Essentials

Commands & Examples

The implemented command is apikey, not api_key. There are currently no /llm chat, max_tokens, or top_p command nodes.

URL Handling

The URL parser accepts both quoted and unquoted URLs. Quotes are optional unless an argument contains whitespace.

# Both are valid
/llm scan http://192.168.1.50:1234
/llm scan "http://192.168.1.50:1234"

/llm set local url http://localhost:1234/v1/chat/completions
/llm set local url "http://localhost:1234/v1/chat/completions"

/llm scan accepts a base URL, version root, or full endpoint:

/llm scan https://api.openai.com YOUR_API_KEY
/llm scan https://openrouter.ai/api/v1 YOUR_API_KEY
/llm scan "https://openrouter.ai/api/v1/chat/completions" YOUR_API_KEY
/llm scan http://localhost:11434

The optional scan key is used only for that scan and is not saved. If no scan key is provided, ViperLLM does not send the global default key to the scanned host.

Common endpoints include:

• OpenRouter: https://openrouter.ai/api/v1/chat/completions
• OpenAI: https://api.openai.com/v1/chat/completions
• LM Studio: http://localhost:1234/v1/chat/completions
• Ollama: http://localhost:11434/api/chat
• Anthropic: https://api.anthropic.com/v1/messages

Usage Walkthrough

1. Configure OpenRouter or another cloud provider:

/llm configure cloud
/llm set cloud apikey YOUR_API_KEY
/llm test
/llm ask Hello!

No key is bundled. Set defaultApiKey in the server config or use /llm set <id> apikey <key>.

2. Scan and configure LM Studio:

/llm scan http://192.168.1.50:1234
/llm configure local http://192.168.1.50:1234 qwen3.5-4b
/llm select local
/llm ask What block am I looking at?

With the default security policy, a player must be an operator to use a private/LAN endpoint.

2b. List available models from the endpoint:

/llm set local model list

3. Add custom behavior:

/llm set local prompt You are a redstone expert. Explain circuits simply.

4. Disable command access for your profile:

/llm commands

Global Configuration

Created at config/viperllm.json:

{
  "defaultMaxTokens": 500,
  "defaultTemperature": 0.7,
  "defaultTopP": 1.0,
  "defaultProvider": "OPENROUTER",
  "defaultModel": "google/gemma-4-31b-it:free",
  "defaultUrl": "https://openrouter.ai/api/v1/chat/completions",
  "defaultApiKey": "",
  "debug": false,
  "contextPlayerData": true,
  "contextInventory": true,
  "contextRecipes": true,
  "contextMaxRecipes": 300,
  "allowCommandExecution": true,
  "allowPrivateNetworkScanning": false,
  "allowPrivateNetworkScanningForOperators": true,
  "findBlockRadius": 16
}

Restart the server after editing this file.

Private-Network Protection

Normal players cannot scan or assign endpoints resolving to internal networks unless allowPrivateNetworkScanning is enabled. Operators are allowed by default through allowPrivateNetworkScanningForOperators.

Protected destinations include:

• localhost, *.localhost, and *.local
• 127.0.0.0/8
• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• Link-local, site-local, CGNAT, benchmark, multicast, and local IPv6 ranges
• Public hostnames that resolve to a protected address

This prevents normal players from turning /llm scan into an internal port scanner while still allowing operators to connect the server to local LM Studio or Ollama installations.

Per-Player Profiles

Profiles are stored at world/viperllm/players/<UUID>.json:

{
  "activeInstanceId": "local",
  "globalChatToggle": false,
  "allowCommandExecution": true,
  "chatMode": "PRIVATE",
  "instances": {
    "local": {
      "providerType": "OPENAI",
      "apiUrl": "http://192.168.1.50:1234/v1/chat/completions",
      "apiKey": "",
      "modelName": "qwen3.5-4b",
      "systemPrompt": "",
      "apiFormat": "openai",
      "settings": {
        "temperature": 0.7,
        "maxTokens": 500,
        "topP": 1.0,
        "chatPrefix": "7[LLM]f ",
        "responseColor": "7",
        "memoryTurnLimit": 20,
        "timeout": 0
      }
    }
  },
  "shortTermMemory": [],
  "longTermSummary": ""
}

API keys are stored as plaintext in server-side profiles. Protect the world directory, backups, and command logs.

Tool Reference

Example tool calls:

@search_recipes mace
@search_items diamond
@find_block diamond_ore
@read_book
@chest_inv
@read_sign
@look_around
@command time query daytime
@tools

The mod does not currently expose @get_item, @get_block, @get_entity, @broadcast, @force_reply, @get_online_players, or @get_user_stats handlers.

Command Safety

@command requires both controls:

1. Global allowCommandExecution: true
2. Player profile allowCommandExecution: true

Players toggle their profile setting with /llm commands. Commands execute through the owning player's command source. A normal player cannot make the LLM execute /op, /gamemode, or another command that the player could not execute directly.

Important Notes

• No API key is bundled or shared by default.
• Quoted and unquoted URLs are both supported.
• /llm configure <id> <url> <model> [api_key] accepts an optional API key at the end.
• /llm set <id> model list probes the endpoint directly for available models. Models are cached for tab completion.
• Scan keys are temporary; instance keys are persisted as plaintext.
• Private endpoints are operator/config restricted by default.
• The model-list book title is truncated to Minecraft's 32-character limit.
• Endpoint probing accepts base URLs and full endpoints.
• @command defaults to available globally and per player, but never elevates permissions.
• Recipe search falls back to fuzzy matching against the full item registry when no exact recipe match is found, supporting modded namespace:item queries.
• @find_block uses a single-word argument (e.g. @find_block diamond_ore). Sentences are rejected.

Built for servers that want tool-using AI assistants with no client installation, no bundled secrets, controlled LAN access, and no command-permission escalation.