Start

Installation

One machine, Python 3.9 or newer, and one model backend. Discord is optional. This is the shortest path to a running Aura.

What you need

Python
3.9 or newer
A model backend
Ollama is the simplest; LM Studio and llama.cpp also work; any OpenAI-compatible endpoint will do
Discord (optional)
a bot token, invited with bot and applications.commands
For the Minecraft mod
JDK 25, Minecraft 26.1.2, Fabric Loader 0.19.2 or newer

The five steps

1. Clone
git clone https://github.com/ymcxc-helloworld/Aura.git && cd Aura/aura
2. Install
pip install -r requirements.txt
3. Secrets
copy .env.example to .env and paste DISCORD_BOT_TOKEN
4. A model
Ollama: ollama pull gemma4:12b (or point ai.model.endpoint at your server)
5. Run
python3 main.py

No Discord? Set switches.hub: true and open http://127.0.0.1:8100/: her own place in the browser, with text channels, voice rooms and commands. Set discord.enabled: false to leave Discord out.

Check it works

Health
curl http://127.0.0.1:9877/health → {"status":"ok","protocol":"ws","clients":0}
Tests
python3 -m pytest tests/ -v — needs no model
In Discord
talk to her in a text channel, or /join to bring her into voice

The Minecraft mod

Build
cd minecraft-mod && ./gradlew build → build/libs/nexus-client-1.2.1.jar
Install
copy the jar into the client mods folder
Order
start Aura first, then Minecraft: the mod connects to ws://127.0.0.1:9700
Another machine
add -Daura.ws.url=ws://<ip>:9700 and set activity.ws_host, with AURA_ACTIVITY_KEY

When something goes wrong

DISCORD_BOT_TOKEN not set
edit .env; make sure the line is not commented out
Connection refused to Ollama
start it: ollama serve
No voice output
/join was not used, or Discord permissions
ModuleNotFoundError
pip install -r requirements.txt again