Configuration

Allay keeps its settings in plugins/Allay/config.yml. Every key has a default, so you can delete the ones you don't change. Texts players read don't live here: they're in lang/, see Languages.

Edit plugins/Allay/config.yml.
Run /allay reload. No restart needed.

A config.yml from MCBuddy 2.3 or 2.4 still loads, and a 2.3 config's texts are skipped, since they live in lang/ now.

#Backend

Key	Default	What it sets
`server.url`	`https://allay.chat`	The Allay backend that answers questions
`server.name`	empty	Your server's name in the backend's admin panel, like `Moonlands`: 2–32 letters, digits, spaces, or `. _ ' -` (Allay Server 6.7+). No two servers on a backend share one; a taken name shows as an error in the log. Empty: the panel shows the server's random id
`server.address`	empty	Where players join, like `mc.example.com`. Allay sends it with the game port, and the backend's admin panel shows it next to your server (Allay Server 6.6+). Empty: the game's `server-ip`, if set
`server.token`	empty	A self-hosted backend's `PLUGIN_TOKEN` (Allay Server 6.0+). Leave it empty for `allay.chat`, which knows your server by its license. It never goes to the log

#Who pays

Key	Default	What it sets
`provider.mode`	`hosted`	`hosted`: a subscription; `byok`: your own key. Anything but `byok` counts as `hosted`
`provider.byok.base_url`	`https://openrouter.ai/api/v1`	Any OpenAI-compatible API
`provider.byok.api_key`	empty	Your key. It never goes to the log
`provider.byok.model`	empty	Empty: the backend's default. It must be able to call tools
`provider.byok.search_model`	empty	Empty: no web search. On OpenRouter, say, `perplexity/sonar`

The subscription's license lives in license.key, not here. See Paying for the model.

#Languages and the country database

Key	Default	What it sets
`locales.default`	`en`	The language for players nothing else matches, and for the console
`locales.sources`	`[ ip, client ]`	Where a player's language comes from, in order
`locales.countries`	ru, es, pt, de lists	Language → the ISO 3166 country codes that get it
`geoip.enabled`	`true`	Look up the country by IP
`geoip.url`	DB-IP's free country database	Where to download it; `{year}` and `{month}` fill in
`geoip.refresh_days`	`30`	Download a fresh one once it's this old

#HTTP

Times are in seconds.

Key	Default	What it sets
`http.call_timeout`	`300`	The whole question, from asking to the last word
`http.connect_timeout`, `read_timeout`, `write_timeout`	`10`, `300`, `10`	Connection timeouts
`http.tool_timeout`	`10`	How long a game tool may run before Allay gets an error
`http.max_idle_connections`, `keep_alive_duration`, `max_requests_per_host`	`5`, `300`, `5`	The connection pool
`http.follow_redirects`, `retry_on_connection_failure`, `compression_enabled`	`true`	Client behavior
`http.logging`	`false`	Log each request's method, URL, and status, never the body
`http.custom_headers`	`{}`	Extra headers for every request. An `X-OpenRouter-Token` from before 5.0 still works as your own OpenRouter key

#Look and sound

Key	Default	What it sets
`ui.action_bar.enabled`	`true`	The live status in the action bar
`ui.action_bar.spinner`	`·✢✳✶✻✽`	Spinner frames; it runs through them and back
`ui.action_bar.frame_millis`, `verb_seconds`	`120`, `3`	How long one frame shows; how often the verb changes
`ui.tool_lines.enabled`	`true`	A chat line for each tool Allay uses
`ui.particles.*`	on, `ENCHANT`, 3, 2.0, 250 ms	Particles over the player's head while Allay works: `enabled`, `type`, `count`, `height_offset`, `animation_interval`
`ui.chat_status.enabled`	`false`	Also say “asking the assistant…” in chat
`ui.book_author`	`Allay`	The author of the books Allay writes
`ui.sounds.enabled`	`true`	Sounds at all
`ui.sounds.success_`, `error_`, `thinking_*`	the allay's own sounds	`_sound`, `_volume`, and `_pitch` for the answer, an error, and thinking. Any Bukkit sound name; 1.0 is the mob's own volume
`ui.sounds.pitch_variation`	`0.1`	Each sound's pitch moves by up to this, so answers don't all sound the same
`ui.sounds.public_answer`	`true`	Everyone who reads an `/askall` answer hears a quiet chortle

#Tools

Key	Default	What it sets
`tools.enabled.<tool>`	`true` (`show_draft`: `false`)	Switches a tool off; a switched-off tool is never offered to Allay. The config file lists every tool with a line on what it does
`tools.operator.enabled`	`true`	`false`: Allay changes nothing, even for operators
`tools.operator.<tool>`	`true`	`give_item`, `teleport`, `set_gamemode`, `heal`, `apply_effect`, `set_time`, `set_weather`; operators only
`tools.reminders.max_pending`	`10`	Reminders one player can have waiting
`tools.notes.max_per_player`	`200`	Notes in one player's notebook
`tools.goals.max_per_player`	`5`	Goals one player can have at once
`tools.point_to.default_seconds`	`30`	How long a way trail lasts when nobody says
`tools.point_to.follow_seconds`	`180`	The same for a trail to another player
`tools.point_to.max_seconds`	`600`	The longest trail (10–3600)
`tools.show_marks.default_seconds`, `max_seconds`	`30`, `600`	How long marks stay; at most (10–3600)
`tools.show_marks.max_marks`	`64`	Marks at once (1–256)
`tools.show_marks.radius`	`48`	How far from the player a mark may be (8–128)
`tools.locate_biome_radius`	`2048`	The biome search radius in blocks (64–6400); it runs on the main thread
`tools.villager_radius`	`32`	How far to look for villagers (8–64)
`tools.locate_structure_radius`	`64`	The structure search radius in chunks; it runs on the main thread, so keep it small
`tools.server.hidden_plugins`	`[]`	Plugins `get_server` leaves out, such as an anti-cheat

scan_nearby_containers, find_item, look_at, and show_marks see only containers the player could open. See Integrations.

#Automation

Key	Default	What it sets
`automation.enabled`	`true`	`false`: no automation at all
`automation.chests.enabled`, `furnaces.enabled`, `brewing.enabled`, `crafting.enabled`	`true`	Each kind of agent
`automation.chests.gap`	`6`	“All nearby” reaches chests across gaps of up to this many blocks; more reaches further and takes longer
`automation.chests.max`	`64`	Chests one agent may take at once (1–256)
`automation.chests.undo_minutes`	`5`	How long [Put back] works
`automation.max_tasks`	`2`	Agents one player may run at once, helpers included
`automation.max_minutes`	`30`	An agent stops after this long
`automation.max_wakes`	`40`	Requests to the model one agent may make; this bounds its cost
`automation.max_wait_seconds`	`600`	The longest an agent sleeps before it looks again
`automation.radius`	`32`	How far its furnaces, stands, tables, and chests may be (4–52)
`automation.pause_distance`	`64`	It pauses while its player is farther than this from where it started
`automation.line_of_sight`	`true`	Furnaces, stands, and tables must be in plain sight

#Spending

Key	Default	What it sets
`quota.enabled`	`false`	Spending limits at all
`quota.monthly_usd`	`20.0`	What the whole server may spend a month
`quota.daily`	`true`	Open the budget day by day
`quota.tiers`	`default: 1`	Tier → weight, given by `allay.quota.<tier>`
`models`	`{}`	Tier → model, given by `allay.model.<tier>`

Paying for the model explains the split.

#Everything else

Key	Default	What it sets
`privacy.consent`	`true`	Before a player's first question, Allay shows what it sends and keeps and asks them to agree, with buttons; nothing about them reaches the backend before they do. The backend keeps the answer (Allay Server 6.1 and newer; an older one can't, and Allay asks nobody)
`privacy.policy_url`	empty	The privacy policy the notice links to. Empty: allay.chat's, or no link with `server.token` (a backend of your own)
`askall.cooldown_seconds`	`30`	How long a player waits between two public questions
`time.zone`	`Europe/Moscow`	The players' default IANA time zone; each can tell Allay theirs
`blocked_commands`	`ban`, `op`, `stop`, `reload`…	Commands `/askx` never runs, whatever the request

Next: Languages