Self-hosting with Docker

Run your own Allay backend next to your Minecraft server. It takes Docker with Compose, an OpenRouter key, and about ten minutes. Your players then ask on your key, with no subscription and no limits.

#1. Pick a version

Every release publishes an image: ghcr.io/allay-ai/server:<version>. The newest one is on the releases page. Pin an exact version: there is no latest tag.

#2. Write compose.yaml

Make a folder and put this file in it. Replace the version and every change-me with its own random value (openssl rand -hex 32 makes a good one).

services:
  allay:
    image: ghcr.io/allay-ai/server:6.0.0
    restart: unless-stopped
    depends_on: [allay-mongo, allay-redis]
    # This machine only. Another machine reaches it through a reverse proxy with TLS.
    ports: ["127.0.0.1:3000:3000"]
    environment:
      MONGODB_URI: mongodb://allay:change-me-mongo@allay-mongo:27017/?authSource=admin
      MONGODB_DATABASE: allay
      REDIS_URL: redis://:change-me-redis@allay-redis:6379
      # Your own backend: no subscriptions, your plugins run on your key.
      SELFHOSTED: "1"
      # The plugin sends this as server.token; without it the backend answers no plugin. 24 characters or more.
      PLUGIN_TOKEN: change-me-plugin-token
      # Seals the keys you save in the admin panel. Keep it with your other secrets.
      SECRETS_KEY: change-me
      # The address you open in a browser; the panel's setup link starts here.
      PUBLIC_URL: http://localhost:3000

  allay-mongo:
    image: mongo:8.0
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: allay
      MONGO_INITDB_ROOT_PASSWORD: change-me-mongo
    volumes: [mongo:/data/db]

  allay-redis:
    image: redis:8-alpine
    restart: unless-stopped
    command: ["redis-server", "--save", "60", "1", "--requirepass", "change-me-redis"]
    volumes: [redis:/data]

volumes:
  mongo:
  redis:

MongoDB keeps players' memories and the panel's data, so its volume matters most. Redis keeps chat sessions, which expire within a day anyway. Both need version 8.0 or later. Neither publishes a port: only the backend reaches them, inside the Compose network, and both want their passwords. MongoDB takes its user only on the first start of an empty volume; for a volume from before, add the user with mongosh first.

#3. Start it

docker compose up -d
curl http://localhost:3000/api/health

The health answer names the version and says "billing": false. If it doesn't answer, docker compose logs allay tells why.

#4. Point the plugin at it

In plugins/Allay/config.yml on your Minecraft server, set the backend's address and its token:

server:
  url: "http://localhost:3000"
  token: "the PLUGIN_TOKEN from compose.yaml"

When Minecraft runs in the same Compose project, use the service name: http://allay:3000. Then run /allay reload. The plugin's provider block doesn't matter here: a self-hosted backend serves its plugins on its own key.

#5. Open the admin panel and add your key

1. In the game, as an operator, run /allay init. The plugin shows a link that works once, for 30 minutes.
2. Open it and create the panel's owner account.
3. On the Settings page, paste your OPENROUTER_API_KEY. Optionally set the model and a PERPLEXITY_API_KEY for faster web search.
4. Ask something in the game with /ask.

Settings apply to the next question, without a restart.

#Behind a reverse proxy

The panel works under any path prefix. Send the prefix in X-Forwarded-Prefix and set PUBLIC_URL to the address with it, such as https://example.com/allay. Expose only /admin and /api/admin/ to the internet; the plugin's /api/v2/* can stay on your internal network. Set TRUSTED_PROXIES to the proxy's address, so sign-in limits count each visitor rather than the proxy (see Security and privacy).

#Upgrading

Change the version in image:, then run docker compose up -d. Read the release notes first: they mark anything that needs a step from you.

From 5.x to 6.0: update the plugin to 6.0 first, add PLUGIN_TOKEN to the backend and server.token to the plugin, and stop publishing MongoDB and Redis. On its first start the backend files every memory under self, replaces players' ids in the statistics with pseudonyms, and drops chat sessions from before 6.0.

Next: Environment variables