What Coolmg Actually Is
Coolmg is a lightweight cross-platform framework built for managing multi-tenant gaming environments. It handles connection pooling, resource isolation, and load distribution across game servers that share the same infrastructure. If you have ever tried to run multiple instances of a multiplayer server on a single machine without things falling apart, this is roughly the category of tool you need. The installation process is straightforward if you follow the official documentation. Clone the repository from the GitHub page, run the setup script, and configure your environment variables. I ran into a problem early on where the default connection pool size was set too low for my workload. The servers would drop under light traffic because the pool exhausted its connections. I solved it by setting COOLMG_POOL_SIZE to 256 in the config file and restarting the service. That fixed the issue completely. The config file lives at /etc/coolmg/config.yml by default. You can override individual settings with environment variables. I usually just edit the YAML directly since it is easier to version control that way.
How It Works Under the Hood
Coolmg uses a proxy architecture. Each game server instance registers with the Coolmg daemon, which then routes incoming connections based on availability and load. It supports both TCP and UDP pass-through, which matters if your game uses UDP for real-time state updates. The routing decisions happen at Layer 4, so there is no application-layer inspection overhead. That is one reason it feels faster than some alternatives I have tried. Another thing most guides skip: Coolmg does not manage the game servers themselves. It only proxies traffic. You still need to start and stop your server binaries. The framework just sits between the players and those binaries. I learned this the hard way after spending an hour wondering why my server was not appearing in the Coolmg dashboard. It was simply not registered. You have to run the registration command for each instance you want tracked.
Common Pitfalls
There are a few things that catch people off guard. The health check interval defaults to 30 seconds. If your server takes longer than that to respond during startup or a memory spike, Coolmg will mark it as down and stop routing traffic to it. I changed mine to 60 seconds with a grace period of 120 seconds for initial startup. That prevents false positives. Another issue is the log rotation. By default Coolmg logs to /var/log/coolmg/. On a busy system those logs grow fast. I switched to a daily rotation policy with a max of 7 files. That keeps disk usage reasonable without losing useful debug info. And one more thing that is not obvious: Coolmg does not support IPv6 out of the box in its default configuration. If your network is IPv6 only, you need to enable the IPv6 passthrough flag in the config. I had a client whose entire deployment was IPv6 and they spent two days before finding that setting. It is documented, but it is easy to miss if you are skimming.
When Coolmg Is Not the Right Tool
If you are running a single server instance, Coolmg adds unnecessary complexity. It is designed for multi-instance scenarios where you need load distribution and health monitoring across several servers. For a single dedicated server, a simple reverse proxy or even port forwarding is enough. If you need application-layer load balancing that inspects HTTP headers or JWT tokens, Coolmg will not help you. It operates at the transport layer. For that use case you would want something like Nginx or Traefik instead. Coolmg is not a replacement for a full-featured web server. There is also a limitation around persistent connections. If your game relies on long-lived WebSocket connections that stay open for hours, Coolmg handles them fine, but the connection tracking tables can fill up under high concurrency. I have seen it happen at around 10,000 simultaneous connections on a standard 8-core machine. Scaling beyond that requires tuning the kernel parameters and increasing the file descriptor limits. That is a whole separate topic.
Where to Download
The official source is the Coolmg repository on GitHub. Pre-built binaries are available for Linux and macOS. Windows support is available through WSL or as a community build. There is no official Windows native binary yet. The project is actively maintained, with releases every few weeks. Check the releases page for the latest version and any breaking changes from previous versions. Most people start with the Docker image if they want a quick test environment. It spins up in about 30 seconds and gives you a functional setup to experiment with before moving to a bare-metal deployment.
Advanced Configuration Tips
Once you get past the basics, there are a few things worth knowing. The failover configuration supports weighted routing, which means you can direct more traffic to healthier servers. I used this when one of my server instances had more RAM and could handle more players. Setting the weight to 3 on that instance and 1 on the others improved player distribution noticeably. Another advanced feature is the rate limiting module. It is not enabled by default. When you turn it on, you can set per-IP connection limits to prevent single clients from consuming all available slots. This is useful if you run into players who open dozens of connections simultaneously. The default rate limiter uses a token bucket algorithm. The configuration is in the rate_limit section of the config file. I recommend starting with 10 connections per second per IP and adjusting from there. Monitoring is built in but basic. The dashboard shows active connections, server status, and throughput. It does not show per-player metrics or detailed latency breakdowns. If you need that level of visibility, you will need to pipe the logs into something like Grafana or integrate with a metrics endpoint. Coolmg exposes Prometheus-compatible metrics on port 9100 by default. That is worth enabling if you plan to scale beyond a few instances.
I also found that the automatic recovery feature can be finicky. When Coolmg detects a dead server, it restarts it after a configurable interval. In my experience, this works well for most crashes but fails when the server enters a loop where it crashes immediately on startup. In those cases the daemon gets stuck in a restart loop and consumes CPU. I disabled auto-restart for problematic instances and handle recovery manually instead. It is a small trade-off for stability.
