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 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 legacy color code format or in JSON format.

RGB support (using the &#rrggbb format) is available and JSON messages are deserialized for Minecraft 1.16.


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 legacy Minecraft color codes or JSON chat.
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.
player-info-forwarding-modeEnumSee Configuring player information forwarding for more information.
forwarding-secretStringThis setting is used as a secret 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).

server 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.
proxy-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.

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.

metrics section

Setting nameTypeDescription
enabledBooleanWhether or not Velocity should send metrics to bStats.
idUUIDA randomly generated UUID that uniquely identifies your Velocity server. Do not alter this setting.
log-failureBooleanWhether or not Velocity should log whenever it fails to connect to bStats.
Copyright © 2018-2020 Velocity Contributors. This wouldn't be possible without our generous sponsors.