Installation

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"]

1. Start the stack with docker compose up -d.
2. 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.
3. To add the optional plugins, list them in MODRINTH_PROJECTS, one per line: placeholderapi, griefprevention, plan.

By hand

1. Download allay-spigot.jar from the latest release.
2. Put it into plugins/.
3. 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.

1. 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.
2. 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"

3. Run /allay reload.
4. 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