Skip to main content

Configuring Velocity

Velocity is designed to be easy to configure and set up. Every Velocity file is stored in velocity.toml, located in the directory where you started the proxy. Velocity uses the TOML file format, as it is easy to understand and avoids pitfalls of YAML and other configuration formats common in the community.

An up-to-date version of the default configuration can be found on GitHub.

Data types

There are a few "special" data types in the Velocity configuration.


Chat messages may be provided in MiniMessage format.

RGB support is available for Minecraft 1.16 and later versions.


An address is a pairing of an IP address or hostname, and a port, separated by a colon (:). For instance, and are valid addresses.

Root section

These settings mostly cover the basic, most essential settings of the proxy.

Setting NameTypeDescription
config-versionStringThis is the current config version used by Velocity. You should not alter this setting.
bindAddressThis tells the proxy to accept connections on a specific IP. By default, Velocity will listen for connections on all IP addresses on the computer on port 25577.
motdChatThis allows you to change the message shown to players when they add your server to their server list. You can use MiniMessage format.
show-max-playersIntegerThis allows you to customize the number of "maximum" players in the player's server list. Note that Velocity doesn't have a maximum number of players it supports.
online-modeBooleanShould we authenticate players with Mojang? By default, this is on.
force-key-authenticationBooleanShould the proxy enforce the new public key security standard? By default, this is on.
player-info-forwarding-modeEnumSee Configuring player information forwarding for more information.
prevent-client-proxy-connectionsBooleanIf client's ISP/AS sent from this proxy is different from the one from Mojang's authentication server, the player is kicked. This disallows some VPN and proxy connections but is a weak form of protection.
forwarding-secret-fileStringThe name of the file in which the forwarding secret is stored. This secret is used to ensure that player info forwarded by Velocity comes from your proxy and not from someone pretending to run Velocity. See the "Player info forwarding" section for more info.
announce-forgeBooleanThis setting determines whether Velocity should present itself as a Forge/FML-compatible server. By default, this is disabled.
kick-existing-playersBooleanAllows restoring the Vanilla behavior of kicking users on the proxy if they try to reconnect (e.g. lost internet connection briefly).
ping-passthroughStringAllows forwarding nothing (the default), the MODS (for Forge), the DESCRIPTION, or everything (ALL) from the try list (or forced host server connection order).
enable-player-address-loggingBooleanIf disabled (default is true), player IP addresses will be replaced by <ip address withheld> in logs.

servers section

Setting NameTypeDescription
A server nameAddressThis makes the proxy aware of a server that it can connect to.
tryArrayThis specifies what servers Velocity should try to connect to upon player login and when a player is kicked from a server.

forced-hosts section

Setting NameTypeDescription
A host nameHostnameThis configures the proxy to create a forced host for the specified hostname. An array of servers to try for the specified hostname is the value.

advanced section

Setting nameTypeDescription
compression-thresholdIntegerThis is the minimum size (in bytes) that a packet must be before the proxy compresses it. Minecraft uses 256 bytes by default.
compression-levelIntegerThis setting indicates what zlib compression level the proxy should use to compress packets. The default value uses the default zlib level.
login-ratelimitIntegerThis setting determines the minimum amount of time (in milliseconds) that must pass before a connection from the same IP address will be accepted by the proxy. A value of 0 disables the rate limit.
connection-timeoutIntegerThis setting determines how long the proxy will wait to connect to a server before timing out.
read-timeoutIntegerThis setting determines how long the proxy will wait to receive data from the server before timing out.
haproxy-protocolBooleanThis setting determines whether or not Velocity should receive HAProxy PROXY messages. If you don't use HAProxy, leave this setting off.
tcp-fast-openBooleanThis setting allows you to enable TCP Fast Open support in Velocity. Your proxy must run on Linux kernel >=4.14 for this setting to apply.
bungee-plugin-message-channelBooleanThis setting allows you to enable or disable support for the BungeeCord plugin messaging channel.
show-ping-requestsBooleanThis setting allows you to log ping requests sent by clients to the proxy.
announce-proxy-commandsBooleanThis setting allows you to enable or disable explicitly sending proxy commands to the client (for Minecraft 1.13+ tab completion).
failover-on-unexpected-server-disconnectBooleanThis setting allows you to determine if the proxy should failover or disconnect the user in the event of an unclean disconnect.
log-command-executionsBooleanDetermines whether or not the proxy should log all commands run by the user.
log-player-connectionsBooleanEnables logging of player connections when connecting to the proxy, switching servers and disconnecting from the proxy.
accepts-transfersBooleanDetermines whether or not the proxy accepts incoming transfers from other servers. If disabled, the proxy will disconnect transferred clients.

query section

Setting nameTypeDescription
enabledBooleanWhether or not Velocity should reply to Minecraft query protocol requests. You can usually leave this false.
portNumberSpecifies which port that Velocity should listen on for GameSpy 4 (Minecraft query protocol) requests.
mapStringSpecifies the map name to be shown to clients.
show-pluginsBooleanWhether or not Velocity plugins are included in the query responses.