Skip to main content

An extendable, modular MUD server.

Project description

An extendable, modular MUD server.

Latest version on PyPI Supported Python versions Latest build via CircleCI Latest code coverage via Codecov

Clockwork is a pure-Python MUD server designed with modularity and ease of development in mind.

Current State

This isn’t a viable MUD server yet. There’s account creation, basic character creation, rooms, talking, and walking around, but that’s about it. There are also no permission controls on admin commands yet, so anyone can do whatever they want (which is good because there is no concept of an admin yet).

So anyway, very under-construction at the moment.


Clockwork uses the MIT license. See the license file for more details.


First, it is highly recommended that you set up a virtualenv to run Clockwork in:

$ cd mymud
$ virtualenv -p python3 --no-site-packages .venv
$ source .venv/bin/activate

Then, Clockwork can be installed through pip:

$ pip install cwmud

Note: If not using virtualenv (you should!), you will need to run this command with elevated privileges (sudo).


Clockwork runs on Python 3.4 and is as yet untested on any later versions. There are currently no plans to support earlier versions.

Clockwork requires a running Redis server and the redis-py bindings package for messages, and bcrypt for password hashing (and bcrypt in turn requires libffi). It also makes use of miniboa-py3, a Python 3 port of miniboa, which is a tiny, asynchronous Telnet server. Our modified copy of miniboa is included in cwmud/libs.

To install the libffi library on Debian/Ubuntu, run:

$ sudo apt-get install libffi-dev

See the Redis Quick Start guide for details on installing and configuring Redis.


All the post-installation configuration settings are stored in cwmud/

Some key settings you’ll probably want to change:

DEFAULT_HOST: The IP to bind the listener to, default is "localhost" (, change to "" to allow external connections.

DEFAULT_PORT: The port to listen for new Telnet connections on, default is 4000.

LOG_PATH: The path for the server log, defaults to "./logs/mud.log" (rotates daily at midnight, which are also settings that can be changed).

DATA_DIR: The path to a folder where local data should be loaded from and saved to (serialized objects, flat text files, etc.), defaults to "./data".

These (and other) options can also be set on a per-run basis using command-line options (see below).


To start the Clockwork server, simply run:

$ python -m cwmud

For a full list of uses and options, see the help output by running:

$ python -m cwmud --help

After booting, the server will be ready to accept Telnet connections on whatever address and port you specified in cwmud/ (default is localhost and port 4000).


Clockwork includes a suite of unit tests in pytest format. To run the test suite you will first need to install pytest and the plugins we use (coverage, flake8, timeout). To install all of the test suite dependencies, run:

$ pip install -r tests/requirements.txt

Note: If not using virtualenv (you should!), you will need to run this command with elevated privileges (sudo).

After pytest is installed, you can run the test suite via our Makefile:

$ make tests

If you don’t have make available (a make.bat file will be in the works for Windows users), you can call pytest directly like so:

$ py.test --flake8 cwmud tests


Please read the style guide for coding conventions and style guidelines before submitting any pull requests or committing changes.

Contact & Support

You can email me questions and comments at You can also find me as Kazan on the Mud Coders Slack group (you can find the sign-up page on the Mud Coders Guild blog).

Project details

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page