Headless client

Hey! The official Resonite wiki is out. It means this is now unmaintained.

The headless client is basically the game without the user interface, allowing you to host somewhat permanent sessions, like with a server.
In order to access the headless client, you need to be a supporter on the Resonite Patreon with a membership of Discoverer or more.

Go back to index..

Downloading the headless client

Note: before proceeding, I can recommend creating a dedicated Steam account for the headless. Doing so will make it easy to automate the process with Docker or scripts later.

Bare metal

To obtain the headless, you currently will need SteamCMD and the headless beta code (can be obtained by sending /headlessCode to the Resonite bot).

Note: it is also possible to download the headless using the regular GUI Steam client, for that right click on Resonite, select “Properties”, go in “Betas” and enter the headless code into the text box. You should now have access to the headless client.

With SteamCMD, the command is fairly simple (note, it will install Resonite in the SteamCMD directory, you can change the path of the +force_install_dir to change that):

bash steamcmd.sh \
    +force_install_dir ./resonite \
    +login SteamAccountName 'SteamAccountPassword' \
    +app_license_request 2519830 \
    +app_update 2519830 -beta headless -betapassword TheHeadlessCode validate \
    +quit

Note: if SteamCMD is giving you any trouble like steamcmd.sh: Not a directory, replace bash steamcmd.sh by ./steamcmd.sh

This will install the headless client into the directory specified, you can now go on to the configuration.
To run the headless client, you can go within the directory and do mono Headless/Resonite.exe and the headless should launch.

Docker

To run a headless within Docker, I can recommend Shadowpanther’s resonite-headless.
It is fairly easy to use.

As specified in the README, the compose file should look like this:

version: "3.3"

services:
  resonite:
    image: shadowpanther/resonite-headless:latest
    container_name: resonite-headless
    tty: true
    stdin_open: true
    environment:
      STEAMBETA: headless
      STEAMBETAPASSWORD: ask-bot-for-code
      STEAMLOGIN: "your_steam_login your_steam_password"
    volumes:
      - "./Config:/Config:ro"
      - "./Logs:/Logs"
      - "/etc/localtime:/etc/localtime:ro"
    restart: unless-stopped

Sveken on Discord made some modifications to the compose file to accommodate for modded Resonite.
For that, you will need to download Resonite Mod Loader, create a directory moddedhead in the data directory where you want to place the files of your headless and place inside the NML files.
Then you can use the following compose file:

version: "3.3"

services:
  resonite:
    image: shadowpanther/resonite-headless:latest
    container_name: modded-headless
    tty: true
    stdin_open: true
    command: mono /home/steam/resonite-headless/Headless/Resonite.exe -LoadAssembly "/home/steam/resonite-headless/Headless/Libraries/ResoniteModLoader.dll" -HeadlessConfig /Config/Config.json -Logs /Logs
    environment:
      STEAMBETA: stuff
      STEAMBETAPASSWORD: things
      STEAMLOGIN: "username password"
    volumes:
      - "/data/moddedhead/Config:/Config:ro"
      - "/data/moddedhead/Logs:/Logs"
      - "/etc/localtime:/etc/localtime:ro"
      - "/data/moddedhead:/home/steam/resonite-headless"
    restart: unless-stopped

This version will hijack the start script to instead run the headless with the -loadAssembly command, thus making it possible to run the headless with mods.

Now that you have this setup, you can proceed to the configuration section.
Launching the headless is as easy as docker compose up -d and docker compose logs to see logs (add -f to it to follow them in real-time).

Configuration

The default headless configuration is as follows:

{
  "$schema": "https://raw.githubusercontent.com/Yellow-Dog-Man/JSONSchemas/main/schemas/HeadlessConfig.schema.json",
  "comment": "DO NOT EDIT THIS FILE! Your changes will be lost. Copy it over and create a new file called Config.json",
  "universeId": null,
  "tickRate": 60.0,
  "maxConcurrentAssetTransfers": 4,
  "usernameOverride": null,
  "loginCredential": null,
  "loginPassword": null,
  "startWorlds": [
    {
      "isEnabled": true,
      "sessionName": null,
      "customSessionId": null,
      "description": null,
      "maxUsers": 16,
      "accessLevel": "Anyone",
      "useCustomJoinVerifier": false,
      "hideFromPublicListing": null,
      "tags": null,
      "mobileFriendly": false,
      "loadWorldURL": null,
      "loadWorldPresetName": "Grid",
      "overrideCorrespondingWorldId": null,
      "forcePort": null,
      "keepOriginalRoles": false,
      "defaultUserRoles": null,
      "roleCloudVariable": null,
      "allowUserCloudVariable": null,
      "denyUserCloudVariable": null,
      "requiredUserJoinCloudVariable": null,
      "requiredUserJoinCloudVariableDenyMessage": null,
      "awayKickMinutes": -1.0,
      "parentSessionIds": null,
      "autoInviteUsernames": null,
      "autoInviteMessage": null,
      "saveAsOwner": null,
      "autoRecover": true,
      "idleRestartInterval": -1.0,
      "forcedRestartInterval": -1.0,
      "saveOnExit": false,
      "autosaveInterval": -1.0,
      "autoSleep": true
    }
  ],
  "dataFolder": null,
  "cacheFolder": null,
  "logsFolder": null,
  "allowedUrlHosts": null,
  "autoSpawnItems": null
}

Configuration keys

Basics

Worlds

Note: you can add as many worlds as you wish, just add a new one in the array.

Commands

There is a bunch of commands that can be used to manage the headless client within its console.