Circus: A Process & Socket Manager


Circus is a Python program which can be used to monitor and control processes and sockets.

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

To install it and try its features check out the Step-by-step tutorial, or read the rest of this page for a quick introduction.

Running a Circus Daemon

Circus provides a command-line script call circusd that can be used to manage processes organized in one or more watchers.

Circus’ command-line tool is configurable using an ini-style configuration file.

Here’s a very minimal example:

cmd = python
numprocesses = 5

cmd = another_program
numprocesses = 2

The file is then passed to circusd:

$ circusd example.ini

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 Working with sockets.

To understand why it’s a killer feature, read How does Circus stack compare to a classical stack?.

Controlling Circus

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

  • circusctl, a management console you can use 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 CLI tools

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

To learn more about this feature, see The Web Console

What now ?

If you are a developer and want to leverage Circus in your own project, write plugins or hooks, go to Circus for developers.

If you are an ops and want to manage your processes using Circus, go to Circus for Ops.

Contributions and Feedback

More on contributing: Contributing to Circus.

Useful Links: