Circus: A Process & Socket Manager


Starting at 0.7, Circus does not include the web console anymore. It’s now located in a standalone package called circus-web.


Circus is a process & socket manager. It can be used to monitor and control processes and sockets.

Circus can be driven via a command-line interface or programmatically through its python API.

It shares some of the goals of Supervisord, BluePill and Daemontools. If you are curious about what Circus brings compared to other projects, read Why should I use Circus instead of X ?.

Circus is designed using ZeroMQ. See Design for more details.


By default Circus doesn’t secure its messages when sending information through ZeroMQ. Before running Circus, make sure you read the Security page.

To install it, check out Installing Circus

Running Circus

Circus provides a command-line script call circusd that can be used to manage one or more watchers. Each watcher can have one or more running processes.

Circus’ command-line tool is configurable using an ini-style configuration file. Here is a minimal example:

check_delay = 5
endpoint = tcp://

cmd = python
args = -u $WID
warmup_delay = 0
numprocesses = 5

cmd = another_program
numprocesses = 2

The file is then run using circusd:

$ circusd example.ini


If you use Circus with zc.buildout, and some of your commands are scripts generated by zc.buildout, you will need to use the copy_env and copy_path options in your watchers.

Besides processes, Circus can also bind sockets. Since every process managed by Circus is a child of the main Circus daemon, that means any program that’s controlled by Circus can use those sockets.

Running a socket is as simple as adding a socket section in the config file:

host = localhost
port = 8080

To learn more about sockets, see Circus Sockets.

To understand why it’s a killer feature, read Circus stack v.s. Classical stack.

Controlling Circus

Circus provides two command-line tools to manage your running daemon:

  • circusctl, a management console you can use it to perform actions such as adding or removing workers
  • circus-top, a top-like console you can use to display the memory and cpu usage of your running Circus.

To learn more about these, see Command-line tools

Circus also offers a small web application that can connect to a running Circus daemon and let you monitor and interact with it.

Running the web application is as simple as adding an httpd option in the ini file:

httpd = True

Or if you want, you can run it as a standalone process with:

$ circushttpd

By default, circushttpd runs on the 8080 port.

To learn more about this feature, see The Web Console

Developing with Circus

Circus provides high-level classes and functions that will let you manage processes in your own applications.

For example, if you want to run four processes forever, you could write:

myprogram = {
    "cmd": "python",
    "args": "-u $(WID)",
    "numprocesses": 3,

from circus import get_arbiter

arbiter = get_arbiter([myprogram])

This snippet will run four instances of myprogram and watch them for you, restarting them if they die unexpectedly.

To learn more about this, see Circus Library

Extending Circus

It’s easy to extend Circus to create a more complex system, by listening to all the circusd events via its pub/sub channel, and driving it via commands.

That’s how the flapping feature works for instance: it listens to all the processes dying, measures how often it happens, and stops the incriminated watchers after too many restarts attempts.

Circus comes with a plugin system to help you write such extensions, and a few built-in plugins you can reuse. See Plugins.

You can also have a more subtile startup and shutdown behavior by using the hooks system that will let you run arbitrary code before and after some processes are started or stopped. See Hooks.

More documentation

Contributions and Feedback

More on contribution: Contributing to Circus.

Useful Links: