Use a Docker image

If you already build your server as a Docker image (a packaged copy of your server and everything it needs), you can register it as a build instead of uploading a ZIP.

Register the image

Use your server key:

curl -X POST https://api.simpl.gg/v1/builds/docker-image \
  -H "api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "0.1.0",
    "image_url": "ghcr.io/your-org/game-server:0.1.0",
    "ports": [{ "name": "game", "protocol": "udp" }]
  }'

name is the build’s name, used as its version_tag.
image_url is where the image is. image also works.
ports works as for ZIP builds. See Ports and environment.

Only the fields in the API reference are accepted. Any other field is refused with 400, and the error names it. Simpl copies the image once, when you register it. Moving or deleting the tag afterwards doesn’t change your build.

What the image needs

A linux/amd64 version. An image built only for another platform, such as linux/arm64, fails, and error_message lists the platforms it has.
An ENTRYPOINT or a CMD, so Simpl knows what to run.

Servers run your image’s own ENTRYPOINT and CMD. Your launch arguments are added after them. Servers get the same ports and environment variables and launch argument placeholders as ZIP builds.

Private images

If your image is in a private registry, add a username and password. A read-only token is enough, such as a GitHub token with only the read:packages permission.

{
  "name": "0.1.0",
  "image_url": "ghcr.io/your-org/game-server:0.1.0",
  "registry_username": "your-github-user",
  "registry_password": "ghp_your_read_only_token"
}

Send both or neither. Simpl uses them once, to copy the image, and then deletes them. They are never shown again.

If the copy fails

The build’s status becomes failed, and error_message says why:

Problem	What to do
The registry rejected the username or password	Check them, and that the token can read the image.
The image was not found, or is private	Check the name and tag. For a private image, add a username and password.
The image was not found	Check the name and tag.
The image has no `linux/amd64` version	Build it again with `--platform linux/amd64` and push it.
Could not reach the registry	Check the address in `image_url`, then try again.

Getting Started

Build Your Server

Run Your Server

Players

Unreal SDK

Platform

Use a Docker image

Register the image

What the image needs

Private images

If the copy fails

​Register the image

​What the image needs

​Private images

​If the copy fails

Register the image

What the image needs

Private images

If the copy fails