Nakama: a game backend you run yourself, with server-side Lua, TypeScript or Go

The gap Nakama fills: a game backend you host

Most small studios reach the point where the client needs an account system, a friends list, a leaderboard and a socket that survives a dropped connection. Building those four things from scratch is weeks of work that has nothing to do with the game. Nakama packages them as one server. The README lists users, storage, social graph, chat, multiplayer, leaderboards, tournaments, parties, purchase validation, in-app notifications, a matchmaker, a dashboard and metrics. The target reader is a game developer or backend engineer who is comfortable running a database and a container, and who wants the social and matchmaking layer to be someone else's problem. The repository is not archived and the last push was on 2026-09-18, with v3.41.0 released the same day, so the project is being changed rather than frozen. The licence is Apache-2.0.

How the server is put together

Nakama is a Go program. The top-level entries show the split: server/ holds the core, console/ the admin dashboard, migrate/ the schema migration tool, apigrpc/ the gRPC and HTTP API definitions, and iap/ purchase validation. The database is not embedded. The README states plainly that Nakama requires CockroachDB or another Postgres wire-compatible server, and go.mod pulls in github.com/jackc/pgx/v5, the Postgres driver, which matches that statement. The docker-compose.yml in the repository runs two services side by side: cockroachdb on 26257 with its admin UI on 8080, and nakama, which first runs a migration and then starts the server. The Nakama container exposes 7349, 7350, 7351 and 9100, and the Prometheus service scrapes 9100. That port layout is the clearest signal of the design: one process serves several protocols, and the metrics endpoint is separate from the client-facing ports. Custom logic is not compiled into the binary by default. The README describes runtime code in Lua, TypeScript/JavaScript or native Go, and the compose file mounts the project directory into the container at /nakama/data, which is how modules reach the running server.

Running Nakama locally with Docker

The README calls Docker the fastest way to run the server and the database together, and points to a docker-compose file placed in a project folder. The repository ships docker-compose.yml, which is the concrete example to copy. The CockroachDB service starts a single node with an insecure store, and the Nakama service waits for its health check before starting. The Nakama entrypoint runs the migration first, then execs the server with a name, a database address, DEBUG logging and a session token expiry of 7200 seconds. The migration step matters: without it the server has no schema and will not serve requests. Note that the image tag in the repository file is 3.37.0, older than the v3.41.0 release, so if you copy the file you should decide deliberately which tag you want rather than assuming the compose file tracks the latest release.

Starting it and checking it is alive

With the compose file in place, the README gives one command to download the images and run the servers. The first run pulls CockroachDB and Nakama, so it takes longer than subsequent starts. After that, the nakama service defines a health check that runs the binary's own healthcheck subcommand, and the cockroachdb service polls its HTTP health endpoint. If you want to confirm the server came up without reading container logs, that healthcheck is the mechanism the project itself uses.

Where the runtime code decides the fit

The feature list is the easy part. The harder question is what happens when your game rule does not match a built-in. Nakama answers with runtime code: Lua, TypeScript/JavaScript or native Go, loaded into the server. That is a real architectural commitment. Your matchmaking logic, your reward calculation and your anti-cheat checks live inside the same process as the socket handling, and a mistake in a module can affect the whole server rather than one client. The alternative is to keep game rules in a separate service and use Nakama only for identity, storage and transport, which is possible but means you write the glue. The README does not document a rollback path for a bad module deploy, and it does not describe how modules are versioned or hot-reloaded. That is the kind of thing to test on a staging instance before it matters in production.

The database is the operational cost

Nakama does not ship its own storage engine, so adopting it means adopting CockroachDB or a Postgres wire-compatible server as well. The repository's compose file uses cockroachdb/cockroach:latest-v24.1 in single-node insecure mode, which is fine for a laptop and not fine for anything else. The README points to deployment notes for production recommendations, and the binary path in the same section tells you to download the server from the releases page and the database separately. So the real footprint of a Nakama deployment is two moving parts, not one, plus whatever you use for monitoring. If your team has no one who wants to own a distributed SQL database, that is a reason to look elsewhere before you look at the feature list.

Nakama compared with Tomodachi

Tomodachi is the closest thing in the search data to a head-to-head comparison, and the difference is the shape of the system rather than the feature count. Nakama is a single server binary backed by a separate SQL database, with a gRPC and HTTP API defined in apigrpc/ and generated clients for Unity, Unreal, Godot, JavaScript and others. Tomodachi takes the opposite route: a Go library you embed in your own application, so you own the process, the deployment and the upgrade cadence, and you get the primitives as packages rather than as a running service. If you want an operations boundary between your game logic and the backend, Nakama gives you one. If you want the backend to be part of your binary and you are already writing Go, the library model removes a network hop and a deployment target. Neither is strictly better; they put the complexity in different places.

Licence, upgrades and what to verify

The repository is Apache-2.0, which permits commercial use and modification, but this is not legal advice and the terms that matter to you are in the LICENSE file. On upgrades, the release cadence visible in the release list is roughly every two months through 2026: v3.39.0 on 2026-05-20, v3.40.0 on 2026-07-13, v3.41.0 on 2026-09-18. The migrate subcommand is how schema changes are applied, and the compose entrypoint runs it on every start, which is convenient locally and something to control explicitly in production. The compose file's pinned 3.37.0 image against a 3.41.0 release is the concrete reminder to check the tag yourself. Before adopting, verify that your database choice satisfies the wire-compatibility requirement, that the ports your clients need are reachable, and that the runtime language you plan to use is one your team can debug inside a running server.

Editorial conclusion

Adopt Nakama if you want a self-hosted backend where accounts, storage, chat, leaderboards and realtime matches are already implemented, and you are willing to write your game rules as Lua, TypeScript/JavaScript or Go modules loaded at runtime. Do not adopt it if you want a fully managed service with no database to operate, or if your game logic is small enough that a thin socket server plus your own database would be less to maintain. Before committing, verify three things in your own environment: that your target database is wire-compatible enough for the migrate step, which ports your clients need (7349, 7350, 7351), and whether the runtime language you want is the one your team will actually maintain.

Frequently asked questions

Official sources

1. heroiclabs/nakama on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases