Installation

#What you need

Spigot or Paper 26.3, or a fork of them, like Purpur.
Java 25.
An Allay backend. The plugin talks to https://allay.chat out of the box; you can also run your own Allay Server.
Optional: GriefPrevention, PlaceholderAPI, and Plan. See Integrations.

Allay is on GitHub only for now, not on Modrinth or Hangar.

#Install the plugin

#With Docker (recommended)

If your server runs in itzg/minecraft-server, it fetches Allay itself. Give PLUGINS the jar's URL:

services:
  minecraft:
    image: itzg/minecraft-server:java25
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.3"
      PLUGINS: |
        https://github.com/allay-ai/minecraft/releases/latest/download/allay-spigot.jar
    ports: ["25565:25565"]
    volumes: ["./data:/data"]

Start the stack with docker compose up -d.
To pin a version, use its own jar instead, like https://github.com/allay-ai/minecraft/releases/download/v5.14.3/allay-spigot-5.14.3.jar.
To add the optional plugins, list them in MODRINTH_PROJECTS, one per line: placeholderapi, griefprevention, plan.

#By hand

Download allay-spigot.jar from the latest release.
Put it into plugins/.
Restart the server.

On its first start Allay writes plugins/Allay/config.yml and the texts in plugins/Allay/lang/, and downloads the country database into plugins/Allay/geoip/.

#Pick a backend

The backend runs the AI model, and the plugin runs the game tools. Choose one of two:

#The hosted backend (`allay.chat`)

Nothing to set up: server.url already points at https://allay.chat. You pay for the model with a subscription or bring your own key, as Paying for the model explains.

#Your own backend (Allay Server)

Run Allay Server next to Minecraft, and there's no billing at all.

Start Allay Server with SELFHOSTED=1 and a PLUGIN_TOKEN of 24 characters or more, as its self-hosting guide shows. Without SELFHOSTED the backend wants a license; without the token it answers no plugin.
In plugins/Allay/config.yml, point server.url at it and put the same token in server.token. In the same compose file that's the service name and port:
```
server:
  url: "http://allay:3000"
  token: "the backend's PLUGIN_TOKEN"
```
Run /allay reload.
Run /allay init as an operator. It gives you a one-time link, valid for 30 minutes, to the backend's admin panel, where you create the first account and set the model key.

/allay status then says the backend is self-hosted, and nobody needs to pay or link anything.

Next: Paying for the model