Player access
This page explains how players join servers through the game proxy and link their panel account, and how the Owner and Admins configure authentication sources, the player entry policy, the login space and the lobby. The first two sections are for players; the rest are for the Owner and Admins.
Joining
Players connect with Minecraft Java Edition. The client version they need is shown on the panel's Account page under Prepare to enter Minecraft. The login space and the lobby use that version; a target server may need another version or mods, as its owner announces.
Each server is reached at <subdomain>.<root>, which can be copied from the panel's Servers list. When the game proxy listens on a non-default port, the address includes the port.
With the default player entry policy, joining works like this:
- The game proxy (Velocity) verifies the player's game identity: first with Mojang, then with the enabled third-party sources in order. See Authentication sources.
- The player enters the login space. A player without a linked panel account gets a bind code there and completes the web sign-in (see Account linking); a linked player passes straight through.
- If the target server is running, the player is moved there directly. If it is stopped or hibernated, Felis starts or resumes it according to its autostart policy; the player waits in the login space (or the lobby when the lobby server is enabled), hears a progress line every minute, and is moved over once the server is ready.
The Owner can change how players enter, for example straight to a main server or without account linking. See Player entry policy.
In the server list, each server's MOTD shows its current state (online, starting, stopped or hibernated); refreshing the server list never wakes a server.
Lobby menu
In the lobby, run /menu to open the server menu. The menu follows the player's client language and shows one tile per server, with the player's own servers first, marked ★ and Your server:
| Tile | Meaning |
|---|---|
| Join (green) | The server is running; click to join. |
| Claim & Start (gold) | The server has no owner; click to claim and start it. |
| Start (red) | The server is stopped; click to start it and join once it is ready. |
| Resume (red) | The server is hibernated; click to resume it and join once it is ready. |
| Can't start (grey) | The player may not start it; the reason appears in the tile's description and in chat. |
In-game commands
| Command | Purpose |
|---|---|
/link | Get a one-time bind code for linking a panel account. |
/menu | Open the server menu in the lobby. |
/felis | Show the proxy and routing status; /felis help lists every command. |
/felis server | List the servers the proxy knows. |
/felis go <server> | Start a server and move you in when it is ready. |
/felis lobby | Return to the lobby. |
/felis claim | Claim the server you are on. |
/felis migrate | Start an account migration that moves your servers to another account. |
/felis web | Show the web console addresses. |
/felis web op approve <code> | Review and approve a pending operator sign-in; Admins and the Owner only. |
/invite <player> | Invite an online player to the server you are on; they accept with /invite accept or decline with /invite deny. |
The /felis commands are not available in the login space; finish signing in first.
Messages when a join is refused
| Message | Cause |
|---|---|
| Not allowed to start the server | The server's autostart policy does not let this player wake it. |
| The server is under maintenance | A backup, restore or file change is in progress; retry once it ends. |
| The server sat idle too long and its world is being archived | World cleanup is archiving the world. |
| Try again later | The platform is at its running server limit. |
| Login timed out, please reconnect | The web sign-in was not completed within the login timeout. |
| This game identity is barred | The identity is on the global blacklist. See Global blacklist. |
For other join problems, see Players cannot join.
Account linking
Account linking binds a panel account to a verified game identity. Claiming, starting, stopping and managing servers require it. A bind code has 8 characters, is valid for about 10 minutes and can be used once.
First sign-in to the player console
Players need no prior registration; a bind code from the game creates their account and signs them in:
- Connect with Minecraft Java Edition. The login space opens a login book and posts the bind code and the player console link in chat.
- Open the link in the system browser. It is usually
https://console.<root>; when the platform uses direct access, the link carries the panel port, for examplehttps://console.<root>:30443, see Access methods. Do not use the in-app browser of WeChat or QQ, where passkeys do not work. - Select Sign in with Bind Code, enter the code and select Verify & Sign In. Felis creates the account, links the game identity and signs you in.
- Return to the game. Once the login space sees the link, it sends you to the target server (or to the lobby when the lobby server is enabled and no server was matched).
The login space waits 600 seconds by default and then disconnects; reconnect for a new bind code. Afterwards, run /link in game at any time for a new code to sign in with. Once you verify an email address or register a passkey on the Account page, you can also sign in with an email code or a passkey.
Linking an existing account
- Run
/linkin game to get a bind code. - In the panel, open Account, enter the code under Minecraft link and select Link.
A game identity can be linked to one panel account only. For link errors, see Account link and claim errors.
The Owner and Admins can also link by profile lookup: on the Account page, choose an Authentication source, enter a Minecraft role name or UUID, select Look up role, then Confirm role link. When a source has no role lookup API configured, use an in-game bind code instead. Game identities of Admins and the Owner cannot be used to sign in to the player console; they sign in to the operator console. See Roles.
Account settings
The Account page also offers:
- Email Verification: enter an email address to receive a six-digit code, valid for 10 minutes.
- Passkeys: register or delete passkeys. An account's only passkey cannot be deleted while its email address is unverified.
- Signed-in devices: review browser sessions, revoke an unrecognized device, or select Sign out other devices.
- API keys: let scripts call external interfaces as this account. Keys can be created only after the platform Owner turns the feature on. On Account → API keys, select Create key, enter a name and choose a validity period: 30 days, 90 days, 1 year or no expiry, with 90 days as the default. The key is shown once, immediately after it is created, and cannot be viewed again after the dialog is closed, so copy and save it first. Each account can hold up to 10 keys; once the limit is reached, revoke the keys no longer in use before creating new ones. Select Revoke in the list to stop a key at once; scripts that use it stop working immediately. For the request format, see API keys.
Panel appearance
Select Theme at the bottom of the sidebar to choose Light, Dark or System. The default follows the system. The choice is stored in the current browser and remains in effect after refreshing or reopening the panel. A fixed Light or Dark choice is unaffected by system appearance changes. On mobile, the theme selector is in the top bar.
Account migration
An account migration moves every server of a retired account to another account:
- With the account being retired, run
/felis migratein game. - Sign in to the retired account in the panel, open Account → Account migration, and verify your identity with Confirm with passkey or Send a code to my email.
- Enter the Account ID shown on the destination account's Account page and select Issue code. The transfer code is shown once, and a notification goes to the verified email address.
- Sign in to the destination account, enter the transfer code under Account migration and select Redeem.
After the migration, the retired account is disabled. If the destination account's quota is too small, the redemption is refused and the code stays valid; redeem it again once the quota is raised. Scheduled tasks on the moved servers are switched off until the new owner reviews and saves them.
Authentication sources
Authentication sources decide which game identities the game proxy accepts. Mojang verification is built in, always enabled and checked first. Under Platform → Authentication sources, the Owner adds third-party Yggdrasil providers, which are checked from top to bottom after Mojang.
Adding a source
Open Platform → Authentication sources and select Add source.
Fill in the fields:
Field Description Permanent source ID A unique ID without colons or surrounding spaces. It becomes permanent when saved, which preserves player UUIDs and account links. Name collision prefix 1–4 letters or digits, unique regardless of case. When a player of this source has the name of an official account, their in-game name becomes <prefix>_<name>.Authentication endpoint (hasJoined) The full hasJoinedURL. HTTPS is required; HTTP is allowed only for localhost or private IPs. No query or fragment.Role lookup API root (optional) Leave empty for a standard hasJoinedURL; for a custom path, enter the Yggdrasil API root so roles can be looked up by name or UUID.Check the endpoint with Test connection on the source card. The check passes when the endpoint answers HTTP 204 for an unused session; it saves nothing and checks neither launcher configuration nor the role lookup API.
Use Move source up and Move source down to set the order.
Select Save & apply and verify your identity.
A saved configuration applies to the next login and role lookup without a restart, and online players stay connected. The configuration saved in the panel takes precedence over the [[auth_source]] list of the installation configuration, which the page imports when it is first opened.
Identities, disabling and deleting
- Official players keep their Mojang UUIDs. Players of a third-party source get UUIDs in a namespace of their own, keyed by the permanent source ID, so identities of different sources never collide.
- Clearing Enabled and saving stops accepting that source's logins. The ID stays reserved, and enabling the source again restores the same player identities.
- The bin icon on a saved source deletes it after a confirmation; the deletion applies with Save & apply. Its players can no longer sign in, and their account links, server data and bans are kept. The ID stays reserved for the endpoint the source used: a source added again with the same ID and the same endpoint restores those identities, and the ID cannot be used with another endpoint.
- Changing a source's endpoint changes who verifies the identities in its namespace; keep it pointed at the same trusted service.
- Players' launchers must use the same provider.
- If the database cannot be read, new authentication is refused; Felis never falls back to an outdated or disabled source.
- If another Owner changed the configuration in the meantime, saving is refused and your draft is kept; select Discard changes and Reload before editing again.
Player entry policy
The player entry policy decides where the proxy sends a player after verifying their identity, independently of game identity verification and panel account linking. The Owner configures it under Platform settings → Player entry → Player entry policy.
On standard installations, Use lobby server controls whether the lobby system server runs. Saving with it enabled automatically creates or starts the lobby (about 800 MB of memory) for post-login server selection and startup waits; saving with it turned off stops the lobby, hides the Lobby entry mode, and handles web sign-in and startup waits in the login space (Limbo).
| Entry mode | Destination after authentication |
|---|---|
| Lobby | The lobby, where the player chooses a server (available when Use lobby server is enabled). |
| Direct to main server | The selected Main server, whatever hostname the player connected with. The main server's autostart policy still decides who may start it. |
| Route by hostname | The server matching the connection hostname. Default destination (optional) handles unmatched hostnames; without one, connections that require web sign-in enter the lobby when the lobby is enabled, or are told after sign-in to reconnect using a server's address when the lobby is disabled, and all others are refused. |
With Require panel account linking on, players must complete web sign-in in the login space. With it off, game identity is still verified, and players can link a panel account separately with /link.
When the destination is offline:
| Option | Behavior |
|---|---|
| Start automatically and wait | Applies the usual wake permission, maintenance, running limit and cooldown checks. Choose a running Startup waiting space: the login space (Limbo) or the lobby; with web sign-in required, the lobby is used when enabled, otherwise the login space. An unlinked player can start the destination only if its autostart policy permits their game identity; being the main server grants no startup right. If the start fails or times out, the player is told why, and a connection waiting in the login space is then disconnected. |
| Enter a fallback server | Sends the player to another running Fallback server. The proxy never starts the fallback server itself, and refuses the connection when neither destination is available. |
| Reject with an explanation | Refuses the connection with an explanation; no waiting space is needed. |
Until a policy is first saved, a fresh installation with the lobby left off uses the default: lobby disabled, route by hostname, require panel account linking, start automatically and wait in the login space; an installation that enabled the lobby at install time or an existing deployment keeps the lobby enabled and waits in the lobby.
A platform without a lobby (small-host profile) offers neither Use lobby server nor the Lobby entry mode, and web sign-in and startup waits always take place in the login space.
Single-server deployment
When you run a single server, players can go straight to it:
- Under Entry mode, select Direct to main server, and select the server under Main server.
- Turn off Require panel account linking.
- Choose what happens when the destination is offline.
- Select Save entry policy and verify your identity.
A running main server then accepts authenticated players directly, without the login space or the lobby. Game identity verification and the global blacklist still apply; the setting does not enable offline mode or change authentication sources.
The proxy reads a saved policy within 15 seconds and applies it to new connections; players already online keep the policy they connected with. Turning off Use lobby server and saving stops the lobby automatically; an unused login space can be stopped under Login & lobby. Running felis setup again preserves the desired state of the system servers. The API and the game plugins must be on the same version to use this feature.
The Startup and wake policy card on the same tab sets the running server limit and the wake cooldown. See Startup and wake policy.
Customizing the login space and lobby
Under Admin → Login & lobby, Admins customize the scenes, guidance and rules players meet when they join. Under Choose a space, select Login space or Lobby; the console page of each system server also links here with Customize login space and Customize lobby.
The login space runs Limbo and is where players authenticate; the lobby runs Paper and offers the server menu. Neither stops when idle.
Settings
Settings can be saved while the space runs and take effect on its next start or restart. After saving, select Restart & apply to apply them now; the restart disconnects players in that space. Settings are stored in /data/felis-experience.json on the space's data volume, independently of the image.
Lobby settings:
| Group | Settings (defaults) |
|---|---|
| Welcome & menu | Chinese menu title, English menu title, Chinese welcome message, English welcome message; Send a welcome message on join (on); Open the server menu on join (off). The welcome message carries a clickable server menu. |
| Player behavior & protection | Default player game mode (Adventure); Return to world spawn on join, Protect against building and damage, Prevent player damage, Prevent hunger, Return to spawn after a void fall (all on). Players with building access keep their own game mode. |
| World environment | Difficulty (Peaceful); Fixed time (0–23999, default 6000); Freeze world time, Keep clear weather, Keep inventory on death, Respawn immediately (on); Allow PvP, Allow natural mob spawning, Allow mob griefing, Allow TNT explosions, Show advancement announcements (off). |
Login space settings are in the Login guidance & waiting group: Login book title, Login book author, Login page heading, Login link text, Login instructions, Open the login book automatically (on), and Login timeout (30–3600 seconds, default 600). Bind codes and sign-in links are generated by Felis, and the chat prompts stay on. An explicitly configured FELIS_LOGIN_TIMEOUT_SECONDS environment variable overrides the login timeout set here.
Text fields hold up to 512 characters. If the settings file is damaged, the game uses defaults for whatever it cannot read; the page keeps the settings that are still valid, and saving writes them over the file.
Maps, plugins and files
The Content & maintenance area offers:
- Maps & scenes:
- Lobby: back up and stop the lobby, upload a world ZIP in the file manager and extract it at the root, confirm that the world folder directly contains
level.dat, setlevel-nameinserver.properties, then start it. Spawn comes from the map; change it withsetworldspawn x y zin the lobby console. - Login space: stop it, upload your scene as
spawn.schemat the root, then start it; adjust the spawn position inserver.properties. The login space uses Limbo schematics and supports neither Paper world maps nor Paper plugins.
- Lobby: back up and stop the lobby, upload a world ZIP in the file manager and extract it at the root, confirm that the world folder directly contains
- Plugins & plugin settings: upload plugin JARs and edit their configuration. Plugins must match the space's core and version; the bundled Felis plugins and LuckPerms are refreshed from the image at startup.
- Advanced file manager: edit server properties, world settings and plugin data. Authentication forwarding settings are maintained by Felis.
- Console & runtime logs: read logs and run lobby commands. Limbo has no RCON, so edit the login space's configuration in the file manager.
- Map backups & restore: back up before replacing maps, plugins or images, or restore a saved backup.
- Lobby builder access: while the lobby runs, enter a Minecraft player name and select Allow building or Deny building to grant or revoke
felis.lobby.build. The permission defaults to operators; you can also runlp user <name> permission set felis.lobby.build truein the lobby console.
The file manager requires the space to be stopped. While the login space is stopped, new players cannot join. A replacement image must keep the Felis login or menu plugin and support the proxy's forwarding protocol; images and resources are set on the system server's Settings tab. For how the images are built and behave, see Lobby image and Login space image.
Global blacklist
The global blacklist records game identities that are barred from logging in, matched by UUID. A barred identity is refused when the game proxy verifies it and is disconnected in the login space, whatever the player entry policy; the blacklist also applies with Require panel account linking turned off. Because matching is by UUID, an official player with the same name but a different UUID is never affected. The blacklist has no page in the panel.