Skip to content

Subnautica

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

egg-subnautica.json

updated

Install

Installer image
ghcr.io/ptero-eggs/installers:debian
Steam app
264710
Steam login
not required
Install script
117 lines

Image

  • .NET 9 ghcr.io/ptero-eggs/yolks:dotnet_9

Panel features

  • steam_disk_space

    The Panel tells the user when SteamCMD does not have enough disk space.

Startup

The Panel runs this command to start the server. It replaces each variable in the command with the value of that variable.

16 variables

Startup command

SUBNAUTICA_INSTALLATION_PATH=/home/container/subnautica XDG_CONFIG_HOME=/home/container/.config ./nitrox/server --save nitrox_world --data-path /home/container/NitroxData
  • The ID corresponding to the game to download.

    APPIDUsers cannot see

    required|numeric|digits_between:1,6

  • Your Steam account username

    STEAM_USERNAMEUsers can edit

    required|string|max:64A value is required.

  • Your Steam account password

    STEAM_PASSWORDUsers can edit

    required|string|max:64A value is required.

  • Your Steam Guard Code

    STEAM_GUARDCODEUsers can edit

    nullable|string|max:8

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

    NITROX_VERSIONUsers can edit

    required|string|between:3,12

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

    SAVE_INTERVALUsers can edit

    required|numeric|digits_between:6,7

  • Disables Auto Save: False / True

    SAVE_DISABLEUsers can edit

    required|string|in:True,False

  • The save name for the server.

    SAVE_NAMEUsers can see

    alpha_dash|between:1,100

  • Password neccessary for connecting to the Server

    SUBNAUTICA_PASSWORDUsers can edit

    nullable|string|between:3,12

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

    SUBNAUTICA_ADMIN_PASSWORDUsers can edit

    required|string|between:3,16

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

    SERVER_MODEUsers can edit

    required|string|in:SURVIVAL,FREEDOM,HARDCORE,CREATIVE

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

    PORTFORWARD_ENABLEUsers cannot see

    required|string|in:True,False

  • Switch between savegame formats. Possible values: PROTOBUF, JSON

    SERIALIZER_MODEUsers cannot see

    required|string|in:PROTOBUF,JSON

  • 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)

    MAX_CONNECTIONSUsers can edit

    required|numeric|between:1,200

  • 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.

    DEFAULT_PERMISSIONUsers can edit

    required|string|in:NONE,PLAYER,MODERATOR,ADMIN,CONSOLE

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

    DISABLE_CONSOLEUsers can edit

    required|string|in:True,False

Wings

Stop command
^C (SIGINT)
Running when the console shows
Server started

Files Wings edits

Wings sets these values in these files before each start.

NitroxData/saves/nitrox_world/server.cfg properties

ServerPort
{{server.build.default.port}}
SaveInterval
{{server.build.env.SAVE_INTERVAL}}
DisableAutoSave
{{server.build.env.SAVE_DISABLE}}
ServerPassword
{{server.build.env.SUBNAUTICA_PASSWORD}}
AdminPassword
{{server.build.env.SUBNAUTICA_ADMIN_PASSWORD}}
GameMode
{{server.build.env.SERVER_MODE}}
AutoPortForward
{{server.build.env.PORTFORWARD_ENABLE}}
SerializerMode
{{server.build.env.SERIALIZER_MODE}}
MaxConnections
{{server.build.env.MAX_CONNECTIONS}}
DefaultPlayerPerm
{{server.build.env.DEFAULT_PERMISSION}}
DisableConsole
{{server.build.env.DISABLE_CONSOLE}}

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.

Changes

  1. Subnautica Nitrox: Update to Nitrox 1.8.x (#553)

    · Mark Norton · ad30ce4

  2. subnautica update (#279)

    · Red Banana · cd4defd

  3. Add steamcmd based eggs

    · Daniel Barton · 60ef9fb

All changes on GitHub

Problem with this egg?

Open an issue on GitHub. Include your Panel and Wings versions.

Install script 117 lines bash in ghcr.io/ptero-eggs/installers:debian Show
#!/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