Skip to main content
LiquidBounce includes built-in proxy support for connecting to Minecraft servers through proxy servers, useful for bypassing network restrictions or protecting your IP address.

​
Supported Proxy Types

The ProxyManager (features/misc/proxy/ProxyManager.kt:42) supports:
  • SOCKS5 - Full protocol support with authentication
  • HTTP - HTTP proxy protocol with authentication
Only SOCKS5 and HTTP proxies are supported. SOCKS4 is not supported.

​
Proxy Configuration

​
Proxy Data Structure

data class Proxy(
    val host: String,
    val port: Int,
    val credentials: Credentials?,
    val type: Type?,
    var forwardAuthentication: Boolean = false,
    var ipInfo: IpInfoApi.IpData? = null,
    var favorite: Boolean = false
)

​
Creating a Proxy

Proxies support multiple input formats: 
// Basic format
host:port

// With credentials (@ notation)
username:password@host:port

// With credentials (colon notation)
host:port:username:password
username:password:host:port

// With type prefix
http://host:port
socks5://host:port
socks5h://host:port
The parser automatically detects the format (Proxy.kt:78-124).

​
Proxy Validation

Before use, proxies are validated by connecting to a Minecraft ping server: 
ProxyManager.validateProxy(proxy, 
    index = null,  // null = add new, index = replace existing
    checkOnly = false  // true = don't add to list
)
1

Send Query Request

Attempts to connect to the Minecraft Ping Server through the proxy (ProxyManager.kt:75)
2

Validate Connection

Ensures the proxy works for Minecraft protocol, not just HTTP(S)
3

Store or Update

On success, adds the proxy to the list or updates an existing one (ProxyManager.kt:84-95)
4

Fire Event

Triggers ProxyCheckResultEvent with success or error message (ProxyManager.kt:78-99)

​
Using Proxies

​
Setting Active Proxy

ProxyManager.proxy = myProxy
The active proxy is automatically used for all server connections (ProxyManager.kt:46-48).

​
Current Proxy

Get the current active proxy (validates it’s configured): 
val currentProxy = ProxyManager.currentProxy
// Returns null if proxy host is blank or port is invalid
Implementation (ProxyManager.kt:54-55): 
val currentProxy
    get() = proxy.takeIf { proxy -> proxy.host.isNotBlank() && proxy.port > 0 }

​
Network Integration

​
Pipeline Handler

Proxies are automatically injected into the Netty pipeline: 
private val pipelineHandler = handler<PipelineEvent> { event ->
    // Skip local servers
    if (event.local) {
        return@handler
    }
    
    val pipeline = event.channelPipeline
    
    // Add proxy handler if not already present
    if (pipeline.get("proxy") == null) {
        pipeline.addFirst("proxy", currentProxy?.handler() ?: return@handler)
    }
}
Local servers (localhost/LAN) automatically bypass the proxy (ProxyManager.kt:112).

​
Proxy Handler Creation

The handler is created based on proxy type (Proxy.kt:47-58): 
fun handler() = when (type ?: Type.SOCKS5) {
    Type.HTTP -> if (credentials == null) {
        HttpProxyHandler(address)
    } else {
        HttpProxyHandler(address, credentials.username, credentials.password)
    }
    Type.SOCKS5 -> if (credentials == null) {
        Socks5ProxyHandler(address)
    } else {
        Socks5ProxyHandler(address, credentials.username, credentials.password)
    }
}

​
Proxy Management

​
Storing Proxies

Proxies are saved in the config system: 
internal val proxies by list(name, mutableListOf<Proxy>(), valueType = ValueType.PROXY)
Changes are automatically persisted (ProxyManager.kt:47, 91).

​
Connection Tracking

The manager tracks validation connections for proper cleanup: 
internal fun addClientConnection(connection: Connection) = mc.execute {
    clientConnections.add(connection)
}
Connections are ticked and cleaned up automatically (ProxyManager.kt:129-138).

​
Advanced Features

​
Forward Authentication

The forwardAuthentication flag can be used to control whether credentials are forwarded to the destination server.

​
IP Information

Proxies can store associated IP information from IpInfo API: 
var ipInfo: IpInfoApi.IpData? = null
This can include:
  • Geographic location
  • ISP information
  • Connection details

​
Favorites

Mark frequently used proxies as favorites: 
proxy.favorite = true

​
Error Handling

Validation failures trigger events with error messages: 
failure = {
    logger.error("Failed to check proxy", it)
    EventManager.callEvent(
        ProxyCheckResultEvent(proxy, error = it.message ?: "Unknown error")
    )
}

​
Best Practices

Use validateProxy() before adding proxies to ensure they work with Minecraft’s protocol, not just HTTP.
The system automatically skips proxies for local servers. Don’t manually bypass this behavior.
Proxy credentials are stored in the config. Ensure your config files are properly secured.
Listen to ProxyCheckResultEvent to provide user feedback on proxy validation results.

​
Configuration Example

{
  "selectedProxy": {
    "host": "proxy.example.com",
    "port": 1080,
    "credentials": {
      "username": "user",
      "password": "pass"
    },
    "type": "SOCKS5",
    "favorite": true
  },
  "proxies": [
    // List of saved proxies
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us