CS2 workshop maps on a dedicated server

A Counter-Strike 2 server loads community maps by their Steam Workshop id, not by file name. host_workshop_map <id> downloads one map and starts it; host_workshop_collection <id> turns a whole Workshop collection into the server's map pool, and ds_workshop_changelevel <name> moves between the maps in it. Players do not install anything - the CS2 client fetches the map from the Workshop as it connects. Almost everything that goes wrong comes from four places: a missing or invalid game server token, a collection that is not public, a map name typed differently from the one the server knows, and a disk that fills up as the collection grows. This guide covers each of those, plus how to build a rotation that survives a restart.

How workshop maps reach a CS2 server#

In CS:GO you could still drop a .bsp into the maps folder and load it by name. CS2 maps are packed .vpk files compiled for Source 2, and the supported way to get a community map onto a dedicated server is the Workshop. The server asks Steam for the item, downloads it into its own Workshop cache, mounts it, and then loads the map inside it. The client does the same thing from its side when it connects.

That design has three consequences worth holding on to:

• The id is the map. A Workshop item id is a long integer from the item's URL (?id=3070596702). The map's internal name, such as de_cache, is only known once the item has been downloaded.
• Steam must trust the server. Workshop downloads go through the server's Steam login, which on a public server is the Game Server Login Token. A server with no token, an expired token, or a banned one usually reports the problem as "the map would not download" rather than as a token error. Steam game server tokens explains how to issue and replace one.
• Updates follow the author. When the author publishes a new version, the server picks it up the next time it loads the map. That is convenient for bug fixes and occasionally painful when an update breaks spawns the night before a tournament.

Running a single workshop map#

The simplest case is one map, for example a practice server that only ever runs an aim map, or a scrim on a map Valve has removed from the official pool. Put the command on the launch line in place of +map:

$ ./game/bin/linuxsteamrt64/cs2 -dedicated -port 27015 +game_alias competitive \    +sv_setsteamaccount <token> +host_workshop_map 3070596702

On the first start the console shows the download progress, then the map loads. On later starts the server checks the item, finds it current, and loads straight away. The same command typed into the console of a running server downloads and switches in one go, which is the quickest way to test a map before committing to it.

On a panel host you do not write the full line. The launch arguments are built from the fields on the Startup tab, and the token sits on its own field; the Workshop command either goes in a startup field if the template provides one, or is typed into the console once the server is up. On RE:NODE the CS2 install itself is run for you and waits on the Setup tab until you paste your own token, which is also the token Workshop downloads use - so a server with a correct token has no extra Workshop step to configure.

Running a collection as the map pool#

A collection is a Workshop page that lists other items. Create one from any map's Workshop page ("Add to collection"), add the maps you want, set its visibility to public, and copy its id from the URL. A private or friends-only collection is the most common reason a server starts with nothing.

$ ./game/bin/linuxsteamrt64/cs2 -dedicated +game_alias casual \    +sv_setsteamaccount <token> +host_workshop_collection 3123456789

On start the server downloads every map in the collection before loading the first one. With a dozen maps of a few hundred megabytes each, the first boot can take several minutes, and the console will show one download after another. That is normal. Restarts after that only download items that changed.

Once it is running, find out what the server thinks the maps are called:

ds_workshop_listmapsds_workshop_changelevel de_cache

ds_workshop_listmaps prints the map names, and ds_workshop_changelevel takes one of those names. Names are not always what the Workshop title suggests - a map titled "Cache" might be de_cache, de_cache_cs2 or something the author invented - so copy them from the output rather than guessing.

Historically, loading a collection on a Source dedicated server needed a Steam Web API key passed with -authkey, and CS2 has changed its behaviour around this more than once since release. If a collection refuses to load while single maps from it load fine, generate a key under your Steam account's Web API page, add -authkey <key> to the launch line, and try again. Check the current state in Valve's CS2 dedicated server notes before you build a large rotation around collections - single-map loading has been the stable path throughout.

Choosing which map the server starts on

When a collection loads, the server picks the first map itself. If you want a specific starting map, the reliable method is to let the server start, then change to the map you want with ds_workshop_changelevel from a console command or a scheduled task. Some launch scripts combine +host_workshop_collection with +host_workshop_map to set the starting map; that worked on some builds and not others, so test it on your version rather than relying on it.

Map rotation: the engine, the map group and plugins#

CS2 has three overlapping ways to decide what plays next, and a server with workshop maps needs to pick one deliberately.

1. Collection as map group. When the server runs a collection, the end-of-match map vote (mp_endmatch_votenextmap 1) and the next-map logic draw from the collection's maps. This is the zero-configuration route and the one most small community servers use.
2. `mapcycle.txt` and `gamemodes_server.txt`. These are the engine and Valve-layer rotation files, covered in CS2 server commands and cvars. They work well for stock maps. For Workshop maps their behaviour is less predictable - a map group entry needs the map to be resolvable by name, and that depends on it already being downloaded. Treat them as a stock-map tool.
3. A map plugin. Rock-the-vote and nomination plugins for CounterStrikeSharp keep their own map list, usually a name plus the Workshop id for each entry, and change maps with the Workshop commands themselves. This is how most busy community servers rotate, because it gives players a vote and gives you a list you can edit without touching the collection.

The cvars that matter whichever route you pick:

mp_match_end_changelevel 1   // change map when the match endsmp_endmatch_votenextmap 1    // show the next-map vote at match endmp_match_end_restart 0       // do not replay the same mapmp_timelimit 30              // minutes per map on modes that use itmp_maxrounds 16              // rounds per map; the mode config may override

Remember that the game mode config is executed after server.cfg on every map load and overrides any round cvars it also sets. If your mp_maxrounds keeps resetting on a casual server, put it in the mode's own override file instead - gamemode_casual_server.cfg for casual, which runs last. Metamod and CounterStrikeSharp covers installing the plugin layer if you go the third route.

Building a collection that behaves#

A collection is a server configuration you keep on Steam, so it deserves the same care as server.cfg.

• Keep it small. Ten to fifteen maps is plenty for one community. Every map costs disk on the server and a download for every new player, and a forty-map collection means most maps are never voted for.
• Own the collection. Make it under an account your community controls, not a moderator's personal account. If they leave and delete it, the server starts with nothing.
• Watch for map updates. Subscribe to the items yourself so Steam tells you when an author publishes a change. An updated map is fetched the next time it loads; a broken update is fixed by removing it from the collection until the author fixes it.
• Prefer maintained maps. Many maps were ported quickly when CS2 launched and have not been touched since. A port with missing clip brushes or broken lighting looks fine in screenshots and plays badly.
• Separate by mode. A surf collection, an aim collection and a defuse collection on three servers beat one mixed collection where the vote offers a surf map to a defuse crowd. Surf, bhop and KZ servers and retakes and deathmatch servers each have their own map habits.

Disk, first boot and the Workshop cache#

Workshop content lives inside the server's install, in its own steamapps/workshop tree (the exact path has moved between CS2 builds, so search for the content/730 folder rather than trusting a guide). Each map is one or more .vpk files plus its metadata. Sizes vary enormously: a small aim map can be tens of megabytes, a detailed defuse map several hundred.

The base CS2 install is already large, so a big collection on a small plan runs out of disk long before it runs out of memory. When the disk fills during a download the server usually fails in an unhelpful way - a map that "does not exist", or an update that cannot be applied - so check free space first whenever Workshop behaviour suddenly changes. Removing a map from the collection does not delete it from the cache; clear old item folders by hand with the server stopped if space is tight. Steam Workshop mods on dedicated servers explains the cache layout and why first boots time out across games.

Memory is a smaller concern. A loaded map adds to the server's working set while it is the current map, but CS2 does not hold the whole collection in memory, so a ten-map rotation costs roughly what the largest map in it costs.

Changing maps on a schedule#

A common request is "aim map in the afternoon, defuse maps in the evening" or "always start on the same map after the nightly restart". Both are console commands on a timer.

ds_workshop_changelevel de_cachehost_workshop_map 3070596702

On RE:NODE the Schedules tab runs a cron expression against an ordered list of tasks - a console command, a backup or a power action, with delays between them - so a nightly restart followed two minutes later by ds_workshop_changelevel on your preferred map is one schedule. On your own machine the same thing is an RCON client in cron. Cron expressions explained covers the syntax, and restart schedules that help covers when a restart is worth having at all.

Do not schedule map changes while people are playing a match. A change mid-round ends it for everyone, and a scheduled task does not know a scrim is on. Pick an hour when the server is reliably empty, or have the schedule print a warning with say a few minutes before.

Troubleshooting workshop maps#

The server starts on a stock map and ignores the collection. The collection is private or friends-only, or the id is of a single map rather than a collection. Open the id in a logged-out browser; if you cannot see it, neither can the server.

"Failed to download" or the download never starts. Token first: check the boot log for the Steam login and make sure the token is valid and not already used by another running server. Then check free disk. Then try one map from the collection with host_workshop_map to separate a collection problem from a download problem.

`ds_workshop_changelevel` says the map was not found. The name is wrong. Run ds_workshop_listmaps and copy the exact name; names are case-sensitive and often carry suffixes.

`changelevel de_mymap` fails for a Workshop map. changelevel looks for stock maps. Use ds_workshop_changelevel for collection maps or host_workshop_map with the id.

Players are kicked or stuck downloading. The client cannot reach the Workshop item, usually because the item was hidden, removed or made private by its author. The server may still have a cached copy, which is why it loads for you and not for them. Replace the map.

The map updated and now spawns or bombsites are broken. The author's update. Remove the item from the collection, change map, and wait for a fix. If you need that exact version, there is no supported way to pin an old Workshop revision; keep a note of maps that have bitten you before.

Plugins crash on a Workshop map but not on stock maps. Some plugins read map-specific config files by name and do not expect the folder structure Workshop maps use. Check the plugin's documentation for how it names Workshop maps, and look in its log for the map name it actually saw.

FAQ#

Do players need to subscribe to my workshop maps?

No. The CS2 client downloads the map from the Workshop when it connects to a server running it. Subscribing in advance only saves them the download wait on first join, which is worth suggesting for large maps.

Can I upload a map file to the server instead of using the Workshop?

For CS2, the Workshop is the supported route. Loose map files for Source 2 are not loaded the way CS:GO's .bsp files were, and anything that works by copying files around tends to break on the next update. Publish the map to the Workshop, even as unlisted for testing, and load it by id.

How many workshop maps can a server run?

There is no small fixed limit, but disk and download time set a practical one. Ten to fifteen maps keeps the first boot short and the map vote meaningful. Past thirty, most maps are never picked and every restart after an author update is slower.

Why did a map change without me touching anything?

Its author published an update and the server fetched it when the map next loaded. Workshop maps always track the latest version; if a particular map keeps changing under you, replace it with a better-maintained one.

Does a workshop map need a different game mode?

Often, yes. Surf, KZ, aim and arena maps expect custom or casual rules and frequently a plugin. Load the map with the matching game_alias - usually custom or casual - and the plugin the map was built for, or players will find a defuse round timer running on a surf map.