Skip to main content

Godot Onboarding Guide


Your game will need to be built to run with a dedicated Linux server. Your server will be deployed and hosted on Hathora Cloud.

1. Preparing your server build

Your server will need to be able to be built as a dedicated Linux server build. For more info, check out Godot's guide.

2. Generating a Dockerfile

By providing a Dockerfile with your server build, we will be able to scale your server across the globe.

Sample Godot Dockerfile:

FROM centos:centos8

RUN cd /etc/yum.repos.d/
RUN sed -i 's/mirrorlist/#mirrorlist/g' /etc/yum.repos.d/CentOS-*
RUN sed -i 's|#baseurl=|baseurl=|g' /etc/yum.repos.d/CentOS-*

RUN yum install -y wget unzip libXcursor openssl openssl-libs libXinerama libXrandr-devel libXi alsa-lib pulseaudio-libs mesa-libGL

# TODO: replace with your Godot version

# Install Godot Server
&& unzip Godot_v${GODOT_VERSION} \
&& mv Godot_v${GODOT_VERSION}-stable_linux.x86_64 /usr/local/bin/godot \
&& chmod +x /usr/local/bin/godot

# Add these dependencies if you're enabling TLS
RUN dnf -y update && \
dnf -y install ca-certificates && \

COPY your_game_server.pck .

CMD /usr/local/bin/godot --headless --main-pack ./your_game_server.pck

3. Deploy server to Hathora Cloud

If this is your first time deploying on Hathora Cloud, we recommend starting with our Deploying on Hathora Cloud guide.

There are 2 ways to deploy your server on Hathora Cloud:

  1. With command line or CI/CD pipeline
  2. Drag and drop upload via Hathora Console
hathora deploy \
--build-tag $BUILD_TAG \
--rooms-per-process $ROOMS_PER_PROCESS \
--container-port $CONTAINER_PORT \
--transport-type $TRANSPORT_TYPE \
--requested-memory-mb $MEMORY_MB \
--requested-cpu $CPU \
--env ENV1=$ENV1_VALUE \
--env ENV2=$ENV2_VALUE \
--idle-timeout-enabled $BOOLEAN\
--app-id $APP_ID \

Zero-downtime deployments: New deployments will not impact any existing games, your newly deployed version will only be used for subsequent games created after.

4. Creating rooms/processes

There are 2 ways to create rooms on Hathora Cloud:

  1. Via API call
  2. Directly with Hathora Console (great for debugging)

A simple API call: RoomApi.CreateRoom(appId).


To learn more about room creation and lifecycle, check out our Room Lifecycle docs

5. Connecting to a room

Once you have created a room, it will take Hathora Cloud a few seconds to spin up your server instance and expose a port for your client to connect to.

We recommend polling RoomApi.GetConnectionInfo(appId, roomId) until status is "active" and ExposedPort is not null.


We will automatically terminate a process if there are no active connections for 5 minutes (i.e. the process is in an idle state for 5 minutes).


With our Hathora Console, you can get connection info (host:port) directly, which is useful for testing and debugging.

6. Lobby Service and integration with matchmakers

Check our Lobby Service for a lightweight way to build a lobby system for your game.

Join our developer community!