Factorio headless server: setup, settings and admins

The Factorio headless server is a separate download from factorio.com, not the Steam copy of the game with the graphics switched off. It is about 57 MB compressed and under 300 MB installed, it needs no graphics driver and no Steam account, and it will happily run a four-person map inside 1 GB of memory. Everything about it is configured by one JSON file and a handful of command-line arguments. This guide covers all of it: the install, creating a map, every key in server-settings.json, the port, the admin files, RCON, and the autosave behaviour that decides how much progress a crash costs you.

What a Factorio headless server is#

Factorio's multiplayer is deterministic lockstep. The server does not send you the state of the world; it collects everybody's inputs, stamps them with a tick number, and sends that back out. Every machine - server and clients - then runs the identical simulation and arrives at the identical result. That single design decision explains most of what follows:

• Bandwidth per player is tiny. You are sending key presses, not entity positions. A busy eight-player game is a few tens of kilobytes per second in each direction.
• Joining is expensive. A new player has to be given the entire map before they can start simulating it. That is one burst of the whole save file, which is why the settings file has upload limits in it.
• Everyone runs the same mods, at the same versions, or nobody connects. There is no such thing as a client-side-only mod in Factorio. A mod changes the simulation by definition.
• The server needs to keep up on its own. If the server cannot hit 60 updates per second, the whole game slows down for everybody. Clients that fall too far behind are dropped and have to re-download the map.

The headless build has no renderer, no audio and no sprite atlas, which is why its memory use is much lower than the desktop game's on the same save. It cannot take screenshots, it cannot run the map editor, and it cannot show you a GUI mod's settings window - the practical consequences of that are in the mods section below.

Requirements and resource usage#

Factorio is one of the least demanding games to host until it suddenly is not. A fresh map with four people is trivial. The same map three hundred hours later, with a thousand trains and forty thousand bots, will pin one core.

• CPU: the update loop is effectively single-threaded. Core count buys you almost nothing past two; clock speed and cache buy you everything. A server that has fallen to 45 updates per second cannot be fixed by adding cores.
• Disk: the install is under 300 MB. Save files start around 2-5 MB and grow with the explored area - 20-40 MB is a normal mid-game figure, and megabases pass 100 MB. Multiply by your autosave slot count, because they all live on disk at once.
• Network: low and steady, with a spike every time somebody joins. If a player's download of the map is slow, that is max_upload_in_kilobytes_per_second doing what you told it to.

Memory is the one that surprises people, because Factorio holds the entire map in RAM and never lets go. Exploring with radar, adding a second surface, or turning on a mod that generates terrain will all push it up permanently. If the container is stopped at its memory limit mid-game you lose everything since the last autosave, so size for where the base is going rather than where it is. The general point in CPU vs RAM for game servers applies squarely here: find out which one you are actually running out of before buying more of the other.

Installing it and creating a map#

The headless package is not on Steam and there is no SteamCMD app id for it. You download it from factorio.com directly. stable gives you the current stable build; substitute latest for the experimental branch if your group is on one.

$ curl -L -o factorio-headless.tar.xz \    https://factorio.com/get-download/stable/headless/linux64$ tar -xJf factorio-headless.tar.xz -C /opt$ /opt/factorio/bin/x64/factorio --version

The package is self-contained. Its config-path.cfg ships with use-system-read-write-data-directories=false, which means saves, mods, config and logs all live under /opt/factorio rather than in ~/.factorio. That is worth knowing before you go looking for a save file in the wrong place.

/opt/factorio/  bin/x64/factorio          the server binary  config/config.ini         generated on first run  data/                     base game data and the example JSON files  mods/                     mods go here  saves/                    save files and autosaves  factorio-current.log      the log, with factorio-previous.log beside it

Four example files ship in data/: server-settings.example.json, map-gen-settings.example.json, map-settings.example.json and server-whitelist.example.json. Copy the ones you want rather than editing the examples in place, because a game update will overwrite them.

A headless server cannot generate a map on start the way a Minecraft server does. You create the save first, as a separate command:

$ cd /opt/factorio$ cp data/server-settings.example.json data/server-settings.json$ cp data/map-gen-settings.example.json data/map-gen-settings.json$ ./bin/x64/factorio --create ./saves/world.zip \    --map-gen-settings ./data/map-gen-settings.json \    --map-settings ./data/map-settings.json

map-gen-settings.json holds the things you choose on the new-game screen: terrain and ore frequency, size and richness, water, starting area, cliff settings and the enemy base parameters. map-settings.json holds the things that keep changing while the game runs: pollution diffusion, enemy evolution and expansion, path finding budgets and steering. Both are optional - leave them out and you get default settings - but they can only be set at creation time for the map generation half, so it is worth a minute now.

Then start the server:

$ ./bin/x64/factorio --start-server ./saves/world.zip \    --server-settings ./data/server-settings.json \    --server-adminlist ./data/server-adminlist.json \    --port 34197 --console-log ./logs/console.log

--start-server-load-latest is the argument you actually want on a hosted server, because it loads the newest file in saves/ including autosaves. That means a restart after a crash picks up the most recent autosave instead of the save you named three weeks ago.

On a panel-based host you do not type any of this. The install is done for you and the same arguments appear as fields on the Startup tab - on RE:NODE the map is generated on the first boot, and the settings file is already in place with a game password generated for the server.

server-settings.json line by line#

This is the whole configuration. The example file is heavily commented with _comment_ keys, which the server ignores, so you can delete them or leave them.

The four segment_size keys at the bottom control how long network messages are split up as the player count changes. Leave them alone unless you are debugging connection drops on a large public server; raising them increases the server's upload requirement and can make things worse for players on poor connections.

Four of these decide whether your server behaves well:

`visibility.public` with `username` and `token`. A public server has to authenticate against factorio.com. Get the token from your profile page on factorio.com and put it in token, not your account password. If the credentials are wrong the server still starts and still works for direct connections - it just logs a matching-server error and never appears in the list. People spend an hour on firewall rules for what is a typo in a token.

`auto_pause`. On by default, and correct for almost every private group: with nobody connected the game stops advancing, so biters do not evolve and pollution does not spread while you sleep. Turn it off only if you want the factory running unattended, and remember that a paused server still uses its memory.

`allow_commands`. admins-only is the sensible default. Any use of /c permanently marks the save as having used commands, which disables achievements for everyone on it. /silent-command and /measured-command count too.

`autosave_interval`. Ten minutes is the default and it is a reasonable trade. Saving a large map blocks the game for a moment - a noticeable freeze on a megabase - so the temptation is to raise it. Resist: the interval is exactly how much progress an unclean stop costs.

Ports, joining and the public list#

Factorio uses one UDP port and nothing else. There is no separate query port, which makes it one of the simplest games to firewall - and also means a TCP-only rule will silently produce a server that runs and cannot be reached. Game server ports explained covers why that mistake is so common.

There are three ways in:

1. Direct connect. Multiplayer, then Connect to address, then 203.0.113.10:34197. Always works, needs no factorio.com login on the server, and is the first thing to test.
2. The public list. Needs visibility.public, valid credentials and require_user_verification left on. New servers appear within a minute or two.
3. LAN. visibility.lan broadcasts on the local network only. Irrelevant on a hosted server.

Joining is not instant. The client downloads the whole save, which on a mature map is tens of megabytes, then catches up to the current tick. If that catch-up takes too long the join fails and retries. Lowering max_upload_slots to 2 or 3 on a busy server makes each individual join faster at the cost of queueing them.

Admins, whitelist and bans#

Three JSON files, all plain arrays of factorio.com usernames, all passed as arguments:

["kovarex", "Rseding91"]

$ ./bin/x64/factorio --start-server ./saves/world.zip \    --server-settings ./data/server-settings.json \    --server-adminlist ./data/server-adminlist.json \    --server-banlist ./data/server-banlist.json \    --server-whitelist ./data/server-whitelist.json \    --use-server-whitelist

The whitelist is only enforced when --use-server-whitelist is present; the file alone does nothing. The ban list accepts either bare usernames or objects with a username and a reason. All three are written back by the server when you use the matching console commands, so do not hand-edit them while the server is running or your change will be overwritten on the next /ban.

Usernames here are factorio.com account names, which is why require_user_verification matters: with verification off, anyone can claim any name and your admin list becomes decorative.

Console commands and RCON#

The headless server reads commands from standard input, which on a panel is the console box. Anything an in-game admin can type works there, without the leading slash being optional - use the slash.

/config is the one worth memorising, because it changes server-settings.json values on a running game. The keys use hyphens rather than the JSON underscores: allow-commands, autosave-interval, autosave-only-on-server, afk-auto-kick, game-password, ignore-player-limit-for-returning-players, max-players, max-upload-slots, max-upload-speed, non-blocking-saving, only-admins-can-pause, require-user-verification, visibility-lan, visibility-public. So /config set max-players 12 takes effect immediately and /config get game-password tells you what the password actually is when nobody can remember.

RCON is enabled with two arguments and speaks the standard Source RCON protocol over TCP, so rcon-cli, mcrcon and every Discord bridge that supports Minecraft will talk to it:

$ ./bin/x64/factorio --start-server ./saves/world.zip \    --server-settings ./data/server-settings.json \    --rcon-port 27015 --rcon-password "a-long-random-string"

RCON has no rate limiting and no second factor, and anything sent through it runs as an admin. Never expose it to the internet on a guessable password - RCON, safely goes through the failure modes properly.

Saves, autosaves and updates#

Factorio writes _autosave1.zip through _autosave5.zip in saves/, cycling through the slots. On a busy map the save itself is a visible stutter for every player, which is the price of the safety.

• A clean stop saves. Sending the process an interrupt, or pressing Stop on a panel, writes the map before exiting. Watch for the save line in the log before you assume it is done.
• A kill does not. Killing the container, running out of memory, or a host crash loses up to one full autosave interval.
• `--start-server-load-latest` is the safety net. Without it, a restart loads the named file and silently ignores three hours of autosaves.
• Autosaves are not backups. They are on the same disk as the save they protect, and slot cycling means an unnoticed corruption is overwritten within an hour. Take real copies somewhere else, and restore one occasionally to prove it works - that is the entire argument of backups that actually restore.

Updating is a manual download of the new headless package and an unpack over the top; there is no auto-updater in the headless build, and the client and server must be on exactly the same version to connect. On RE:NODE the backup slots included on every Factorio plan cover the "before I update" copy, and the Schedules tab can run a daily backup and a weekly restart on a cron expression without you being there.

Mods live in mods/ as .zip files named ModName_1.2.3.zip, with mods/mod-list.json deciding which are enabled. When a client joins a modded server the game offers to download and enable the matching mods automatically, so players do not need to install anything by hand as long as the mods are on the official portal. The details, including what mods do to update rates, are in Factorio mods and UPS on a server.

Troubleshooting#

The server is not in the public list. Almost always the factorio.com credentials. Check the log for a matching-server error, confirm visibility.public is true, and use the token from your profile rather than your password. Test with a direct connect first: if that works, the server is fine.

"Map version is not compatible" or an outright version mismatch. The client updated and the server did not. Both must be the exact same build. If you run mods, update them before the server, not after.

Players time out while joining a large map. Raise max_upload_in_kilobytes_per_second if you set it, or lower max_upload_slots so fewer transfers share the pipe. A player who has already joined once downloads only the difference, so the first join is always the worst.

Everybody is at 45 updates per second. The server cannot simulate the map fast enough. Nothing about the network will fix it. That is the whole subject of the mods and UPS post.

The server restarts every few minutes. Usually the memory limit on a container being reached during a save, because saving briefly needs more memory than running does. Look at whether the restarts cluster around the autosave interval, then either raise the limit or set non_blocking_saving off if you turned it on. Why your game server keeps restarting covers reading the pattern.

The map reset to a fresh start. A --create left in the start command, or a start command pointing at a save path that does not exist. The old file is usually still in saves/.

Commands do nothing. allow_commands is admins-only and you are not on the admin list, or you are typing into the console without the slash.

FAQ#

Do I need to own Factorio to run a headless server?

No. The headless package is a free download and the server needs no licence. You need a factorio.com account only to publish the server to the public list, and each player obviously needs their own copy of the game.

Can I run the headless server from my Steam install?

No. Steam ships the full game, which is a different build with graphics. You can host from inside the game, but that ties the map to one person's machine and pauses when they leave. The headless package is the separate, correct download.

How many players can a Factorio server hold?

max_players defaults to unlimited and the practical ceiling is the simulation, not the player count. Twenty people on a modest base is fine. The same twenty on a megabase will not be, because every client has to keep up with the same update rate.

Where do I find the join password?

/config get game-password in the console prints it, and game_password in server-settings.json sets it. Changing it with /config set game-password takes effect immediately without a restart.

Why did we lose fifteen minutes after a crash?

The map is written on the autosave timer, not continuously. Anything after the last autosave existed only in memory. Lower autosave_interval, use --start-server-load-latest so restarts pick up the newest file, and stop the server cleanly when you can.

Does the server need the same mods as the clients?

Yes, exactly the same mods at exactly the same versions. Factorio has no client-side-only mods, because every mod changes the simulation. The client will offer to sync automatically with anything published on the mod portal.