screeps/screeps: running the Screeps MMO world on your own hardware

What the screeps/screeps package actually is

Screeps is an MMO RTS sandbox in which the core mechanic is programming your units' AI. You control a colony by writing JavaScript that runs continuously in a single persistent world shared with other players. The official world lives at screeps.com. This repository is the other half of that sentence: a distributed, standalone game server you launch on a local computer or a dedicated server on the Internet.

The audience is narrow and specific. It is for players who want a private world, for groups who want to run a shard without depending on the official host, and for developers who need the game engine available locally for automated testing. It is not a client. There is no browser UI shipped here and no account system. The README states plainly that the server has no user authentication mechanism of its own and that Steam is employed for that purpose, in two parallel modes: native authentication through a local Steam client, which works automatically when launched via Steam, and a Steam Web API key for machines without a Steam client.

That single design decision shapes everything else. You cannot hand out accounts the way you would with a typical self-hosted web application. Whoever wants to play needs to authenticate through Steam, and the server needs either the local client or an API key to verify them.

Six processes, one launcher, and a Pub/Sub bus in the middle

The server is not a monolith. The README describes it as multiple parallel processes linked to each other, with a separate launcher process to start them correctly. The modules are published as separate npm packages and each has its own repository. The package.json pins them explicitly: @screeps/backend 3.3.0, @screeps/common 2.16.0, @screeps/driver 5.3.0, @screeps/engine 4.3.0, @screeps/launcher 4.2.0, @screeps/storage 5.1.3, plus @screeps/pathfinding 0.4.17.

The division of labour is documented and worth reading before you deploy anything. The launcher starts the other processes and includes the server control GUI. The storage module holds a LokiJS-based database, a key-value store and a Pub/Sub mechanism, and the rest of the processes connect to it to exchange data. The backend is an HTTP server for clients plus a CLI server for administration. The engine is the game core that executes game scripts and interacts with world objects. The driver is the link between the environment-independent engine and the host environment.

That last point is the most interesting architectural claim in the README. The engine module is shared between the official server, the standalone server and an in-browser simulation. The driver exists because the engine is environment-independent, and the README says you can replace the driver with your own module if you want a different method of storing and handling data. The practical consequence is that the game logic is not something you fork to change storage. You swap the driver. The default driver is what couples this stack to LokiJS and to a single db.json file.

Because the processes talk through storage rather than directly, you can launch them your own way. The README points at launcher/lib/start.js for the list of environment variables each process needs, and names upstart, systemd and distribution across different machines as legitimate options. That is a real deployment path, not a hypothetical one, but it means you own the orchestration.

Installing screeps/screeps and starting a first world

The README gives the console launcher as the command-line route. The prerequisites it lists are Node.js 22 LTS or higher, plus Python 3 and build tools per the node-gyp requirements. The package.json is stricter than the README prose: engines requires node >=22.9.0 and npm >=10.8.2. Trust the package.json when you provision a machine.

Install the package globally or locally, then run init, then start:

npm install screeps
npx screeps init
npx screeps start

The README notes that you will be prompted for your Steam Web API key during this flow, and that you can obtain one from the Steam developer page. That prompt is the gate between you and a running world. If you are launching on a machine without a Steam client, the key is not optional.

The stock launcher reads a file named .screepsrc in the current directory for launch configuration, and the same options can be passed on the command line. Running npx screeps start --help prints the full list. The defaults that matter most are the listen port, 21025, the host, 0.0.0.0, and the CLI port, which defaults to port+1:

npx screeps start --port 21025 --host 0.0.0.0 --cli_host 127.0.0.1 --runners_cnt 2 --processors_cnt 2

Two of those flags deserve attention. The README warns that runners_cnt and processors_cnt should not be set greater than the number of physical CPU cores, and both default to 2. The CLI host defaults to 127.0.0.1 while the game server defaults to 0.0.0.0, which is a sensible split: the administrative interface stays local unless you deliberately move it.

To connect, the README says to use the Steam game client, click "Change server", and enter your server credentials. There is also a --password option for a server password presented on user sign-in, empty by default. Note that this is a server-level password, not per-user authentication. The README does not describe a browser client, so the Steam client is the documented way in.

LokiJS in one file, and what that costs you

The default built-in storage is based on LokiJS and stores all data in db.json. The README is candid that this choice exists to allow embedding in pure JavaScript environments like the Steam game client. That is the reason, and it is a good one for the Steam build. For a server holding a persistent world that runs 24/7 with multiple players, it is the weakest part of the default configuration.

The README acknowledges this directly: you can manually replace the storage engine with another community solution to improve performance, and it links a step-by-step guide for installing a standalone private server on Ubuntu using MongoDB and Redis as storage. That guide is external, on docs.screeps.com, and the repository does not vendor it. So the upgrade path out of LokiJS is documented as a pointer, not as a supported configuration you can read in this codebase.

This is where I would push back on the default. A single JSON file holding an entire persistent world is convenient for a laptop and awkward for anything else. It also makes backup and restore a file-copy operation, which is simple, but it makes concurrent access and growth a question the README does not answer. If your plan is a long-running shard with several players, plan the storage decision before you populate the world, not after.

Where screeps/screeps is the wrong tool

The clearest limitation is authentication. If you want to run a private world for people who do not have Steam accounts, or you want to integrate with an existing identity provider, this server does not offer that. The README states there is no user authentication mechanism of its own. Steam is not a plugin here; it is the mechanism.

The second limitation is versioning. The repository's most recent release listed is v3.4.0 from 2019-05-03, while package.json declares version 4.3.0 and pins module versions in the 2.x to 5.x range. The last push to the repository was on 2026-04-01. That combination tells you the release tags and the published package version have drifted apart. If you depend on tagged releases for reproducibility, you will be pinning module versions by hand from package.json rather than following release notes.

The third is operational. The README does not document rollback, does not describe schema migration between versions, and does not describe what happens to db.json when a module is upgraded. Because the storage format is owned by @screeps/storage, upgrading that dependency is not a neutral act. Nothing in the repository says otherwise, and the absence is worth treating as a real gap rather than an oversight in the README.

Finally, this is not a way to play Screeps for free in the sense of getting the official world's content. It is a server for your own world. The official MMO at screeps.com is a separate thing that this project does not replace.

The alternative: the official hosted world

The genuine alternative is not another self-hosted server. It is playing on the official world at screeps.com, which the README links as the game itself. The difference in approach is who runs the persistence layer and who handles identity. On the official world, you write JavaScript and it runs; you do not provision Node.js, you do not obtain a Steam Web API key, you do not choose between LokiJS and MongoDB plus Redis, and you do not tune runners_cnt against your core count. You also do not get a private shard, and you do not get the engine running on your own machine for automated tests.

That is the real trade. This repository buys you control over the world and the ability to run the engine locally. It costs you every operational decision that the hosted service makes for you. The README's own framing supports this: it says the engine module is shared between the official and standalone servers, so the game rules are the same. What differs is everything around the rules.

If your reason for self-hosting is cost, note that the README does not present this project as a cheaper way to play. It presents it as a way to launch your own game world. Those are different motivations and they lead to different deployment choices.

Licence, maintenance and what an upgrade actually involves

The licence is ISC, declared in both the repository metadata and package.json. ISC is a permissive licence in the same family as MIT: it permits use, modification and redistribution with the licence text retained. This is not legal advice, and the ISC text in LICENSE.txt is what governs. One thing worth checking yourself: the dependencies are separate packages with their own licences, so the licence of the top-level screeps package does not automatically describe everything in node_modules.

On maintenance, the facts are the last push on 2026-04-01 and a most recent listed release of v3.4.0 from 2019-05-03. The repository is not archived. Beyond that, the README does not describe a support policy, a compatibility guarantee, or a deprecation schedule for the module versions pinned in package.json.

The practical upgrade cost follows from the architecture. There is no single version number that describes your deployment. You have the top-level package at 4.3.0 and six pinned module versions underneath it, and the storage module owns the on-disk format. Upgrading means deciding, per module, whether the change is safe for the world you are running. The README gives you no procedure for that. If you run this for anything you care about, snapshot db.json before you touch dependency versions, and read launcher/lib/start.js when you move processes onto systemd or upstart so the environment variables stay correct.

Editorial conclusion

Adopt screeps/screeps if you want a private Screeps world for a small group and you already have a Steam Web API key, or if you need to run the same engine the official server uses for automated testing. Do not adopt it if you need built-in account management, a documented upgrade path, or a project with a release cadence: the last push was on 2026-04-01, the most recent release is v3.4.0 from 2019-05-03, and the README does not document rollback or migration between versions. Verify first that Node.js is at 22.9.0 or higher, that your build toolchain satisfies the node-gyp requirements, and that LokiJS in a single db.json file can hold the world you intend to run.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. README
4. Releases
5. screeps/screeps on GitHub