How to set up a Metin2 server with QuantumCore X (open source C# emulator, Docker guide)

[admin]

Can you run a Metin2 server with QuantumCore X? Yes, and it is honestly the easiest Metin2 server setup I have done in years: you grab the open source C# emulator from GitHub, dump two proto files from a TMP4 client, and either run a single executable or bring the whole stack up with Docker Compose. The catch is that the project is still in alpha, so read the limitations section before you plan your grand opening.

I have set up more classic Metin2 server files than I care to admit, most of them leaked, half-broken and full of FreeBSD pain. So when I tried QuantumCore X (QCX) I wanted to write down what actually works right now, mid 2026, and what does not.

What QuantumCore X actually is

QCX is an open source implementation of the Metin2 server, written from scratch in modern C# on .NET. It is a fork of the original QuantumCore C# project, continued by MeikelLP with the stated goal of making the codebase as maintainable and modern as possible while filling in the missing features over time. The code is under the Mozilla Public License 2.0, and the repo is genuinely active: over 1,100 commits and contributions from a bunch of community developers, with CI running on every change.

Why should you care when the classic server files exist? Because with QCX you get readable, debuggable C# instead of a decades-old C++ blob, you get a real dependency setup (MariaDB plus Redis) instead of mystery configs, and you can run everything on Linux, Windows or in containers without touching FreeBSD once.

What you need before you start

• A TMP4 compatible client. The docs literally say to just google "TMP4 Client". QCX targets the standard 40k client, so no custom client work is needed for testing.
• For the quick test route: a QCX build, either from GitHub Releases (v0.1 and up), the nightly pipeline, or built yourself with the .NET SDK (SDK 9 for current main).
• For the Docker route: Docker with Compose on any Linux box or Windows machine.
• Windows somewhere, at least for running the client and dumping the proto files. The server itself runs fine on Linux.

Hardware is a non-issue for testing. This is a lean .NET app plus MariaDB and Redis; any small VPS with 2 GB RAM will run an empty test server without complaint.

Step by step: the quick single-executable setup

This is the route from the official getting started guide, and the docs are upfront that it is only meant for testing.

• 1. Get your TMP4 client and, inside the client folder, run Eternexus\--dump_proto--\dump_proto.exe. This spits out the item_proto and mob_proto files the server needs.
• 2. Download a QCX release and unpack it so you have QuantumCore.Single.exe with appsettings.json next to it.
• 3. Create a data folder next to the executable and drop item_proto and mob_proto in there.
• 4. Start the server with ./QuantumCore.Single.exe. On first start it creates a default admin account for you: username admin, password admin. Change that the second you go beyond localhost.
• 5. Point your client at the server by editing serverinfo.py: in single mode the game port is 13001, auth is 11002 and the guild mark server is 13000, all on localhost.
• 6. Log in with admin/admin and you are on your own QCX server.

If you would rather build from source: clone the repo, run dotnet build in the src directory, then dotnet run --project src/Executables/Single. Same data folder rules apply.

Step by step: the Docker setup

For anything that should survive longer than an afternoon, use the full setup. The repo ships a ready docker-compose.yml sample with four services:

• auth: the login server from ghcr.io/meikellp/quantum-core-x/auth, exposed on port 11000, with its own auth.appsettings.json mounted read-only.
• game: the game server from ghcr.io/meikellp/quantum-core-x/game on port 13000, with game.appsettings.json and your data folder (the proto files again) mounted in.
• cache: a plain redis:latest container that QCX uses for live game state.
• db-mysql: mariadb:12.3 with a metin2 database and user preconfigured through environment variables, data persisted in a named volume.

Both server containers wait for healthy database and Redis containers before starting, so the boot order sorts itself out. The workflow is simply: copy the sample folder, drop your dumped proto files into data, adjust the passwords in the compose file and the two appsettings.json files, then docker compose up -d. Prebuilt images come straight from the GitHub Container Registry, so there is nothing to compile. Note that the ports differ from single mode here (auth 11000, game 13000), so set serverinfo.py accordingly.

Current limitations, and they matter

This is the part every "OMG new server files" thread skips. The first tagged release, 0.1.0 "The Baseline" from May, is explicitly labelled an initial alpha with the most basic features and many missing. What you get today: login, character creation, empires, movement, spawns via spawn groups and points, basic combat and items, shops, a permission group system and a solid set of admin commands. What you do not get yet:

• No quest system. Quests are the 0.2 milestone on GitHub and at the time of writing none of its issues are closed. For a game where half the content lives in quest scripts, that is the single biggest blocker.
• Plenty of smaller systems are incomplete or stubbed; the project homepage itself still says work in progress.
• No backward compatibility with the old QuantumCore, and things like the config format already changed once (TOML to JSON), so expect breaking changes between versions.

My honest verdict: QCX is today the most pleasant way to study and hack on Metin2 server tech, and a great base if you want to contribute C# code. It is not yet something you launch a public live server on. Watch the repo, join their Discord, and revisit once quests land.

Frequently asked questions

Is QuantumCore X free and legal to use?
The server code is open source under MPL 2.0, so yes. Keep in mind the docs themselves note that Metin2 and all its art and lore are copyrighted by Webzen, so the usual private server caveats apply to client and assets.

Which client version does it need?
A TMP4 compatible 40k client. You also need it to dump item_proto and mob_proto with the bundled dump_proto.exe, since the server does not ship game data.

Can I replace my classic server files with QCX right now?
Not if you want a playable game. With no quest system and many features still missing in the 0.1 alpha, it is for testing, learning and development, not production.

Does it run on Linux?
Yes, natively via .NET or through the official Docker images. Only the client tooling (dump_proto, the game client itself) needs Windows.

That is everything I verified hands-on and against the official docs. If you have tried QuantumCore X yourself, hit a snag with the Docker setup, or know the current state of the quest milestone better than I do, reply below. I will keep this thread updated as new releases drop, and I am happy to help debug your setup if you post your logs.