# What a connection config file must contain

> A host needs two things from you: a deployment manifest that says how to start and check your server (engine, transport, ports, command, probes, shutdown), and players need a connection configuration (address, port, protocol, TLS and version). This guide lists every field and why it exists.

*NetCraftGames (NCG) by Charging Bull Software. Last updated: 2026-10-03. Canonical page: https://netcraftgames.com/guides/connection-config-file-contents/*

## The short answer

A deployment manifest is for the host: it names the engine and transport, the exact start command, each port and protocol, how to check health and join, where saves live and how to stop. A connection configuration is for your players' clients: the address, port, protocol, whether TLS is used, and the build version they must match. NetCraftGames reads your submission to produce both, and you review what it proposes.

> **Where this comes from**
>
> The manifest shape and the player connection format below are the ones built into NetCraftGames today. Values that only exist after publishing, such as the final server address, are shown as clearly marked placeholders until then.


## The deployment manifest, field by field

| Field | Required for | What it means |
| --- | --- | --- |
| `engine` | all | Which lane: for example `unity-ngo`, `unity-mirror`, `unreal-replication`, `godot-enet`, `godot-websocket`, `browser-wss`, or `custom-native` (a custom raw TCP or UDP server, see below) |
| `transport` | all | `udp`, `tcp`, `websocket`, `wss` or `webrtc`; must be one the engine can use |
| `platforms` | all | Intended client platforms. Declaring one does not mean it was tested |
| `mode` | all | `dedicated` (we run your server) or `relayed` (WebRTC signaling only) |
| `networkingImplemented` | all | You confirm the game already has working multiplayer networking |
| `os`, `arch` | dedicated | `linux` and `x64` only |
| `command` | dedicated | The start command. `command[0]` must be a literal path under `/game/` |
| `ports` | dedicated | Each `{ port, protocol }` pair the process opens |
| `profile` | all | `standard` (2 vCPU, 4 GiB) or `large` (4 vCPU, 8 GiB, counts double) |
| `savePath` | optional | A literal path under `/game/` to checkpoint on shutdown |
| `health` | dedicated | How to check the process is alive: TCP, HTTP with a path, or UDP with request and expected reply |
| `joinProbe` | recommended; required for `custom-native` | A game-level check with a known expected reply: an `http` path, a `udp` request, or a read-only `tcp` banner where your server speaks first |
| `playerProbe` | optional | A loopback HTTP endpoint returning bounded JSON such as `{ "players": 2 }`, for idle shutdown |
| `shutdown` | optional | Signal `SIGTERM` and `graceSeconds` before a forced stop |
| `artifact` | dedicated | The uploaded archive's id and its lowercase SHA-256 digest |
| `idleSupported` | optional | `true` if the server reports players and tolerates idle shutdown |

### A real example

This is the Unity NGO template from the NetCraftGames integration docs. Replace the digest with the SHA-256 of your own archive.

```json
{
  "engine": "unity-ngo", "transport": "udp", "platforms": ["windows", "android", "ios"],
  "mode": "dedicated", "networkingImplemented": true, "os": "linux", "arch": "x64",
  "command": ["/game/UnityServer.x86_64", "-batchmode", "-nographics"],
  "ports": [{ "port": 7777, "protocol": "udp" }], "profile": "standard",
  "savePath": "/game/saves",
  "health": { "type": "udp", "port": 7777, "request": "health", "expected": "healthy" },
  "playerProbe": { "type": "http", "port": 9090, "path": "/players" },
  "joinProbe": { "type": "udp", "port": 7777, "request": "join-status", "expected": "joinable" },
  "shutdown": { "signal": "SIGTERM", "graceSeconds": 30 }, "idleSupported": true,
  "artifact": { "id": "<archive id>", "sha256": "<64 lowercase hex characters>" }
}
```

## Custom native TCP/UDP (direct): your own protocol

If your server speaks its own raw TCP or UDP protocol, with no Mirror, Netcode, Unreal, Godot or WebSocket library behind it, declare `engine` as `custom-native` and `transport` as `tcp` or `udp`. This lane is supported, and it is deliberately limited:

- **Configuration and deployment only.** We start your Linux x64 build on an isolated machine and check the checks you declare. Nothing about your game's protocol is certified.
- **Direct, with no gateway.** Players connect to the running server's public IP address and port. There is no TLS termination, no origin check and no WebSocket relay from us, so any encryption or authentication is yours to build.
- **You supply the join probe.** An open port never proves a player could join. Declare a `joinProbe` that your server really answers: for TCP, a banner your server sends first (we connect, send nothing, read the first bytes and match `expected`); or an `http` path, or a `udp` request and reply. Without it the release stays at "configuration needed".
- **A launcher script is fine.** If a shell script starts your server with its own arguments, use that script as `command[0]` so the arguments are kept. The image provides bash and a POSIX sh.
- **Linux libraries.** Programs are read for the glibc they need, and a build that needs a newer glibc than the worker image (2.39, Ubuntu 24.04) is held with advice, so build on Ubuntu 24.04.

```json
{
  "engine": "custom-native", "transport": "tcp", "platforms": ["windows"],
  "mode": "dedicated", "networkingImplemented": true, "os": "linux", "arch": "x64",
  "command": ["/game/Server/run-server.sh"],
  "ports": [{ "port": 47777, "protocol": "tcp" }], "profile": "standard",
  "health": { "type": "tcp", "port": 47777 },
  "joinProbe": { "type": "tcp", "port": 47777, "expected": "YOUR-GAME-BANNER" },
  "shutdown": { "signal": "SIGTERM", "graceSeconds": 30 }, "idleSupported": false,
  "artifact": { "id": "<archive id>", "sha256": "<64 lowercase hex characters>" }
}
```

When you declare Mirror or Netcode for GameObjects for a Unity player build that holds none of their assemblies, the code reading raises a non-blocking advisory and suggests this lane. It never rewrites your declaration for you.

## Rules that cause most rejections

- **Paths are inside the machine, not on yours.** `command[0]` and `savePath` must be literal paths under `/game/`.
- **TCP and UDP probes differ.** HTTP and TCP probes need a TCP port; UDP probes need a UDP port. A TCP connect alone never proves a UDP game works.
- **Declare real ports.** Every port your server opens, with the right protocol, and nothing it does not.
- **No secrets.** Credentials in the archive are detected and the build is rejected; the values are never repeated back.
- **Digest of the exact file.** Run `sha256sum server.tar.gz` on the file you upload.

## What a player connection config must carry

NetCraftGames builds a schema-checked JSON document named `netcraft.connection-config/1`, plus engine-specific code snippets, from what it found in your submission and what you declared. Secrets are never included in it.

| Field | What it holds |
| --- | --- |
| `lane` | How players reach you: `gateway_wss` (browser WebSocket through the TLS gateway), `direct_udp`, `direct_tcp` (also used by the custom native lane) or `webrtc_signaling` |
| `endpoint` | Scheme, host, port, path and full URL; each is either filled in or a marked placeholder until publish |
| `originAllowlist` | The exact website origins allowed to connect (browser lanes) |
| `playerFields` | The values a client must set, and whether each comes from NetCraftGames, the player or your code |
| `serverRequirements` | What your server must do for this lane to work |
| `snippets` | Engine-specific example code, each marked as not yet verified |
| `secrets` | Always states that no secret is in the file |
| `gaps` and `notes` | What could not be determined, so you can see what is guessed and what is known |

Browser and WebSocket games are reached at `wss://<gateway host>/play/<gameId>`, which requires an allowed `Origin` and forwards to your server at the root path, or at the one path you write as `wsPath` in your manifest. UDP and raw TCP games, including custom native servers, are reached directly at the running server's public address: the file then carries a generic direct client section (host, port, protocol and what your join probe expects) instead of an engine snippet. WebRTC games use room signaling. Never put a secret in a client config: players can read it.

## Frequently asked questions


### Can I host a game that uses its own TCP or UDP protocol instead of Mirror or Netcode?

Yes, as the Custom native TCP/UDP (direct) lane, which is limited on purpose. NetCraftGames deploys and configures your Linux x64 server, players connect directly to its public IP address and port with no gateway, and you must supply a join probe because an open port never proves gameplay. NetCraftGames does not certify your protocol or your game.

### What is the difference between a manifest and a connection config?

A manifest is what the host needs to run your server: engine, transport, start command, ports, health and join probes, save path and shutdown behavior. A connection config is what players' clients need to reach it: address, port, protocol, TLS and version. NetCraftGames reads your submission to produce the second from the first.

## Related pages

- [Engines and transports NetCraftGames can host](https://netcraftgames.com/engines/): Which engines and transports NetCraftGames is built to host: Unity Mirror and NGO, Unreal, Godot ENet and WebSocket, browser WSS and WebRTC, with honest gaps.
- [What happens when a connection fails](https://netcraftgames.com/connection-failures/): When your game does not connect, NetCraftGames emails the exact problem and a concrete fix, then you resubmit. The 19 failures it detects and how each is fixed.
- [Mirror server on the cloud: ports and firewall checklist](https://netcraftgames.com/guides/mirror-server-ports-firewall-checklist/): A practical ports and firewall checklist for running a Mirror dedicated server on a cloud machine: KCP, Telepathy and SimpleWeb ports, binding and testing.