Back to the cards

otomo

Backend: self-hosted, for Godot games

My part
Creator and lead developer
Team
Small team
When
Sep 2026 to now
Games on it
Elemaniacs
Made with
Go, PostgreSQL, Valkey, Docker Compose, nginx, Prometheus, Loki, GitHub Actions, Jenkins, Godot C# SDK

More or less 70% done

The otomo logo in blue, with the line "Open-source, vendor-neutral live-service orchestration".

What it is

otomo is a self-hosted, vendor-neutral backend for Godot live-service games. Your game server stays the authority for gameplay, and otomo runs everything around it: content updates, sign-in, friends and parties, matchmaking and game servers, the economy, and the live-ops tools that staff use to run the game.

I created otomo and I lead its development. It isn’t a solo project though, I wrote most of it and my teammates built parts of it, including the first gateway, most of the Session routes and the matchmaker’s queue.

The project isn’t finished, but I’m more or less 70% done with it, and this post-mortem covers the part that exists.

The architecture

There are two sides to otomo. Players come in from the public internet, while staff can only reach the admin side through an SSH tunnel.

flowchart LR
  client["Godot client"]
  client -- "HTTPS" --> edge["edge<br/>nginx, TLS"]
  edge --> gateway
  gateway --> services["auth, patch, session,<br/>matchmaker, economy"]
  services --> allocator
  client -- "UDP, with a ticket" --> proxy["Gameplay Proxy"]
  proxy -- "only once the ticket checks out" --> gs["game servers<br/>(private)"]
  gs -- "register, heartbeat" --> allocator

This is the staff side, which is not reachable from the internet:

flowchart LR
  staff["staff browser<br/>(SSH tunnel)"] --> gwdev["gateway_dev"]
  gwdev --> adminauth["admin-auth"]
  gwdev --> config
  gwdev --> dashboard
  config -. "read-only" .-> patch["patch<br/>(player side)"]
  dashboard --> obs["Prometheus + Loki"]

Each service has its own Postgres database and its own database role. Valkey holds the data that can afford to be lost, like presence and the matchmaking queue.

Service What it does
gateway The player-facing gateway: token checks, rate limits, routing
gateway_dev The staff gateway, loopback only
auth Player accounts, device login, refresh tokens
admin_auth Staff accounts, roles, TOTP, invites
config Authoring: drafts, versions, releases, channels
patch Read-only delivery of manifests and files to players
session Profiles, presence, friends, parties, loadouts
matchmaker Queues and match formation
allocator The pool of game servers, and join tickets
gameplay_proxy The single public UDP port, and a relay for peer-hosted matches
economy The ledger, wallets, items, shop, entitlements
chat Channels and messages
ops Maintenance mode and the update gate
dashboard Metrics, logs and a merged audit trail
cli The admin side from a terminal

Key decisions

Two gateways instead of one

My first plan was a single gateway image with a flag to choose between player routes and admin routes. The problem is that with one image, the gateway that faces the internet contains the admin routes, and it’s one wrong environment variable away from serving them.

Whether admin routes are reachable must not be a runtime decision.

So the gateway was split into two binaries, and the public one has no admin route table to load at all. It costs some duplicated code, and a CI script keeps the shared packages identical.

Players never connect to a game server directly

The Gameplay Proxy owns the only public UDP port, and a player needs a ticket to get past it.

sequenceDiagram
  participant C as Client
  participant M as Matchmaker
  participant A as Allocator
  participant P as Gameplay Proxy
  participant G as Game server
  C->>M: queue with my party
  M->>A: reserve a server for this match
  A-->>M: join ticket, signed, valid for 60 s
  M-->>C: your match and your ticket
  C->>P: first datagram carries the ticket
  Note over P: signature, expiry, known server, never used before
  P-->>C: accepted
  P->>G: forward this one address

The game servers have no public address, so a client without a ticket has nothing to connect to.

Login that assumes tokens get stolen

A player signs in with a device ID, and Auth only stores a keyed hash of it. Access tokens last 15 minutes, and refresh tokens are single-use.

If a refresh token that was already used is presented again, it’s treated as theft and every token in that family is revoked. The one exception is a token that was used in the last 30 seconds, which is refused without revoking anything, since a client on a bad connection can send the same request twice.

We considered making Auth a full OpenID provider and rejected it, as our client is a game SDK holding a device secret and not a browser.

A ledger that can be audited

The economy is a double-entry ledger that can only be appended to, and this is enforced by a database trigger.

  • Every route that moves money takes an idempotency key, so a retried request returns the stored result and the player isn’t paid twice.
  • The game never names an amount. It reports that a player finished a mission, and the rules decide what that pays.
  • A reconciler compares the cached balances against the sum of the entries and reports any difference, but it doesn’t repair anything, since a ledger that quietly fixes itself can’t be trusted.

Authoring and delivery are separate services

Config is where staff write, and Patch is where players read. Patch reads Config’s database through a read-only role, so the public side can’t change the game’s content even if it’s compromised.

A release is immutable once it’s made, and each channel points at one release.

flowchart LR
  r41["release 41"] --- r42["release 42"] --- r43["release 43"]
  dev(["dev"]) --> r43
  staging(["staging"]) --> r42
  live(["live"]) --> r41

Rolling back points a channel at an earlier release, and promoting copies a release to the next channel. Neither of them edits a release.

The platform may not know a game’s words

While porting a game onto otomo, that game’s vocabulary kept ending up inside the platform, and each time it made otomo more specific to that one game. This is the rule we settled on:

A platform service may not know a game’s word.

If a service needs to know what one game’s crate or badge is, the abstraction is one level too low. This is now enforced by a CI check.

otomo owns placement, not the wire

The join ticket started as one thing and was later split into two: a placement claim that says who goes where, and a transport descriptor that says how to connect. That split is what allows the same matchmaker to support dedicated Godot servers, a Photon transport, and peer-hosted matches.

What went wrong

  • The first real release failed, and then failed its own rollback. The release script checked health as soon as the containers were up, before the services had settled, so it judged the release as broken, rolled back, and then judged the rollback as broken for the same reason. The gate now waits for the services to settle.
  • The CI host’s disk filled up to 100%. Build caches, old workspaces and leftover images kept growing with nothing to clean them up, so I added cleanup jobs.
  • The documentation fell behind the code. The README still lists the matchmaker as future work. Our rule now is that when a document and the code disagree, the code and its tests win.
  • Peer hosting wasn’t planned for. Every dedicated Godot server costs 120 to 190 MB of memory and our hosts are small. A co-op game doesn’t need a neutral server to simulate it, it needs otomo to keep identity, placement and the economy honest, so the proxy gained a relay mode.

What’s left

  • Peer-hosted matches can’t pay out rewards yet, and party launches aren’t peer-hosted.
  • Sign-in is device-only for now, with Steam and Google sign-in planned.
  • The economy can’t reverse an entry.
  • There is a ceiling on how much currency a game can pay out, but not on items.
  • A leaked device ID can’t be revoked.
  • Alerts only show up in the dashboard, and nothing pages me.

What runs on it

Elemaniacs is our co-op Godot game, and almost everything outside of the level itself is handled by otomo:

  • The client patches itself, signs in and loads the player’s profile, and old builds are forced to update.
  • Balance numbers, missions and difficulty are config documents, so our designers can tune the game without a new build.
  • The base client is only the menu, and the levels arrive as content packs.
  • Friends, parties, presence and the lobby.
  • Parties queue together, dedicated servers verify join tickets, and peer-hosted matches go through the relay.
  • Spellcrafting and mission rewards go through the ledger.

The second game is the community game server that I run.

How it evolved

  1. 10 to 16 Sep 2026

    Project setup

    I set up nine stub services in one Go workspace, with a Jenkins pipeline for each of them, before any of the services did anything.

  2. 18 to 23 Sep

    Skeletons

    The foundations for the gateway, Auth, Config and Session went in, along with the first GitHub Actions workflow and the Docker Compose base. The gateway was also split into two binaries here.

  3. 26 to 27 Sep

    The staff side

    152 commits over two days, covering staff accounts with TOTP, config authoring, Patch delivery, the dashboard and the admin site.

  4. 28 Sep to 3 Oct

    The player side

    The Allocator and its join tickets, the Gameplay Proxy, the TLS edge and the foundation of the Godot SDK. This closed our first milestone.

  5. 20 to 22 Oct

    Planning the second milestone

    After a two-week gap, we wrote the design documents for the matchmaker, sign-in, transports and the economy before writing any of the code.

  6. 25 to 29 Oct

    Economy and matchmaking

    The Economy ledger was built and a real matchmaker replaced the stub. Maintenance mode, the update gate and backups were added in the same week.

  7. 2 to 5 Nov

    Integration

    Match formation and placement, entitlements and chat. The rule that the platform may not know a game's words also became a CI check.

  8. 6 to 8 Nov

    Hardening and peer hosting

    Gated releases with automatic rollback, encrypted nightly backups, CI disk cleanup, a relay mode for peer-hosted matches, and a CLI.