Skip to content

Run a new game server build

Otomo doesn't contain a game server: it runs yours. This guide explains what your Godot server has to do to work with otomo, then exports it, copies it to your VM, and starts it in place of the old build. It takes 30 to 60 minutes the first time, and about 10 once you're used to it.

Read Parties and matches and Servers and containers first. This guide also uses the terminal a lot; if that's new to you, read Command-line basics too.

You'll need:

  • otomo deployed on your VM (Deploy otomo on a VM);
  • Godot 4.7.2 .NET and your game's server project on your computer;
  • WSL on Windows (Before you begin);
  • a login on the VM (ssh you@play.example.com works from WSL).

The big picture

 Your PC                                     Your VM (Linux)
 ───────                                     ───────────────
 Godot exports      ──── copy (scp) ────▶    deploy/gameserver/build/
 the server project                                 │
 for Linux                                          ▼  docker compose build
                                             a new game server image
                                                    │
                                                    ▼  docker compose up -d
                                             gs-1 and gs-2 restart on it,
                                             and tell the Allocator "I'm here"

What's a dedicated server export? Exporting a Godot project as a dedicated server produces a Linux program with no window, graphics or sound (Godot strips them out), which is exactly what a machine in a data centre needs. It's started headless: no screen at all, just text output. Your server project can be a separate Godot project or the same one as your game, exported with a server preset.

Dedicated server or peer-hosted?

Otomo can place a match in three ways, chosen per matchmaking pool (transport in matchmaking.rules). One deployment can use all three at once.

Dedicated (otomo-udp) Peer-hosted (p2p_host) Room server (photon)
Who runs the match your server build, on your VM one player's game client an external room service
Cost on your VM ~120–190 MB RAM per warm server, all day a few KB per room in the Gameplay Proxy none
Server export and image needed (this guide) not needed not needed
Who players connect to the Gameplay Proxy the Gameplay Proxy (relay) the room service directly
Trust your server is the authority the host is trusted for simulation only the room service
If the authority goes away the reaper ends the match 30 s resume window, then the match ends host_lost (abandoned) the room service's rules
Bandwidth on your VM 1× the match's traffic about 1.5×: the host's traffic crosses your uplink twice none

Choose peer-hosted for co-operative modes where a cheating host only spoils their own group's game and nothing valuable is paid out on the host's word, when RAM or build minutes on your host are scarce, and when your players are on desktop builds that can host. Keep dedicated servers for competitive modes, anything whose result pays out currency or items without the reward-trust rules (design 32), and web builds (a browser cannot host). Peer-hosted needs P2P_ENABLED=true in deploy/.env (it switches on both the Allocator's transport and the proxy's relay mode) and an SDK with host mode; the wire is in the p2p wire contract. The rest of this guide is about dedicated servers.

What your game server must do

Otomo runs a fixed pool of game servers (gs-1 and gs-2), each in its own container. Otomo starts your program, but your code has to talk to the Allocator, the part of otomo that hands servers out to parties. Here's the whole contract.

Read the launch settings

Otomo passes these as environment variables (read them with System.Environment.GetEnvironmentVariable in C#):

Variable Example Meaning
OTOMO_GS_SERVER_ID gs-1 This server's name. Use it in every Allocator call.
OTOMO_GS_PORT 7777 The UDP port to listen on with ENetMultiplayerPeer.CreateServer.
OTOMO_GS_INTERNAL_ADDR gs-1:7777 The address the Gameplay Proxy forwards players to. Send it when registering.
OTOMO_GS_CAPACITY 4 How many players a match may have.
OTOMO_ALLOCATOR_URL http://allocator:8080 Where the Allocator is.
OTOMO_ALLOCATOR_KEY_FILE /run/secrets/service_keys/allocator_gameserver.key A file holding the key to send with every Allocator call.
OTOMO_CONFIG_URL http://config:8081 Where Config's internal listener is, for the configuration bundle below. Empty means "load masters from the export, as before".
OTOMO_CONFIG_KEY_FILE /run/secrets/service_keys/config_gameserver.key A file holding the key that reads the configuration bundle. It can read that one route and nothing else.

When OTOMO_ALLOCATOR_URL is empty (in the editor, or on your PC), run standalone: listen on a port and skip everything below. That's how you test the server locally.

Talk to the Allocator

Every call is an HTTP POST with the header Authorization: Bearer <the contents of the key file> and a JSON body:

When Call Body Answer
Once, at start-up POST {url}/internal/servers/register {"server_id": "gs-1", "internal_addr": "gs-1:7777", "capacity": 4} 204
Every 5 seconds POST {url}/internal/servers/gs-1/heartbeat {"players_connected": 0} 200 {"allocation": null}, or the match it's reserved for: {"allocation": {"allocation_id": "…", "player_ids": ["…"], "leader_id": "…" \| null, "expires_at": "…"}}
When the match is over POST {url}/internal/servers/gs-1/ended {"allocation_id": "…"} 204

Then follow this lifecycle:

Event What your server does
Start Register, then heartbeat every 5 seconds
A heartbeat answers with an allocation Remember its allocation_id and player_ids: that's the match, and those are the players allowed in. leader_id is the party leader (one of player_ids, or null if none was named): make that player the lobby host, and leave the lobby without a host until they have connected
Players connect Report the count in players_connected on every heartbeat
Optional release report Add build, docs_release_id, docs_staged_release_id and, if you have it, config_release (strings; docs_staged_release_id is empty when nothing is staged) to the heartbeat body so staff can see whether this server has pulled the newest release. docs_release_id is the authoritative installed-release indicator; config_release is optional and may be omitted or empty. Omit them all and the heartbeat still works
Everyone has left for about 20 seconds Call ended with the allocation ID, then exit with code 0
A heartbeat answers 404 not_registered Otomo thinks this server died. Exit; it will be restarted

Exiting after a match is deliberate: the container restarts it at once with a fresh world, and it registers as free again. A server that stops heartbeating for 15 seconds is marked dead, and its match ends.

Rollout order. Deploy the Allocator that accepts the release fields before any game server image that sends them. The Allocator decodes the heartbeat strictly and answers 400 invalid_request to a field it does not know. A server that falls back to the old body on a 400 keeps working, but that is a safety net, not the plan.

If your clients join your own room server

Some games keep their own room server — an external Photon server, say — instead of sending players through otomo's UDP proxy. Otomo supports that as a transport: otomo-udp is the proxy (the default, and what everything above describes) and photon is a room server your clients dial themselves. The transport is a field on the server's record, so one deployment can run both kinds of server side by side, and the calls above do not change.

A room-server build registers with its host and port triple instead of an internal address:

Field Value Meaning
transport "photon" The room server is the transport.
endpoint.host "rooms.sg.example.com" The room server's host name, without a port.
endpoint.ports {"master": 5055, "game": 5056, "name": 5058} All three, each between 1 and 65535, each different: master to find or create a room, game for the room's traffic, name for the name service.
endpoint.room "kf-8f21" (optional) The room clients are admitted to, when your deployment names one. Omit it when the room server creates rooms per match.
POST {url}/internal/servers/register
{
  "server_id": "room-sg-1",
  "capacity": 8,
  "transport": "photon",
  "endpoint": {
    "host": "rooms.sg.example.com",
    "ports": { "master": 5055, "game": 5056, "name": 5058 },
    "room": "kf-8f21"
  }
}
  • No internal_addr. Nothing on otomo's side dials your room server, so there is no address to give. It is still required for otomo-udp, unchanged.
  • Mistakes are refused at start-up. A missing or out-of-range port, a host that carries its own port, two roles on one port, and an unknown transport all come back as 400 invalid_request, with every problem in one message and the accepted transports named. You find out when the server starts, not when a player tries to join.
  • Heartbeat and ended are unchanged. A room server is still a place a party was put, so the Allocator still needs to hear that it is alive and that the match is over.
  • The answer says where to connect. POST /internal/allocations (which Session calls) returns a descriptor: for otomo-udp that is {"transport": "otomo-udp", "endpoint": {"address": …, "port": …}, "proxied": true} and the old address/port fields as well; for photon it is {"transport": "photon", "host": …, "ports": {…}, "room": …, "proxied": false} and no address/port, because no otomo process is on the wire. proxied: false is the part a client must act on: it dials the room server itself.

This is also why an HTTP plane behind a tunnel and a game's UDP port dialled directly can be served by one deployment: they are two different transports, not two ports of one.

Each player connects with a join ticket: a short-lived token, signed by the Allocator, naming the server and the player. The Gameplay Proxy already checks it, so a server that skips this step still works. For defence in depth, check it again in SceneMultiplayer.AuthCallback before calling CompleteAuth:

  • the client sends the ticket's text with SendAuth (Join a match, Step 3);
  • the ticket is a JWT signed with Ed25519; the public key is at {OTOMO_ALLOCATOR_URL}/.well-known/jwks.json;
  • accept it only if iss is https://allocator.otomo.internal, aud is otomo:gameserver, it hasn't expired, srv is this server's ID, its player is in the allocation's player_ids, and you haven't already accepted the same jti (each ticket works once).

Full details

services/allocator/README.md and design/14-launch-handoff.md in the repository give the exact fields and failure cases.

Load the server configuration

Your masters — balance values, match rules, feature flags — can live in otomo instead of in the export, so someone on your team can change them without shipping a new build. Config publishes them as a release, and the server half of a release is available as one file: a gzipped tar holding one JSON document per namespace, plus a manifest.json that lists them.

Otomo serves it here:

GET {OTOMO_CONFIG_URL}/internal/config/releases/{release_id}/bundle
GET {OTOMO_CONFIG_URL}/internal/config/channels/{channel}/bundle
Authorization: Bearer <contents of OTOMO_CONFIG_KEY_FILE>

{release_id} is the release you want, and a release id never changes its contents: releases are immutable, so the same id is always the same artefact. The second form is the same artefact addressed by channel (dev, staging or live) instead of by id: it serves whatever release the channel currently serves, resolved at request time from one release — never a mix of two. Use it when you want the server to follow a channel; use the id form when you want a running match to stay on the configuration it was tested with.

At start-up, read OTOMO_CONFIG_URL and OTOMO_CONFIG_KEY_FILE from the environment like the settings above; when OTOMO_CONFIG_URL is empty, keep loading masters from the export, exactly as before.

A successful fetch is 200 with Content-Type: application/gzip and four headers that matter to you:

Header Meaning
ETag Changes whenever the release's content would change. Send it back as If-None-Match on the next fetch; 304 Not Modified means there is nothing new to load.
Digest sha-256=<hex>: the SHA-256 of the file you are holding.
X-Otomo-Release The release id the file belongs to.
X-Otomo-Channel The channel the release was published on.

Inside the tar, manifest.json comes first, then config/<namespace>.json for each namespace. The documents are sorted by name and every timestamp is pinned, so the same release always produces the same bytes — which is why comparing digests tells you whether anything actually changed. manifest.json lists each document's namespace, audience, version, size and its own SHA-256.

Load it in five steps, in this order:

  1. Fetch the bundle.
  2. Verify it: hash the bytes you received and compare with Digest. A mismatch means the download was damaged on the way, so treat it as a failed fetch and keep what you have.
  3. Unpack into a new directory, such as config-<release_id>.new — never over the directory you are currently reading.
  4. Check each document against manifest.json (its own SHA-256 and size), and only then swap directories and reload. Rename the old directory out of the way, rename the new one into place, then reload your tables, so nothing ever reads a half-written directory.
  5. On any failure — a bad digest, a tar you cannot unpack, a document that fails its own hash — delete the new directory and keep the last good bundle. A server that refuses to start because a config fetch failed is worse than one that starts on yesterday's balance values.

A minimal C# version, using .NET 8 (which Godot 4 .NET uses):

using System.Formats.Tar;
using System.IO.Compression;
using System.Net;
using System.Security.Cryptography;

var url = $"{configUrl}/internal/config/releases/{releaseId}/bundle";
using var request = new HttpRequestMessage(HttpMethod.Get, url);
request.Headers.Add("Authorization", $"Bearer {key.Trim()}");
request.Headers.TryAddWithoutValidation("If-None-Match", lastETag);

using var response = await http.SendAsync(request);
if (response.StatusCode == HttpStatusCode.NotModified) return;   // up to date
response.EnsureSuccessStatusCode();

var bytes = await response.Content.ReadAsByteArrayAsync();
var sha = Convert.ToHexString(SHA256.HashData(bytes)).ToLowerInvariant();
if (response.Headers.TryGetValues("Digest", out var digest) &&
    digest.First() != $"sha-256={sha}")
    throw new InvalidDataException("the bundle does not match its digest");

var staging = Path.Combine(root, $"config-{releaseId}.new");
if (Directory.Exists(staging)) Directory.Delete(staging, true);
Directory.CreateDirectory(staging);

using (var gzip = new GZipStream(new MemoryStream(bytes), CompressionMode.Decompress))
    TarFile.ExtractToDirectory(gzip, staging, overwriteFiles: true);

// Verify staging/manifest.json here, then swap:
var live = Path.Combine(root, "config");
var old = Path.Combine(root, "config.old");
if (Directory.Exists(old)) Directory.Delete(old, true);
if (Directory.Exists(live)) Directory.Move(live, old);
Directory.Move(staging, live);
LoadMasters(live);        // your code: read config/*.json into your tables

When to fetch

Fetch at start-up, then every minute or so with the ETag you already hold: a 304 costs almost nothing, and the alternative is a server running stale balance values. Fetch the channel route to follow whatever is published; if you want a match to start on exactly the configuration it was tested with, pin the release id you saw in X-Otomo-Release and fetch that id instead.

What the bundle does not contain

Only server configuration is in it. Values your client needs come from the patch manifest (Content and patching): server-only tuning must never reach a player's machine, so the two halves are published separately. One bundle is capped at 512 MiB; a release past that is refused with an error naming the release, never handed over truncated.

Step 1: Install the Linux export templates (once)

Godot needs export templates (pre-built engine files) to export for each platform. You install them once per Godot version.

  1. Open your server project in Godot.
  2. Editor → Manage Export Templates…
  3. If it says the templates for 4.7.2.stable.mono are missing, press Download and Install. It downloads about 1 GB, so give it a few minutes.

When it's done, the window lists the installed version. Close it.

Step 2: Export the server

First create the export preset, once: Project → Export… → Add… → Linux, name it Linux, and on its Resources tab set Export Mode to Export as dedicated server.

Then export, from the editor or from the command line. Both give the same result.

  1. Project → Export…, and select the preset named Linux.
  2. Press Export Project…, choose an empty folder such as C:\gs-export, name the file gameserver.x86_64, untick Export With Debug, and press Save.

Open Command Prompt (Start menu → cmd) and run these three lines, one at a time:

cd %USERPROFILE%\MyGame\server
mkdir C:\gs-export
C:\godot_4.7\Godot_v4.7.2_console.exe --headless --path . --export-release Linux C:\gs-export\gameserver.x86_64
  • Line 1 moves into your server project's folder. %USERPROFILE% is Windows' name for your home folder, such as C:\Users\Mei. Change the path to where your project is.
  • Line 2 makes the output folder.
  • Line 3 runs Godot without a window (--headless) on this project (--path ., where . means "this folder"), and exports the preset named Linux to the given file. Change C:\godot_4.7\… to wherever your Godot is.

Don't type angle brackets

If you copy a path from documentation that contains a placeholder like <out>, replace the whole placeholder. In cmd, < means "read from a file", and you'll get The system cannot find the file specified.

The file must be named gameserver.x86_64: otomo's container starts it by that name. When the export finishes, C:\gs-export contains:

Item What it is
gameserver.x86_64 The server program, with the game's resources packed inside it
data_gameserver_linuxbsd_x86_64\ The .NET runtime your C# code needs. Always ship it together with the program.

Before sending it to the VM, make sure the program starts on Linux. WSL is Linux, so you can test it right on your PC.

  1. Open WSL.
  2. Go to the export folder. In WSL, your C: drive is at /mnt/c:

    cd /mnt/c/gs-export
    
  3. Mark the program as runnable. Linux only runs files with the execute permission, and files copied from Windows don't have it:

    chmod +x gameserver.x86_64
    
  4. Run it for 10 seconds, standalone, on a test port:

    OTOMO_GS_PORT=7791 timeout 10 ./gameserver.x86_64 --headless
    

    ./ means "the program in this folder". You should see Godot's start-up lines, then whatever your server prints when it starts listening. If it exits at once with an error, fix that before going further.

Step 4: Copy it to your VM

Still in WSL, in /mnt/c/gs-export:

  1. Pack both items into one file, so there's a single thing to copy:

    tar czf /tmp/gs-build.tgz gameserver.x86_64 data_gameserver_linuxbsd_x86_64
    

    Tip: type data_ and press Tab to complete the long folder name.

  2. Copy it to the VM's /tmp/ folder:

    scp /tmp/gs-build.tgz you@play.example.com:/tmp/
    
  3. Log in to the VM:

    ssh you@play.example.com
    

    From now until Step 7, every command runs on the VM.

  4. Replace the old build with the new one:

    cd ~/otomo/deploy
    rm -rf gameserver/build
    mkdir -p gameserver/build
    tar xzf /tmp/gs-build.tgz -C gameserver/build
    
    • cd ~/otomo/deploy goes to otomo's deployment folder, where all the Docker commands are run from.
    • rm -rf gameserver/build deletes the previous build. Double-check you typed gameserver/build.
    • mkdir -p makes the folder again, empty.
    • tar xzf … -C gameserver/build unpacks your upload into it.

    Check the result with ls gameserver/build. It should list gameserver.x86_64 and data_gameserver_linuxbsd_x86_64.

Step 5: Build the image and restart the game servers

If this is the first build, add gameservers to COMPOSE_PROFILES in deploy/.env (COMPOSE_PROFILES=edge,gameservers).

  1. Build a new Docker image from the new files:

    docker compose build gs-1
    

    Both game servers use the same image, so building gs-1 is enough.

  2. Restart both game servers on the new image:

    docker compose up -d gs-1 gs-2
    

    up starts the listed containers, replacing any whose image changed. -d returns you to the prompt instead of showing their output.

This ends any match in progress

Restarting a game server ends its current match, and the players in it are returned to their lobby. Do it when nobody's playing, or warn your testers first.

  1. Watch gs-1 start:

    docker compose logs -f gs-1
    

    -f means "follow": keep showing new lines as they arrive. You should see your server start and register. Press Ctrl+C to stop watching (the server keeps running).

Step 6: Check both servers are ready

Ask the Allocator's database which game servers it knows about:

docker compose exec postgres psql -U otomo allocator -c 'select server_id, state, players_connected, last_heartbeat from game_server order by 1'

This runs psql (a program that queries the Postgres database) inside the database's container. You should see:

 server_id | state | players_connected |        last_heartbeat
-----------+-------+-------------------+-------------------------------
 gs-1      | free  |                 0 | 2026-09-30 10:15:02.123+00
 gs-2      | free  |                 0 | 2026-09-30 10:15:03.456+00

Both free, and last_heartbeat within the last few seconds. Type exit to leave the VM.

Step 7: Join a match

Follow Join a match and press Join in your game.

To watch the lifecycle while you play, log in to the VM again and repeat the query from Step 6 every few seconds. You'll see gs-1 go from free to reserved, then busy with 1 player. After everyone quits, it reports the match as ended, restarts, and is free again.

Keeping old builds to go back to

To be able to switch back to a previous build quickly, give each image a tag named after your server project's commit (the short code from git log, such as b97b748):

OTOMO_GAMESERVER_TAG=b97b748 docker compose build gs-1

Then open deploy/.env in a text editor (nano .env; save with Ctrl+X, then Y), set OTOMO_GAMESERVER_TAG=b97b748, and run docker compose up -d gs-1 gs-2. To go back, set the old tag and run the same up -d command. The old image is still stored, so there's nothing to rebuild.

Keep the server's content in step with the clients

Players' games get content packs and settings from Patch. A game server has two choices:

  • Load the release's configuration with the bundle described in Load the server configuration above. The server then follows the same gameplay data the release carries, and a 304 on a fetch tells it nothing has changed since the last one.
  • Keep the masters in the export. Then the server only has what was in that build: if you publish a release that changes gameplay data the server also uses, export and restart the server too, or the two will disagree.

Either way, content packs — textures, scenes, audio — stay a client concern: they are in the patch manifest, not in the bundle.

If something goes wrong

You see What it means What to do
Cannot stat: No such file or directory from tar A typo in a file or folder name Use Tab completion; check with ls
Permission denied (publickey) from ssh or scp The VM doesn't have your SSH key Add your public key to the VM (Command-line basics)
Host key verification failed You ran ssh from Windows instead of WSL Run it from WSL
exec … gameserver.x86_64: no such file or directory in the logs The export isn't named gameserver.x86_64, or isn't in gameserver/build/ Rename it and repeat Step 4
The log shows only Godot's version line and nothing else Godot buffers printed output when it isn't a terminal Enable Application › Run › Flush stdout on Print in the server project and re-export
Your server can't read the key file The key files have the wrong owner sudo chown -R 65532:65532 secrets/service_keys, then Step 5 again
Register answers 401 Your server isn't sending the key, or sends it wrongly Check the Authorization: Bearer … header carries the key file's contents, without a trailing newline
The bundle fetch answers 401 Your server isn't sending OTOMO_CONFIG_KEY_FILE, or the file's contents were pasted with a newline Send the header with the file's contents, trimmed of whitespace
The bundle fetch answers 413 The release is larger than the bundle ceiling (512 MiB by default) Publish a smaller release, or raise the limit on the otomo side
The bundle fetch answers 304 Nothing changed since the digest your server already holds Keep running what you have; there is no body to read
A server stays out of the Step 6 list It crashed on start-up or never registered docker compose logs gs-1 and read the last lines
Join says no_capacity Both servers are busy, or neither registered Step 6

More in Troubleshooting.