12 KiB
Empostor
Empostor is an open-source private server implementation for Among Us.
Features
- FriendCode support (authentication)
- Dynamic ports
- Admin Panel (dashboard)
- Plugin support
- Server-side anticheat
Getting Started
To run the server, you need:
Download the build you'd like from the releases. You most likely want the x64 build. Use the arm64 build if you are running Empostor on a Raspberry Pi, another ARM-based SBC, or an ARM VPS.
Unzip the file and go to config.json. To make your server playable for other devices, replace the "PublicIp" field with your actual public IP address.
It is also recommended to set up a Reverse Proxy (for HTTPS connections).
Docker
Docker Compose port mappings are generated from config.json on the host before the container starts. Install the .NET 10 SDK, Docker Engine with Compose v2, and Python 3.9 or newer. Generate the Linux x64 release, then set Server.PublicIp in its config.json to your public IP or domain:
dotnet tool restore
dotnet cake build.cake --target=Build
cd build/Empostor-Server_linux-x64
python3 docker-up.py
On Windows, use Set-Location build/Empostor-Server_linux-x64 and python docker-up.py. The Linux x64 generated release folder contains the published server files, config.json, and the three Docker files. Cake adds these files to the release folder; it does not create a separate image context or deployment archive. The host-side launcher reads config, fills the port sections in Dockerfile and compose.yml, then invokes Compose using the same folder as the image build context. Rerun the Cake build after updating the server or marketplace. Set EMPOSTOR_CONFIG to use a different configuration file; the launcher reads and mounts that same file read-only.
| Configuration | Published ports |
|---|---|
| HTTP enabled | HttpServer.ListenPort/tcp, with the same host and container port |
| DeltaPort range enabled | DeltaPortStart through DeltaPortEnd/udp, with identical host and container ranges |
GameCode with GameCodePorts |
Only GameCodePorts[0]/udp |
| GameCode with an empty list, or DeltaPort range disabled | PublicPort:ListenPort/udp |
After changing port or verification settings, rerun python3 docker-up.py up -d --force-recreate to regenerate the mappings and reload the configuration. Use the launcher for other Compose commands too, for example python3 docker-up.py logs -f or python3 docker-up.py down. Running docker compose up directly does not generate port mappings.
Keep Server.ListenIp and HttpServer.ListenIp at 0.0.0.0 for IPv4 bridge networking. Keep UseUfw and UseFirewalld disabled inside the container and allow the published ports in the host/cloud firewall. The default DeltaPort range publishes 20,001 UDP ports, which can be slow to create in Docker; reduce the range to suit your expected player count, or use GameCode for a single shared UDP port. The pool also reserves DeltaPortLowWaterMark ports (default 5).
The image runs as the non-root app user. Persistent Docker volumes hold Data, Log, plugins, libraries, Pages, Languages, languages, and Update; plugin files and generated configurations in these directories remain writable across container recreation. Program files and the bundled marketplace catalog/assets remain root-owned. Empty named volumes receive the image's initial contents, including bundled pages/themes. Existing volumes retain their contents when the image is rebuilt; back them up and update bundled assets separately when needed. Installed plugins can be managed through the admin marketplace. For host bind mounts instead of named volumes, grant the container user write access (UID 1654 in the .NET 10 image). Custom plugin output paths must point into a writable mounted directory.
Client Setup
Windows
- Go here and enter your server's IP/domain, port and name. Press "Download server file"
- Press Win + R and enter this (leave the quotation marks):
"%userprofile%\AppData\LocalLow\Innersloth\Among Us"
- Put the new regionInfo.json file you downloaded in the folder. Overwrite the existing file in the folder.
- Launch Among Us. If everything worked, your server should appear in the regions list!
Android/iOS
- Launch Among Us. When you reach the main menu, close the app.
- Go here and enter your server's IP/domain, port and name.
- Scroll until you see Instructions and press the Android or Apple logo.
- Press "Open in Among Us". Among Us should open.
- Your server should appear in the regions list!
Configuration
All settings live in config.json next to the server binary (a full sample is src/Empostor.Server/config.json). Unknown keys are ignored, so an old config keeps working after an update.
| Section | Purpose |
|---|---|
Server |
Public IP/port, listen address and the client verification mode (VerificationMode, DeltaPortStart..DeltaPortEnd) |
HttpServer |
Web API, admin panel and matchmaking token endpoint (Enabled, ListenIp, ListenPort) |
AntiCheat |
Server-side anticheat, including the IP request rate limit |
Timeout |
Spawn and connection timeouts |
Compatibility |
Game version compatibility rules |
Debug |
Game recorder |
AuthApi |
Friend code resolution (Mode: GameServices, Ume, Both or Off) |
Admin |
Admin panel password and marketplace URL |
HPLP |
HPLP public region listing |
Verification mode
Empostor has to know which HTTP authentication (POST /api/user) belongs to which raw UDP connection, because the game's UDP handshake carries no token, PUID or game code. Server.VerificationMode selects how:
| Mode | Behaviour |
|---|---|
DeltaPort (default) |
Every player gets a unique dynamic UDP port from the DeltaPortStart..DeltaPortEnd pool. The port itself is the proof of identity. |
GameCode |
No dynamic ports at all — only the shared listen port (GameCodePorts[0], or ListenPort) is used. The lobby list hands out a server-issued challenge game code per player, and the JoinGame that follows over UDP is authenticated by that code alone. |
| Key | Default | Description |
|---|---|---|
VerificationMode |
DeltaPort |
DeltaPort or GameCode |
GameCodePorts |
[] |
Ports for GameCode mode; only the first is bound. Empty falls back to ListenPort/PublicPort |
TemporaryGameCodeLifetimeSeconds |
180 |
How long an issued challenge code stays valid |
In GameCode mode the port pool is disabled (no delta listeners, no per-player firewall rules) and DeltaPortStart/DeltaPortEnd are ignored.
The game client validates the game code of every message it receives against the code it joined with and silently drops mismatches, and the UDP handshake carries no token/PUID/game code. GameCode mode therefore uses the code itself as the token:
- A lobby listing returns a challenge code — a second, server-generated game code (same format, so the client accepts it as a normal join target) bound to
(authenticated user, real game, player name, client version). JoinGame(challenge)over UDP is resolved by the challenge code alone — no IP, no PUID, no name matching. The challenge is single-use and expires afterTemporaryGameCodeLifetimeSeconds, so many players can join the same game at the same time without being mixed up.- The server then re-keys the client with
Msg00 HostGamecarrying the real code (AmongUsClient.OnGameCreatedis empty, so this only overwritesGameId). Everything after that — game data, the in-lobby code display, invites — uses the real code, so no message rewriting is needed.
HostGame is the one exception: no code exists before the host message, so the hosting socket is matched against the PUT /api/games request by IP, player name and client version (the PUID comes from the HTTP token). Joining an already hosted game with the real code (legacy POST /api/games, e.g. Steam invites) still falls back to the same name/version/IP matching.
AntiCheat
| Key | Default | Description |
|---|---|---|
Enabled |
true |
Master switch of the anticheat |
BanIpFromGame |
true |
Also block banned IPs on the game (UDP) side |
AllowCheatingHosts |
Never |
What happens to hosts that cheat |
EnableGameFlowChecks, EnableMustBeHostChecks, EnableOwnershipChecks, EnableRoleChecks, EnableTargetChecks |
true |
Game flow / state validation |
EnableColorLimitChecks, EnableNameLimitChecks, EnableItemLimitChecks |
true |
Lobby limits (colors, names, items) |
ForbidProtocolExtensions |
true |
Reject unknown/extension protocol messages |
EnablePacketSizeChecks, PacketSizeLimit |
true, 1203 |
Maximum inbound packet size |
EnableRateLimits |
true |
IP request rate limit and game-side rate limits (below) |
Ip request rate limit
Within one window (1 minute) the same IP may only make 30 TCP (HTTP) requests — this protects the HTTP API against connection/request flooding. The limit lives in IpRateLimitService and is switched by EnableRateLimits. When the limit is exceeded:
- Every endpoint answers with
429 Too Many Requestsplus the standard matchmaker error body{"Errors":[{"Reason":116}]}—116isDisconnectReason.TooManyRequests, which the client renders as its own localized "too many requests" popup without retrying. TheRetry-Afterheader says how many seconds are left. - This includes the whole join flow of the game client (
POST /api/usermatchmaking token andPUT/GET /api/gamesFindHost): the client never receives a token or a port, so it never enters the UDP phase and no dynamic pool port is spent on a blocked request — the player gets the popup and returns to the main menu instead of a black screen. /adminand/api/adminare neither counted nor limited, so the dashboard can never lock the operator out.
Empostor usually runs behind a CDN or reverse proxy, so the real client IP is taken from the X-Real-IP header, then from the first entry of X-Forwarded-For, and only afterwards from the socket address. Make sure your CDN/proxy forwards one of these headers — otherwise every player would share the proxy IP's quota. Note that the game client polls some endpoints (e.g. /api/games) while you play: if 30 per minute is too tight for your players, set EnableRateLimits to false (that also switches off the game-side RPC/task rate limits).
Contributing
Please read the contributing guidelines.
You're welcome to open a pull request/issue!
Documentation
The documentation is available here!
License
This project is licensed under the GPL-v3.0 License.