Factorio: Mods, Worlds and Admin on Your Server

How the files are laid out

A Factorio server has three folders you will be working with:

saves/       your worlds as .zip files
mods/        your mods as .zip files, plus mod-list.json
data/        the game's own files, including the DLC mods

On top of that there is the configuration, server-settings.json, and the access lists. You will find all of it under Files in the Potionhost control panel.

---

Step 1 - server-settings.json

Factorio ships a template at data/server-settings.example.json. Copy it and edit the copy.

Key	Default	Meaning
name	-	The name in the server list
description	-	The description
max_players	0	0 means unlimited. Admins can join a full server
visibility	{"public": true, "lan": true}	An object, not a string
username	""	Your factorio.com account. Required for public listing
token	""	Token from factorio.com. Use it instead of your password
game_password	""	Password to join
require_user_verification	true	Requires players to have a valid factorio.com account
autosave_interval	10	Minutes between autosaves
autosave_slots	5	Number of autosaves cycled through
afk_autokick_interval	0	Minutes idle before a kick. 0 = never
auto_pause	true	Pauses the game when nobody is online
only_admins_can_pause_the_game	true
allow_commands	"admins-only"	true, false or "admins-only"
non_blocking_saving	false	Experimental. Leave it off

visibility is the mistake everyone makes. It has to be written as an object:

"visibility": { "public": true, "lan": true }

and not as "visibility": "public".

Token for public listing

To appear in the public list you need both username and token:

1. Log in to factorio.com and open your profile.
2. Click Reveal next to the token and copy it.
3. Put both into server-settings.json.

Use token rather than password - a token can be revoked, and your account password does not sit in plain text on the server.

Port: Factorio uses UDP 34197. There is no TCP port to open.

---

Step 2 - Mods

Mods are .zip files named name_version.zip, for example Krastorio2_2.0.5.zip. Put them in mods/ - do not extract them.

The server does not download mods itself. There is no mod portal on a headless server. You upload the zip files yourself.

Which mods are enabled is controlled in mods/mod-list.json:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "elevated-rails", "enabled": true },
    { "name": "quality", "enabled": true },
    { "name": "space-age", "enabled": true },
    { "name": "Krastorio2", "enabled": false }
  ]
}

There is no version in the file - the version is decided by which zip sits in the folder. If a mod is in mods/ but not in the list, the server adds it itself as enabled.

mod-settings.dat in the same folder holds the mods' own settings. It is binary and cannot be edited by hand. To change it: configure the mods in a single-player game on your own computer and upload the resulting mod-settings.dat.

---

Step 3 - Space Age and the other DLC mods

The DLC is delivered as four official mods, and they ship with the game in data/ - there is nothing to download. They appear in mod-list.json like any other mod:

Mod	Role
base	The base game. Can never be disabled
space-age	The expansion itself
elevated-rails	Comes with Space Age
quality	Comes with Space Age

To run without Space Age, set space-age, elevated-rails and quality to "enabled": false and leave base alone.

Decide before you create your world. A world made with Space Age enabled cannot simply carry on without it - the map contains the DLC's planets and content. To switch, you need a new world.

If you run Space Age, your players need to own the expansion too.

---

Step 4 - Worlds

Saves are .zip files in saves/. Never extract them.

Create a new world:

./bin/x64/factorio --create ./saves/my-world.zip

Start the server on a specific world:

./bin/x64/factorio --start-server ./saves/my-world.zip --server-settings ./data/server-settings.json

Or on the most recently saved one:

./bin/x64/factorio --start-server-load-latest --server-settings ./data/server-settings.json

The flag is --start-server-load-latest. --start-server-latest-save does not exist and will make the server fail.

Uploading your own world: stop the server, upload the .zip to saves/ and start again. The server has to run the same version as the world or newer - you cannot load a newer world on an older server. And every mod the world uses has to be in mods/ at the right versions.

Autosaves are named _autosave1.zip, _autosave2.zip and so on, and they rotate. With the defaults - every 10 minutes and five slots - you have roughly the last 50 minutes. To roll back, just start the server on the autosave you want.

---

Step 5 - Admins, bans and whitelist

Three JSON files holding lists of usernames:

server-adminlist.json
server-banlist.json
server-whitelist.json

The format is simple:

[ "player1", "player2" ]

The whitelist is only enforced if the server is started with --use-server-whitelist. A populated file without the flag does nothing - a classic support case.

Commands in-game or in the console:

Command	What it does
/promote <player>	Makes the player an admin
/demote <player>	Removes admin again
/ban <player> <reason>	Bans the player
/unban <player>	Lifts a ban
/kick <player> <reason>	Kicks the player
/whitelist add/remove/get/clear	Manages the whitelist
/admins	Lists every admin
/players	Lists the players on the server
/server-save	Saves now

The server writes these files itself when you use the commands - so only edit them while the server is stopped, otherwise your changes are overwritten on shutdown.

---

How players get your mods

When a player joins a modded server, the game asks whether they want to sync. If they accept, their client downloads exactly the same mod versions the server is running.

The client downloads from the mod portal, not from your server. If you use a mod that is not published on the portal - or has been taken down - it cannot be synced. You have to send the zip file to your players manually.

The match is exact: same mods, same versions, same startup settings. There is no tolerance for a single patch version of difference.

---

Troubleshooting

Symptom	Likely cause	Fix
Your active mods don't match the server's	A difference in mods, versions or mod-settings.dat	Accept the sync, or fix the zip files on the server
The sync loops forever	The mod is not on the portal, or the player is not logged in to factorio.com	Send the zip manually
The server is not in the public list	visibility written as a string, or missing username and token	Fix the object and re-copy the token
Missing username	The token is set but username is empty	Both fields are required
Space Age cannot be disabled	The world was created with the DLC enabled	Create a new world
Mods do not load	The zip was extracted or renamed	Upload the untouched name_version.zip again
The server will not load an uploaded world	The world is newer than the server	Update the server - downgrading is not possible
Players cannot connect	UDP 34197 is not open	Open the port. TCP makes no difference
The whitelist does not work	--use-server-whitelist is missing	Add the flag
My admin changes disappeared	The server wrote the file back on shutdown	Only edit the lists while the server is stopped
Desyncs	Almost always mod bugs, not the network	Update mods, and find the culprit by removing them one at a time

---

Good advice

• Back up saves/ and mods/ before every mod update. Mods and worlds belong together.
• Avoid changing mod versions mid-playthrough if you can - every player has to follow along at the same time.
• Set auto_pause to true on a small friends server. Then the factory does not run on while you sleep.
• Leave non_blocking_saving off. Factorio itself calls it experimental.
• Raise autosave_slots if you have the disk space. It is cheap insurance.

Got a mod error you cannot decipher? Send us the contents of factorio-current.log in a ticket.