Subnautica

games
Report Issue

Subnautica is an open world survival action-adventure video game developed and published by Unknown Worlds Entertainment. In it, players are free to explore the ocean on an alien planet, known as planet 4546B, after their spaceship, the Aurora, crashes on the planet's surface. Note: NitroxMod version 1.8+ is required

Contributors:
README

Subnautica: Nitrox Mod

Subnautica is an open world survival action-adventure video game developed and published by Unknown Worlds Entertainment. In it, players are free to explore the ocean on an alien planet, known as planet 4546B, after their spaceship, the Aurora, crashes on the planet's surface. The multiplayer function is provided by the mod "Nitrox". This mod is still in alpha version and therefore not yet fully stable.

Requirements

  • Nitrox 1.8+ — older versions are not supported by this egg.
  • A Steam account that owns Subnautica. The account must use email-based Steam Guard; the authenticator app is not supported by SteamCMD's +set_steam_guard_code flow.

Steam Guard install flow

Steam Guard codes are single-use and expire quickly.

  1. Trigger the first install with STEAM_GUARDCODE blank. SteamCMD's login will fail and Steam will email a fresh code to the account owner.
  2. Paste that code into the Steam Guard Code variable on the server's Startup page.
  3. Reinstall the server — the install script consumes the code and downloads Subnautica.
  4. Clear the Steam Guard Code field after the install succeeds; it's not needed on subsequent boots.

Server Ports

Nitrox uses a single UDP port. Pterodactyl's default allocation is assigned automatically.

Port Default Protocol
Server any UDP

Make sure the allocation includes UDP. Nitrox 1.8 removed the old "must be ≥1024" port restriction, so any free port the node allows is fine.

Save folder

The save folder is hardcoded to nitrox_world (visible in the Save Name variable as read-only). Files live under NitroxData/saves/nitrox_world/. The Save Name variable is locked because Pterodactyl's config-file parser does not template variables inside file paths — changing it would break the panel's ability to manage server.cfg.

Configuration

The egg manages these server.cfg keys from variables (no need to hand-edit unless you want options the egg doesn't expose):

  • ServerPort (from the panel's allocation)
  • SaveInterval, DisableAutoSave
  • ServerPassword, AdminPassword
  • GameMode, SerializerMode
  • MaxConnections, DefaultPlayerPerm, DisableConsole
  • AutoPortForward

The full server.cfg lives at NitroxData/saves/nitrox_world/server.cfg. Editable through the panel file manager when the server is stopped. Other Nitrox config keys not exposed as variables can be edited directly there.

Known limitations

  • In-game console is not interactive from the panel console. Typing /op, /kick, etc. into Pterodactyl's web console will not reach Nitrox. This is upstream — Nitrox's ConsoleInputService requires raw-mode terminal behaviour that Pterodactyl Wings' TTY doesn't currently provide. A yolks-level wrapper is being tracked in the Pterodactyl community. The server itself works fine; admin commands must currently be issued in-game by a player with admin permissions.
  • Graceful stop uses SIGINT, not the stop console command. Consequence of the above. Pterodactyl's Stop button still works — the egg's stop configuration is set to ^C, which .NET Generic Host catches and converts into a clean save + shutdown.

Updating Nitrox

Set the Nitrox Version variable to latest (default) and reinstall to pull the newest release. Pin to a specific tag (e.g. 1.8.1.0) if you need to lock the version — see Nitrox releases for tags.

Docker Images (1)
Name Image
ghcr.io/ptero-eggs/yolks:dotnet_9 ghcr.io/ptero-eggs/yolks:dotnet_9
Startup Command
SUBNAUTICA_INSTALLATION_PATH=/home/container/subnautica XDG_CONFIG_HOME=/home/container/.config ./nitrox/server --save nitrox_world --data-path /home/container/NitroxData
Variables (16)

Steam App ID

The ID corresponding to the game to download.

Environment:
APPID
Default:
264710
User Viewable:
User Editable:
Rules:
required|numeric|digits_between:1,6

Steam Username

Your Steam account username

Environment:
STEAM_USERNAME
Default:
None
User Viewable:
User Editable:
Rules:
required|string|max:64

Steam Password

Your Steam account password

Environment:
STEAM_PASSWORD
Default:
None
User Viewable:
User Editable:
Rules:
required|string|max:64

Steam Guard Code

Your Steam Guard Code

Environment:
STEAM_GUARDCODE
Default:
None
User Viewable:
User Editable:
Rules:
nullable|string|max:8

Nitrox Version

Which version of Nitrox to install and use. Use the version e.g. 1.8.1.0 or latest for the newest release

Environment:
NITROX_VERSION
Default:
latest
User Viewable:
User Editable:
Rules:
required|string|between:3,12

Auto Save Interval

Time between auto saves specified in milliseconds. Default is 2 minutes (120000ms).

Environment:
SAVE_INTERVAL
Default:
120000
User Viewable:
User Editable:
Rules:
required|numeric|digits_between:6,7

Disable Auto Save

Disables Auto Save: False / True

Environment:
SAVE_DISABLE
Default:
False
User Viewable:
User Editable:
Rules:
required|string|in:True,False

Save Name

The save name for the server.

Environment:
SAVE_NAME
Default:
nitrox_world
User Viewable:
User Editable:
Rules:
alpha_dash|between:1,100

Server Password

Password neccessary for connecting to the Server

Environment:
SUBNAUTICA_PASSWORD
Default:
None
User Viewable:
User Editable:
Rules:
nullable|string|between:3,12

Admin Password

If specified, players must provide this password to gain access to administrator commands on the server.

Environment:
SUBNAUTICA_ADMIN_PASSWORD
Default:
PleaseChangeMe
User Viewable:
User Editable:
Rules:
required|string|between:3,16

Game Mode

Subnautica game mode. SURVIVAL = manage food/water/oxygen. FREEDOM = no survival meters. HARDCORE = permadeath survival. CREATIVE = unlimited resources, no damage.

Environment:
SERVER_MODE
Default:
SURVIVAL
User Viewable:
User Editable:
Rules:
required|string|in:SURVIVAL,FREEDOM,HARDCORE,CREATIVE

Auto Portforward via UPnP

If set to true, the server will try to open port on your router via UPnP

Environment:
PORTFORWARD_ENABLE
Default:
False
User Viewable:
User Editable:
Rules:
required|string|in:True,False

Serializer Mode

Switch between savegame formats. Possible values: PROTOBUF, JSON

Environment:
SERIALIZER_MODE
Default:
JSON
User Viewable:
User Editable:
Rules:
required|string|in:PROTOBUF,JSON

Max Players

Maximum number of players that can be connected simultaneously. Nitrox alpha is generally tested up to ~10; higher counts work but stability varies. (200 max)

Environment:
MAX_CONNECTIONS
Default:
10
User Viewable:
User Editable:
Rules:
required|numeric|between:1,200

Default Player Permissions

Permission level new players are assigned when they first join. NONE = guest (no commands). PLAYER = standard. MODERATOR = can kick. ADMIN = full server control. CONSOLE = reserved for server console.

Environment:
DEFAULT_PERMISSION
Default:
PLAYER
User Viewable:
User Editable:
Rules:
required|string|in:NONE,PLAYER,MODERATOR,ADMIN,CONSOLE

Disable In-Game Console

Set to True to disable the in-game developer console for connected players. Leave False for normal use.

Environment:
DISABLE_CONSOLE
Default:
False
User Viewable:
User Editable:
Rules:
required|string|in:True,False
Installation Script
Container: ghcr.io/ptero-eggs/installers:debian
Entrypoint: bash
#!/bin/bash
# Installation Script for Subnautica + Nitrox

# Install dependencies
dpkg --add-architecture i386
apt update
apt -y --no-install-recommends install curl jq unzip libstdc++6 ca-certificates libsdl2-2.0-0:i386

# Resolve Nitrox download URL (latest or pinned NITROX_VERSION)
GITHUB_PACKAGE="SubnauticaNitrox/Nitrox"
case "$(uname -m)" in
  aarch64|arm64) ARCH_TAG="linux_arm64" ;;
  *) ARCH_TAG="linux_x64" ;;
esac

if [ -z "${NITROX_VERSION}" ] || [ "${NITROX_VERSION}" = "latest" ]; then
    RELEASE_JSON=$(curl -fsSL "https://api.github.com/repos/${GITHUB_PACKAGE}/releases/latest")
else
    ALL_RELEASES=$(curl -fsSL "https://api.github.com/repos/${GITHUB_PACKAGE}/releases")
    RELEASE_JSON=$(printf '%s' "${ALL_RELEASES}" | jq -c --arg v "${NITROX_VERSION}" '.[] | select(.tag_name == $v)')
    if [ -z "${RELEASE_JSON}" ]; then
        echo "Nitrox version ${NITROX_VERSION} not found; falling back to latest"
        RELEASE_JSON=$(curl -fsSL "https://api.github.com/repos/${GITHUB_PACKAGE}/releases/latest")
    fi
fi

DOWNLOAD_URL=$(printf '%s' "${RELEASE_JSON}" | jq -r --arg arch "${ARCH_TAG}" '.assets[] | select(.name | test($arch; "i")) | .browser_download_url' | head -n1)

if [ -z "${DOWNLOAD_URL}" ] || [ "${DOWNLOAD_URL}" = "null" ]; then
    echo "Could not determine Nitrox download URL for ${ARCH_TAG}"
    printf '%s' "${RELEASE_JSON}" | jq '.assets[] | {name, browser_download_url}'
    exit 1
fi

# Install SteamCMD
mkdir -p /mnt/server/steamcmd
cd /tmp
curl -fsSL -o steamcmd.tar.gz https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz
tar -xzf steamcmd.tar.gz -C /mnt/server/steamcmd
cd /mnt/server/steamcmd

chown -R root:root /mnt
export HOME=/mnt/server

if [ -z "${STEAM_GUARDCODE}" ]; then
    echo "### No Steam Guard code provided."
    echo "### One should be emailed to you shortly; set STEAM_GUARDCODE and reinstall."
    sleep 5
    timeout 60 ./steamcmd.sh +force_install_dir "${HOME}/subnautica" +login "${STEAM_USERNAME}" "${STEAM_PASSWORD}" +quit
    exit 1
fi

mkdir -p "${HOME}/subnautica"
./steamcmd.sh +force_install_dir "${HOME}/subnautica" +@sSteamCmdForcePlatformType windows +set_steam_guard_code "${STEAM_GUARDCODE}" +login "${STEAM_USERNAME}" "${STEAM_PASSWORD}" +app_update "${APPID}" ${EXTRA_FLAGS} validate +quit
status=$?

if [ $status -ne 0 ]; then
    echo "### Subnautica download failed (likely a bad/expired Steam Guard code)."
    echo "### A new code should arrive shortly; update STEAM_GUARDCODE and reinstall."
    sleep 5
    timeout 30 ./steamcmd.sh +force_install_dir "${HOME}/subnautica" +login "${STEAM_USERNAME}" "${STEAM_PASSWORD}" +quit
    exit 1
fi

mkdir -p "${HOME}/.steam/sdk32" "${HOME}/.steam/sdk64"
cp -v linux32/steamclient.so "${HOME}/.steam/sdk32/steamclient.so"
cp -v linux64/steamclient.so "${HOME}/.steam/sdk64/steamclient.so"

rm -rf "${HOME}/nitrox"
mkdir -p "${HOME}/nitrox"
cd "${HOME}/nitrox"
curl -fsSL "${DOWNLOAD_URL}" -o Nitrox.zip
unzip -q Nitrox.zip
rm Nitrox.zip
if [ "$(find . -mindepth 1 -maxdepth 1 | wc -l)" = "1" ]; then
    WRAPPER=$(find . -mindepth 1 -maxdepth 1 -type d)
    if [ -n "${WRAPPER}" ]; then
        mv "${WRAPPER}"/* "${WRAPPER}"/.[!.]* . 2>/dev/null || true
        rmdir "${WRAPPER}"
    fi
fi
if [ -f "${HOME}/nitrox/Nitrox.Server.Subnautica" ]; then
    ln -sf Nitrox.Server.Subnautica "${HOME}/nitrox/server"
else
    ln -sf NitroxServer-Subnautica "${HOME}/nitrox/server"
fi
chmod +x "${HOME}/nitrox/server" 2>/dev/null || true

mkdir -p "${HOME}/.config"

mkdir -p "${HOME}/NitroxData/saves/nitrox_world"
CFG="${HOME}/NitroxData/saves/nitrox_world/server.cfg"
if [ ! -e "${CFG}" ]; then
    {
        echo "CreateFullEntityCache=False"
        echo "Seed="
        echo "ServerPort=11000"
        echo "SaveInterval=120000"
        echo "PostSaveCommandPath="
        echo "MaxConnections=${MAX_CONNECTIONS}"
        echo "InitialSyncTimeout=300000"
        echo "DisableConsole=${DISABLE_CONSOLE}"
        echo "DisableAutoSave=False"
        echo "ServerPassword="
        echo "AdminPassword=PleaseChangeMe"
        echo "GameMode=SURVIVAL"
        echo "SerializerMode=JSON"
        echo "DefaultPlayerPerm=${DEFAULT_PERMISSION}"
        echo "DefaultOxygenValue=45"
        echo "DefaultMaxOxygenValue=45"
        echo "DefaultHealthValue=80"
        echo "DefaultHungerValue=50.5"
        echo "DefaultThirstValue=90.5"
        echo "DefaultInfectionValue=0.1"
        echo "AutoPortForward=False"
    } > "${CFG}"
fi