Status Adapter

The status adapter controls what players see in the Minecraft server list — the MOTD, player count, version, and favicon. Each route can use a different status adapter.

Fixed Adapter (Default)

Returns a static, preconfigured status response.

routes:
- hostname: "mc.example.net"
  status:
    type: fixed
    name: "My Network"
    description: "\"Welcome to our server!\""
    favicon: "data:image/png;base64,..."
    enforces_secure_chat: true
    preferred_version: 777
    min_version: 766
    max_version: 1000

Fields

Field	Type	Default	Description
name	string	"Passage"	Server name displayed in the version field
description	string	"\"Minecraft Server Transfer Router\""	MOTD as a JSON text component
favicon	string	(built-in icon)	Base64-encoded 64x64 PNG (data:image/png;base64,...)
enforces_secure_chat	bool	true	Whether the server enforces secure chat
preferred_version	integer	777	Protocol version shown in the server list
min_version	integer	0	Lowest protocol version reported as compatible
max_version	integer	1000	Highest protocol version reported as compatible

MOTD Formatting

The description field uses Minecraft’s JSON text component format:

# Simple text
description: "\"Welcome!\""

# Colored text
description: '{"text":"Welcome!","color":"gold"}'

# Multi-line with formatting
description: '{"text":"","extra":[{"text":"My Network\n","color":"gold","bold":true},{"text":"Join now!","color":"gray"}]}'

Favicon

Generate a favicon from a 64x64 PNG image:

echo -n "data:image/png;base64,$(base64 -w 0 server-icon.png)"

Protocol Versions

Some reference points:

Version	Protocol
26.3	777
26.2	776
26.1	775
1.21.11	774
1.21.9	773
1.21.6	771
1.21.2	768
1.21	767
1.20.5	766

766 (1.20.5) is the lowest version that supports the transfer packet. See the protocol version list on the Minecraft Wiki for the current, complete table.

These fields only affect the server list

min_version and max_version do not reject logins. If the client’s protocol version falls inside [min_version, max_version], Passage echoes the client’s own version back so the server list shows the server as compatible; otherwise it reports preferred_version, which makes the client display “Outdated client!” or “Outdated server!”. A player can still attempt to log in either way.

The only login that Passage itself rejects on version grounds is one below protocol 766, which cannot reach the configuration phase at all. Those clients receive the disconnect_unsupported message, whose {preferred} parameter is filled with this adapter’s name. Set name to the version you want those players to install (e.g. "26.3") if you rely on that message.

---

HTTP Adapter

Fetches status from an HTTP endpoint. Responses are cached to avoid hitting the endpoint on every server list ping.

routes:
- hostname: "mc.example.net"
  status:
    type: http
    address: "https://api.example.com/minecraft/status"
    cache_duration: 60

Fields

Field	Type	Default	Description
address	string	"http://localhost:8080"	HTTP endpoint URL
cache_duration	integer	60	Cache duration in seconds

Endpoint Requirements

The endpoint must accept a GET request and return JSON matching the Minecraft status response format:

{
  "version": {"name": "My Network", "protocol": 777},
  "players": {"online": 42, "max": 100, "sample": []},
  "description": "{\"text\":\"Welcome!\",\"color\":\"gold\"}",
  "favicon": "data:image/png;base64,...",
  "enforcesSecureChat": true
}

description is a string, not an object

Passage expects description to be a JSON string whose content is the text component — exactly like the description field in the configuration file. Returning a nested object ("description": {"text": "..."}) fails to deserialize and the ping is answered with an error.

Only version is required. players, description, favicon and enforcesSecureChat may be omitted or null.

Tip

The HTTP adapter is great for status pages that aggregate player counts across your backend servers or show dynamic information. Set cache_duration to at least 10-30 seconds to avoid overloading your status endpoint.

---

gRPC Adapter

Delegates status generation to an external gRPC service for full control over the response.

routes:
- hostname: "mc.example.net"
  status:
    type: grpc
    address: "http://status-service:50051"

Fields

Field	Type	Default	Description
address	string	""	The gRPC service endpoint URL

gRPC Service Definition

The service must implement the Status service from status.proto:

service Status {
    rpc GetStatus(StatusRequest) returns (StatusResponse);
}

The StatusRequest includes:

• client_address (Address): The client’s network address
• server_address (Address): The address the client connected to
• protocol (uint64): The client’s Minecraft protocol version

See the gRPC Protocol Reference for full message definitions and the Custom gRPC Adapters guide for implementation examples.

---

Choosing a Status Adapter

Use Case	Recommended Type
Static server with fixed MOTD	fixed
Dynamic player count or rotating MOTD	http
Complex logic (per-player status, A/B testing)	grpc