Skip to content
A First Look At Muru

A First Look At Muru

grahamdumpleton.me • November 22, 2026

In my last post I talked where Muru came from and what I want it to be, but didn't show it doing anything. Time to fix that.

Muru has three ways of running an application. There is a development mode for when you are working on an application on your own machine, a daemon for hosting applications on a server, and a mode for running an application in a container. The same process model sits underneath all three, so what you see while developing is what you get in production. That makes development mode a good place to start, since it is the simplest of the three and still shows off some of what makes Muru different.

Muru comes as two pieces. The muructl command is what you install and interact with. It is a single binary written in Rust, with no Python dependencies of its own. The second piece is muru , a runtime library which runs inside your application's Python interpreter. You don't install that one yourself. The first time muructl runs an application on a particular Python version, it fetches the matching runtime library into your user cache directory. Nothing gets installed into your project.

The easiest way to install muructl is as a tool with uv :

Using pipx install muructl , or pip install muructl into some environment, works just as well. Muru is still in alpha, with only pre-releases available, and supports Linux and macOS on CPython 3.11 or later, including the free-threaded builds.

For a project to try it with, create a directory with a virtual environment:

Not wanting to complicate things by bringing a web framework into it just yet, we will start with a plain WSGI application. Save this as app.py :

To run it, give muructl run the module and the name of the WSGI callable within it:

There is no need to activate the virtual environment first, as muructl will find the .venv directory in the project by itself. Running this the output is:

Even with an application this small, there is more going on than you might expect. A host process was started which imported the application once. A worker process was then forked from the host, meaning that it starts out as a copy of the host with the application already loaded. Finally, the edge, which is the part of Muru that accepts HTTP connections, started listening for requests, passing them through to the worker.

Importing the application once and forking workers from it isn't a new idea, but doing it safely is harder than it looks. If importing the application opens a database connection or starts a background thread, that doesn't survive being forked, and what you get are mysterious problems later on. Muru checks for this when it does the import, before any workers are forked. How that check works deserves a post of its own, so I will come back to it.

Note too that development mode only listens on the loopback interface. It is not meant to be exposed to the outside world, which is what the daemon is for.

What the access log tells you

Open in a browser, or use curl , and a line is added to the terminal for the request:

Much of this is what you would expect from any access log, with the status, the method and path, the size of the response, and the total time. The parts which are a bit different are queue and app . The first is how long the request waited for a worker thread to become free to handle it, and the second is how long your code took.

On a laptop with one user these are tiny numbers and not very interesting. In production they are anything but. A request that takes a long time because your code is slow, and one that takes a long time because every thread was busy and it had to wait its turn, are very different problems. The first means you have code to fix, the second means you don't have enough capacity. If you can't tell the two apart, you will often end up fixing the wrong thing. Being able to see that distinction, right down to individual requests, is a small example of what I meant in the last post Muru knowing what Python web applications need.

The line also says which worker handled the request, and gives the request a unique id. The same id is returned to the client in an X-Request-ID response header, so a response can be matched up to the log line for it. Anything the application prints is likewise

When the application fails

Applications have bugs, so let's add one. Change app.py to:

Make a request and, because this is development mode, the error page sent back includes the traceback:

The same traceback appears in the terminal,

If the client says it wants JSON, as an API client would, it instead gets back an application/problem+json response with the same details:

Either way, the worker itself is fine. An exception raised by your code results in a failed request, but never a dead process.

Reloading is a release

You may have noticed that I didn't restart anything after changing app.py . That is because development mode watches the project directory, and when a .py file changes it reloads automatically. This is on by default.

Reloading on code changes is something every development server does, so on its own it isn't remarkable. What is different is how Muru does it. Rather than restarting the worker in place, a reload starts a whole new host and worker beside the existing ones. Only once the new worker is ready is traffic switched across to it, after which the old one is shut down. The terminal shows it happening:

Each set of host and workers is a release, numbered as they are created. Where this gets interesting is when the change you make breaks things badly enough that the application can't even be imported. Add import nosuchmodule to the top of app.py and save it:

The new release failed to start, so traffic never moved to it, and the release carried on serving requests the whole time. Fix the code and save again, and the release starts and takes over. The failed attempt still counts as a release, so this will be r4 .

In development mode this mostly saves you from staring at a dead server after a typo. The reason I find it worth dwelling on is that it is exactly the same mechanism the daemon uses when deploying a new version of an application to a server. There, a new release starts beside the old one, traffic moves across once it is ready, and if it never becomes ready the old release just keeps serving. That is the basis of zero-downtime deploys in Muru, and of things like blue/green deploys, canaries and rolling back to a release. Development mode is giving you a small taste of that every time you save a file.

Nothing this is specific to hand-written WSGI applications. For a Flask application you point muructl run at the Flask application object:

and for Django at the WSGI application it already generates for you:

Neither framework needs to know anything Muru.

That covers the basics of running an application in development mode. Rather than walk through every option, the posts which follow will concentrate on the places where Muru does things differently to the other ways of hosting a Python web application, still in development mode for now, before moving on to the daemon.

The full story

This article is one source in a clustered incident — the cluster page carries the summary, timeline and every other outlet covering it.

Extracted Entities