Terraria server config: serverconfig.txt and commands

A Terraria server is one executable and one text file. TerrariaServer reads serverconfig.txt, opens a single TCP port, loads a .wld file and that is the entire architecture - no query port, no server browser, no RCON, no plugin system. It is refreshingly small, and it is also why the vanilla server gives you twenty-four console commands and nothing else: no permissions, no whitelist, no teleport, no protection. This guide covers every setting in the config file, every console command the server actually has, how world creation works including the secret seeds, the journey mode permission block, and where TShock takes over. Figures here are from the 1.4.5 dedicated server; a key that does not exist in your build will simply be ignored.

How a Terraria server is configured#

The dedicated server is a free download from terraria.org, separate from the game, containing Windows, Linux and Mac builds in one archive. It must be the same version as the clients, down to the fourth digit - a 1.4.5.8 client cannot join a 1.4.5.7 server.

Started with no arguments, the server runs an interactive wizard: choose a world or make one, pick the size, the difficulty, the world evil, a name, a port, whether to forward it with UPnP, and a password. That is pleasant on a desktop and useless on a server, because a process waiting on standard input looks exactly like a process that has hung. Point it at a config file instead:

$ ./TerrariaServer.bin.x86_64 -config serverconfig.txt

Everything in the file has a command line equivalent, and the command line wins where both are set. The file is plain key=value, one per line, # for comments, no spaces around the equals sign and no quotes around values. It is read once at start, so every change needs a restart.

On a panel you are not typing that command. On RE:NODE the world is generated on the first boot and the size and difficulty are fields on the Startup tab, which set the same values the wizard would have asked for.

Requirements, player counts and performance#

Terraria is the lightest game in this catalogue and the numbers are genuinely small.

maxplayers accepts anything from 1 to 255. The number you can actually run is not a memory question, it is an NPC question: the server updates every active NPC and projectile on one thread, and a Frost Moon with sixteen players present is a different workload from sixteen people mining. Load is spiky rather than steady, which is why a Terraria server can idle for an hour and then stutter for ninety seconds during an invasion.

Two settings exist specifically for this. npcstream trades bandwidth against enemy skipping - lower numbers send more data and produce less teleporting, 0 turns the throttle off. slowliquids=1 caps how much liquid moves at once, which helps during large flooding but makes water take longer to settle.

The heavy variant is tModLoader, where every mod loads into the same process and world generation is the peak. That is covered separately in Terraria and tModLoader, hosted properly; size for generation, not for the steady state.

serverconfig.txt, setting by setting#

A worked example for a private server on a large expert world:

world=/home/terraria/.local/share/Terraria/Worlds/Hardmode.wldworldpath=/home/terraria/.local/share/Terraria/Worlds/autocreate=3worldname=Hardmodedifficulty=1maxplayers=10port=7777password=copper-shortswordmotd=Be nice. No grief. Boss fights are announced in Discord.worldrollbackstokeep=3secure=1npcstream=60priority=1

Three notes that save an evening. world wants the full path to the file including the extension; worldpath wants a directory and is used for autocreate and for the world list. autocreate only fires when the file in world does not exist, so leaving it in is safe once the world is made - it is not the same trap as Factorio's --create. And upnp is for a router at home; on hosted infrastructure it does nothing useful and can be left at the default or set to 0.

secure=1 is worth turning on. It adds server-side checks against a handful of common client-side cheats. It is not an anti-cheat and it will not stop a determined inventory editor, but it costs nothing.

Creating the world: size, difficulty, evil and secret seeds#

World size is the autocreate value: 1 small, 2 medium, 3 large. Large worlds take longer to generate, hold more content and are what most groups want. Difficulty is set once at creation and cannot be changed afterwards from the config - 0 classic, 1 expert, 2 master, 3 journey.

World evil - corruption or crimson - is chosen at creation. There is no config key for it, but the command line has -worldevil and the interactive wizard asks. On a panel, that choice is normally a field on the Startup tab alongside size and difficulty.

Then there are the secret seeds, which get their own config keys rather than being typed into seed. Each is a 0 or 1 switch and enabling one overrides the seed text:

#seed_celebration=1#seed_theconstant=1#seed_notthebees=1#seed_notraps=1#seed_fortheworthy=1#seed_remix=1#seed_drunk=1#seed_zenith=1

These are the drunk world, the for-the-worthy world, the no-traps world and the rest. They change world generation profoundly and they are permanent, so set them before the first boot or not at all. If several are enabled the game combines them, which is how people end up with a world they cannot describe.

Journey mode permissions on a server

Journey mode on a multiplayer server is not a free-for-all. Each of its powers has its own permission setting, with three values: 0 locked for everyone, 1 only the host can change it, 2 anyone can change it.

journeypermission_time_setfrozen=1journeypermission_time_setdawn=2journeypermission_time_setnoon=2journeypermission_time_setdusk=2journeypermission_time_setmidnight=2journeypermission_godmode=0journeypermission_wind_setstrength=1journeypermission_rain_setstrength=1journeypermission_time_setspeed=1journeypermission_rain_setfrozen=1journeypermission_wind_setfrozen=1journeypermission_increaseplacementrange=2journeypermission_setdifficulty=0journeypermission_biomespread_setfrozen=0journeypermission_setspawnrate=1

Every one of these defaults to 2 in the shipped example, which means on a stock journey server anybody can freeze time, turn on god mode, change the difficulty and stop biome spread. For a public server that is almost certainly not what you want. journeypermission_setdifficulty and journeypermission_godmode are the two to lock first.

Ports, passwords and connecting#

One port, and it is TCP, which makes Terraria the exception in a catalogue of UDP games. A UDP rule will not help you and a TCP rule is all you need. Game server ports explained covers why most games do the opposite.

There is no public server list and no query protocol, so nothing advertises your server anywhere. Players join through Multiplayer, then Join via IP, then the address, the port and the password in three separate prompts. A hostname works in that first box, so pointing an A record at the server and giving people a name instead of four numbers is worth the five minutes - connecting a domain to a game server has the record to create.

The Steam route is different. Starting the server with -steam and -lobby friends lets your Steam friends join from the friends list without an address at all; -lobby private restricts it to invitations. That is convenient for a small group and irrelevant for a hosted server that people join by address.

Passwords are sent on connect and set in the config or at runtime. Keep them to letters, digits and hyphens - the config parser has no quoting, so a password with spaces or an equals sign in it will not be what you think it is.

Console commands#

The vanilla server reads commands from standard input. This is the complete list.

That is genuinely all of it. There is no operator concept, no whitelist, no teleport, no item command, no region protection and no way to undo griefing. settle is more useful than it looks - a flooded base after someone empties a bucket collection is a solved problem.

Note what is missing from the bottom of that list: nothing here restricts who can do what. A vanilla Terraria server trusts everybody who knows the password. If that is not acceptable, you need TShock.

TShock: accounts, groups and the commands vanilla lacks#

TShock replaces TerrariaServer with a build that keeps the same game and adds a server framework: user accounts, groups and permissions, regions, a whitelist, item bans, logging, a plugin API and a REST interface. It is the standard answer for any Terraria server that is open to strangers.

First run prints a setup code in the console and writes it to tshock/setup-code.txt. Join the server with a normal client and claim it:

/setup 12345678/user add myname a-long-password owner/login myname a-long-password/setup

The first command grants temporary superadmin, the second creates a permanent account in the owner group, the third logs you into it, and the fourth closes setup mode so the code stops working. Do all four in one sitting; a server left in setup mode is a server anyone can take over.

Configuration is tshock/config.json. From TShock 4.4 onwards the keys live inside a Settings object, and names have moved between major versions, so read the file you have rather than a guide written for an older one. The ones people change first:

Groups are the point of TShock. Out of the box there is a ladder from guest through default, vip and the admin tiers up to owner, each with a permission list, and /group addperm and /user group move people around it. Everyday admin then looks like /kick, /ban add, /mute, /tp, /spawn, /butcher, /time day, /region define, /save and /off. Server-side characters can be turned on so that inventories live on the server instead of on each player's machine, which is the only real defence against people arriving with items from a cheated single-player world.

The cost of TShock is the update lag. It has to be rebuilt for each Terraria release, so after a patch you wait days or weeks while your players have already auto-updated. Plan for that before a big content update rather than during one.

Worlds, backups and rollbacks#

A Terraria world is a single .wld file, typically a few megabytes on a small world and tens of megabytes on a large hardmode one. That makes backups trivial and losing a world equally trivial. The server keeps rolling copies according to worldrollbackstokeep, and writes a .bak beside the world, both on the same disk as the original.

• Stop the server properly. exit saves and shuts down. exit-nosave does not, and neither does killing the process. Anything built since the last save is gone.
• Save before you copy. Copying a .wld while the server is running gives you a file mid-write. Run save, wait for the confirmation, then copy.
• Keep copies off the machine. Rolling backups protect you from a bad decision, not from a lost server. On RE:NODE the backup slots on every Terraria plan are stored off the machine they protect and restore with a button, and the Schedules tab can take a nightly one on a cron expression. Backups that actually restore explains why untested backups are not backups.
• Back up before hardmode. Breaking an altar changes the world permanently and generates new biome stripes. It is the single most requested rollback in Terraria.

On a vanilla server, characters are not the server's problem: each player's inventory lives on their own machine, which is why a character can carry gear between worlds and why you cannot stop someone arriving fully equipped. TShock's server-side characters change that, and it is the main reason public servers run it.

Troubleshooting#

The server starts and then does nothing. It is in the interactive wizard waiting for a keystroke. Add -config serverconfig.txt, and check that the path in world exists.

"Lost connection" the moment somebody joins. Version mismatch. The client auto-updated and the server did not. Check the exact build numbers, including the fourth digit.

Nobody outside the network can connect. TCP 7777 is not open, or the address is wrong. Terraria has no query port, so there is no second thing to test - if the port is open and the process is listening, it works.

The password is rejected even though it is right. A space, a quote or an equals sign in the config value. Simplify the password and restart.

The world reverted a few hours. The process was stopped without a save. Use exit, and if the server is being restarted on a schedule, make sure the schedule sends a clean stop rather than a kill.

Enemies teleport around during invasions. That is npcstream doing its job at the default of 60. Lower it to 30 if you have bandwidth to spare, or accept it; the alternative is more data per player.

TShock commands do nothing. You are not logged in. Accounts are separate from characters, so /login after every join unless the group has been granted automatic login.

FAQ#

How many players can a Terraria server hold?

maxplayers allows up to 255 and the honest answer is far fewer. Eight to sixteen is a normal group; past that, invasions and boss fights are what breaks, not the player count itself, because the server updates every NPC and projectile on one thread.

Can I change the world difficulty after creating it?

No. Classic, expert, master and journey are fixed at world generation. Changing difficulty in the config afterwards affects the next world you create, not the one already in the file.

Does a Terraria server need UDP ports?

No. Terraria is TCP on a single port, 7777 by default. That is unusual for a game and it is the reason half the firewall advice you will find for other games does not apply.

Do I need TShock?

Only if you need permissions, protection or plugins. For a password-protected server among friends, vanilla is simpler, updates the day the game does, and has nothing extra to break. For anything public, the vanilla server's lack of any permission system makes TShock close to mandatory.

Where are the world files?

Wherever worldpath points. The defaults are the Terraria folder under Documents on Windows and under the user's local share directory on Linux. On a panel they are in the server's own file tree, where the file manager and SFTP can reach them.

Can I move a single-player world onto the server?

Yes, and it is a straight file copy. Stop the server, upload the .wld file into the world folder, point world at it with the exact file name, and start. Your character comes with you separately, because characters are stored on each player's machine.