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