Branding your server

Set a square server icon and a wide banner for the launcher and website. Both are optional; servers without images use a placeholder.

Upload images from Warden. Icon changes do not require a server restart.

For the in-game Escape menu, use Pause menu customization. Its Lua accent and resource logo are separate from the launcher icon and website banner.

What the two images are#

They are files that live next to your server.jsonc, referenced by identity.icon and identity.banner as relative paths — not URLs. Your server reads the bytes, sends them to the master inside its registration, and the master stores them by content hash and serves them from /api/v1/icons/{sha256} and /api/v1/banners/{sha256}. You never upload anything to a CDN, and there is nothing to host yourself.

The rules that actually apply#

Several guards sit between your file and a picture on a page, and they are not all equally strict. The bounds below are the intersection — an image that satisfies them works everywhere. Warden enforces exactly this list, so if the panel accepts your file, the website will draw it.

Icon#

The 64 px floor is the one that catches people. A 32×32 icon is accepted by an older server build and by the master, and then silently shows a placeholder on the website. Warden refuses it up front and tells you the size you gave it.

Banner#

The one that is easy to miss: the pair has a combined budget#

Both images travel base64-encoded inside a single registration request to the master, and that request is capped at 512 KiB. So the two files together must stay under about 378 KiB of raw bytes — well below the 2 MiB a banner is allowed on its own.

This matters more than it looks. Going over does not produce a missing image: the whole registration is refused, and your server does not appear in the server list at all. Warden checks the pair before it writes anything and tells you how much to shave off; a server started with an over-budget pair already on disk logs an explicit error instead of failing silently.

A PNG exported at a sensible palette is nowhere near this. A photographic banner saved as a 24-bit PNG easily is — export it as JPEG or WebP.

Uploading from Warden#

1. Open your panel and sign in (see Warden if you have not set it up yet). You need the config.edit permission — the owner account has it.
2. Go to Config. Under Identity there is a picker for the icon and one for the banner, each with the rules printed next to it and a preview of what is currently set.
3. Choose a file. The panel decodes it in your browser and checks it immediately, so a wrong size is refused before anything is uploaded — with the bound and your file's actual dimensions in the message, for example "Icon must be at least 64×64 px; yours is 48×48."
4. Under the two pickers, a line shows how much of the combined budget you are using.
5. Press Apply changes.

Your server writes the file next to its config (server-icon.png, server-banner.png) and updates server.jsonc to point at it.

What happens next, and what needs a restart#

Images do not need a restart. Applying them re-sends your server's registration to the master straight away, with the new pictures in it. The panel tells you what happened — "images written; published to the master" — and the launcher and website pick the change up on their next refresh, within about a minute.

Everything else in that form — name, description, tags, visibility, player cap, public endpoint — is baked into the options your server started with, and those do need a restart. Warden only shows the "restart required" banner when a restart is genuinely required, so when you see it, it means something.

To remove an image, use Remove icon / Remove banner and apply. That clears the reference; the file stays on disk.

Doing it by hand instead#

Warden is not required. Put the files next to server.jsonc and name them in the identity block:

"identity": {
  "name": "My Server",
  "icon": "server-icon.png",
  "banner": "server-banner.png"
}

The paths are relative to the config file and may not escape its directory or be symlinks. Restart the server to pick them up. If an image is outside the bounds above, the server still starts and logs a warning saying which bound it missed — worth reading, because that is the difference between a picture and a placeholder.

Banner support needs a recent master#

Banners are newer than icons. A master that predates them accepts the registration and stores the icon, but its catalogue response carries no banner field, so nothing shows the banner anywhere — no error, just no hero image. If your icon appears and your banner does not, and everything above checks out, this is almost certainly why. Icons are unaffected.

When something does not show up#