# Nexa AI (Minecraft Mod + Paper Plugin) > Note: This page includes detailed information about the mod/plugin. If it feels too much, you can skip straight to using it. Just install the mod/plugin and run the command /nexa to get started right away. Nexa AI adds an ai agent into Minecraft. - Works as a **Fabric / Forge mod** (clients + servers) - Also available as a **Paper plugin** Players can talk to Nexa in chat and (with the right permissions) let it run server tools like teleporting, locating structures, changing weather/time, and more. ## Features * Chat with Nexa directly: `/nexa ` * Agent modes: * **Ask-before-act** (default): privileged actions are previewed and require confirmation * **Autonomous**: Nexa can execute allowed steps automatically (guardrails still apply) * Per-player request limits + global cooldown (server guardrails) * Custom assistant name + personality prompt * Fabric/Forge client UI (press **`N`** to open Nexa chat/config) * Built-in tools (“function calling”) for server-aware actions and lookups * Optional join/idle **auto messages** (can be turned off) * Update notifications + feedback sending (via the proxy) ## Supported Targets * **Fabric**: Minecraft `1.21.11` and `1.20.1` * **Forge**: Minecraft `1.21.11` and `1.20.1` * **Paper**: Minecraft `1.21.11` ## Commands ### Chat * `/nexa ` — chat with Nexa * `/nexa confirm` — approve queued actions (ask before act) * `/nexa cancel` — cancel queued actions ### Configuration * `/nex-config clearchat` — clear your chat history * `/nex-config feedback ` — send feedback (rate limited) * `/nex-config mode show` — show your current mode * `/nex-config mode ` — set your mode * `/nex-config limits status` — show limits and cooldown * `/nex-config limits maxrequests <1..15>` — set max requests (**requires privileges**) * `/nex-config limits cooldown ` — set global cooldown (**requires privileges**) * `/nex-config custom name ` — change assistant name (**server: requires privileges**) * `/nex-config custom prompt ` — set personality prompt (**server: requires privileges**, max 1000 chars) * `/nex-config custom reset` — reset name/prompt to defaults (**server: requires privileges**) * `/nex-config custom show` — view your current custom settings * `/nex-config automessages enable|disable|status` — toggle join/idle auto messages (server wide) ### BYOK (Bring Your Own Key) BYOK is **per-player** and bypasses the default proxy for chat calls. * `/nex-byok status` — show BYOK status * `/nex-byok toggle enable|disable` — enable/disable BYOK * `/nex-byok provider ` — choose provider * `/nex-byok apikey ` — set API key (cloud providers) * `/nex-byok endpoint ` — set endpoint (local/custom providers) * `/nex-byok model ` — set model name * `/nex-byok tools enable|disable` — enable/disable tool calling (useful for local endpoints) * `/nex-byok test` — test current BYOK config ## Modes ### **Ask-before-act** Nexa proposes an action preview and waits for confirmation before running any privileged tool. Approve via the clickable buttons in chat, or with `/nexa confirm` (deny with `/nexa cancel`). privileged tools are queued for approval (30s) and can be approved via `/nexa confirm`. ### **Autonomous** Nexa can execute allowed tools without an explicit prompt. Guardrails still apply (cooldowns, limits, and required privileges). ## AI Provider ### **Default AI Service** By default, Nexa uses the default services that are setup by me. It is free but you could expearence issue like rate limiting, overload, etc. So it is recommened to BYOK. ### **BYOK Mode** BYOK (Bring Your Own Key) lets each player use their own provider + key. * Providers: **Google**, **OpenAI**, **OpenAI-compatible (custom endpoint)**, **Ollama**, **LM Studio** * Configure via `/nex-byok ...` (or the Fabric/Forge GUI) * For best results, choose a model that supports **tool calling / function calling** Note: BYOK settings (including API keys) are stored on the server in the world data file. ## Permissions & Privileges Nexa uses two permission nodes across all platforms: * `nexa.use` — access to `/nexa`, `/nex-config`, and `/nex-byok` * `nexa.admin` — administrative actions (guardrails + privileged tools) ## Requirements & Installation ### Java * Minecraft **1.20.1**: typically runs on **Java 17** * Minecraft **1.21.11**: typically runs on **Java 21** ### Install * **Fabric**: install Fabric Loader + **Fabric API**, then drop the `nexa-fabric*.jar` into `.minecraft/mods/` * **Forge**: drop the `nexa-forge*.jar` into `.minecraft/mods/` * **Paper**: drop `nexa-paper-.jar` into `plugins/` and restart Tip: the server-side commands work with just the server install; the Fabric/Forge **GUI** is available when installed on the client. ## Guardrails (Server) * Agent mode: `ASK_BEFORE_ACT` or `AUTONOMOUS` * Per-prompt request budget (`maxrequests`) and a global cooldown (`cooldown`) * Privileged actions are previewed (and can be denied) in ask-before-act mode ## Fair Use, Safety, and Privacy * Community built: please don’t abuse the service (rate limits/guardrails exist for a reason). * AI provider terms: when using the default service, prompts/responses are sent to Google Gemini. When using BYOK, your chosen provider’s terms/policies apply. * Nexa can be wrong. Treat outputs as suggestions, especially for commands/actions. * Harmful, abusive, illegal, or exploitative use is not tolerated. Repeated abuse may lead to denial of service. ### Logging & Data * **Server/world file:** Nexa stores persistent settings per-world in `chatmc_locations.json` (saved locations, mode/guardrails, BYOK config, etc.). * BYOK API keys are stored here (server-side). Only grant server file access to people you trust. * **Feedback:** `/nex-config feedback ` sends your feedback message (and identifying metadata) to the proxy. ## Support & Contributions If you encounter issues, have feedback, or wish to contribute to Nexa AI, please join my Discord server and report there. Discord: https://discord.gg/Wvst4znsgk

Mod_MC