Self-hosted service
ochinchina/supervisord avatar
ochinchina/supervisord

This supervisord is a single static binary with leftover test tags

a go-lang supervisor implementation

4,287 stars627 forksGoMIT

At a glance

What is it?
supervisord is a Go reimplementation of the Python process supervisor, aimed at containers where a Python runtime is dead weight. The build is one static binary. The management interface is XML-RPC over HTTP, which is why the client subcommand and the daemon have to find each other, and why that client cannot use a Unix socket. Two details in the repository are worth noticing: the build instructions ask for a Go version the module file does not require, and two test-suffixed versions sit among the release tags.
Who is it for?
This implementation fits someone moving a Python supervisor configuration into a container image where the runtime is the thing they are trying to remove, and who needs to keep the same configuration file format. It does not fit someone who wants the Python supervisor's own capabilities, since this is a reimplementation with its own subset, and it does not fit an air-gapped registry that cannot reach the upstream module proxy.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 23 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ochinchina/supervisord4,287 ★ · +16
Star history
Repository2026-09-232026-11-15
ochinchina/supervisord4.3k4.3k

16 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The stated reason is that Python is too big for a container

The page opens with a reason and a preference, in that order.

The Python supervisor is a powerful tool used by a lot of people to manage processes, and the author says they like it too.

Then the actual argument. That tool requires a large Python environment on the target system, and in some situations, for example in a container, the Python is too big.

Everything else follows from that one constraint. Reimplementing it in Go means a compiled binary rather than a runtime plus packages, which means a container image with one file in it, which means no interpreter to pin and no dependency tree to audit.

So the project is not trying to be a better supervisor. It is trying to be the same supervisor without the interpreter, and the compatibility work is all in service of that.

The daemon mode with a web interface is a second-order feature of the same goal: if you are running a process supervisor in a container, you need a way to signal it, and the Python tool's answer was XML-RPC over HTTP, so this one answers the same way.

The config file is found in six places, two of them relative to the binary

The autodetection order is a list of six paths, and the last two are the interesting ones.

The first four are absolute or working-directory relative: the config in the current directory, the config in an etc subdirectory of it, the config in the system etc directory, and the config in a supervisor subdirectory of the system etc directory, the last of which is noted as existing since a particular version of the original tool.

Then two paths relative to the executable rather than to you.

code
5. ../etc/supervisord.conf (Relative to the executable)
6. ../supervisord.conf (Relative to the executable)

That pair is what makes the binary portable in a way the original is not. A container image can carry its own config directory next to the binary and it will be found no matter what the working directory happens to be, which is the part that container entrypoints get wrong routinely.

The cost is that you can end up running a configuration you did not intend to edit, because the search is a fallback chain. Passing the config path explicitly with the flag is the unambiguous form, and the page gives it first.

The client subcommand cannot use a Unix socket

The control interface is HTTP with XML-RPC, and the page is precise about what that means.

The server can listen on a Unix domain socket or on TCP, and basic auth is optional. The configuration section differs for each.

Then the caveat, which is about the client rather than the server: the control subcommand works correctly only if the HTTP server is enabled and the server URL is set correctly, and a Unix domain socket is not currently supported for this purpose.

So the socket option is server-only. You can run a server that listens on a socket, and you cannot manage it with the bundled client.

The server URL is itself resolved by a four-step fallback: a command-line option if present, then a value in the control section of a config passed with the config flag, then a value in the control section of whatever config was autodetected, and finally a hardcoded default pointing at localhost on the daemon's port.

That last step is a footgun worth naming. With no config found and no option given, the client will try localhost on the daemon's port, which is right if you bound the server there and wrong everywhere else.

One documented option is literally two question marks

The supervised-program options are a long list, and it is the most useful reference on the page.

The command can be a full path or resolved through the environment path, with its arguments in the same string. The number of processes has a companion option, numprocs_start, whose description is only two question marks. Autostart defaults to true. Start seconds is the window a program has to stay up before the supervisor counts the start as successful, and zero removes the requirement. Start retries is how many serial attempts are allowed before the program is put into a terminal failure state.

Then the pair people usually need.

The entry for the starting process count is `numprocs_start`, and its description is two question marks.

Two question marks where a description should be.

The rest of the list is solid and covers the exit codes that count as expected for automatic restart, the stop signal, the wait before a forced kill, and standard input.

Stop signals are sent one by one, then a kill follows

The stop sequence is described in enough detail to be worth quoting, because the ordering is the whole behaviour.

A stop signal is the signal sent to a command to stop it gracefully.

If more than one stop signal is configured, the signals are sent to the program one by one with an interval equal to the stop-wait setting. If the program does not exit after all of them have been sent, the supervisor kills it.

So the multi-signal form is not a broadcast. It is a ladder: a gentle signal, then whatever you listed next, and only after the last one has had its full wait does an ungraceful kill happen.

That is the right design for a supervisor, because a process that needs different treatment on different shutdown paths can be given a sequence rather than a choice. And it is the reason the wait setting is documented as the amount of time before the forced kill, since it is the interval of every rung of the ladder, not just the last one.

The exit codes list interacts with this. Automatic restart uses it to decide which exits are expected, so a program killed by the supervisor's own stop request is distinguished from one that died on its own.

The build page asks for an older Go than the module requires

Two files state a Go version and they do not agree.

The build section says to make sure a particular older release is installed in your environment before compiling.

The module file says something several releases newer.

code
go 1.27.3

The build instructions have not caught up with the module. That is a small thing in isolation, but it points at a build process that has not been revisited, which matters more for the two target platforms described on the page.

The Linux build is a generated step followed by a fully static link with external link mode and a binary called `supervisord`. The Windows build is two commands on a Windows machine, one of which tidies the module and the other of which builds without the static flags, producing `supervisord.exe`.

So the two platforms do not get the same treatment: Linux is built to have no dynamic dependencies at all, and Windows is built normally. That is a reasonable split given what each platform's linker does, and it is also why the Linux recipe needs the external link mode flags at all.

The container image copies one file onto a scratch base

The container recipe is the shortest possible expression of the project's argument.

It starts from a Go toolchain image, copies the source in, and builds with one command: cgo disabled, the release tag set, symbols stripped, and the result written to a path in the binary's own location.

Then the final stage is a base with nothing in it.

dockerfile
FROM scratch

COPY --from=builder /usr/local/bin/supervisord /usr/local/bin/supervisord

ENTRYPOINT ["/usr/local/bin/supervisord"]

A scratch base is an empty filesystem with no shell and no distribution. There is no package manager, no libc and no configuration directory, so there is nothing to audit and nothing to patch.

There is also nothing to run except the supervisor, and nothing to write to unless you mount something. A configuration file in the image has to be baked in at build time or mounted at run time, which is exactly what the executable-relative search path in the configuration autodetection supports.

One thing the image does not do is set a config path. The entrypoint takes no arguments, so the config has to arrive by one of the six search paths or by an argument your orchestrator adds.

A test-suffixed tag sits among the release tags

The release list has three entries and two of them do not look like releases.

The newest is an ordinary patch version, v0.7.6, published on 2026-09-26. The other two are v0.0.3-test, published three minutes before it, and v0.0.2-test, eleven days earlier.

So the most recent releases are one patch tag and two test-suffixed tags.

That is a small signal about the release process.

If you are pinning a version, the tags with the test suffix are the ones to look at twice.

Editorial conclusion

This implementation fits someone moving a Python supervisor configuration into a container image where the runtime is the thing they are trying to remove, and who needs to keep the same configuration file format. It does not fit someone who wants the Python supervisor's own capabilities, since this is a reimplementation with its own subset, and it does not fit an air-gapped registry that cannot reach the upstream module proxy. Before you adopt it, check four things. Which configuration options you actually rely on, because the page documents a subset and one of the entries is literally two question marks. Which Go version you build with, since the page and the module file disagree. Whether you need a Unix socket for the control interface, because that combination is explicitly unsupported for the client subcommand. And whether the release you pick is a real release, because two test-suffixed tags are currently in the list.

Frequently asked questions

What is this supervisord used for?

It manages processes the way the Python supervisor does, by reading a configuration file of program definitions, starting them, restarting them when they die unexpectedly, and reporting status. The stated motivation for this Go implementation is that the Python tool requires a large Python environment on the target system, which is a problem in a container image.

How do I install this Go supervisord?

Compile it. For Linux there is a generation step followed by a build with the release tag set and fully static linking. For Windows, run the commands on a Windows machine, one of which tidies the module first. A container image can also be built from the recipe in the repository, which compiles to a static binary and copies it onto an empty base filesystem.

How do I manage a running supervisord?

Enable an HTTP server in the configuration, add a server URL, and use the control subcommand, whose available operations are status, start, stop, shutdown, reload, add, remove, update, clear and reread. That client path works over HTTP only; a Unix domain socket is supported by the server but not by the control subcommand.

Official sources

  1. Issues
  2. License: MIT
  3. ochinchina/supervisord on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ochinchina-supervisord.svg)](https://hysenlabs.com/projects/ochinchina-supervisord)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ochinchina-supervisord.svg)](https://hysenlabs.com/projects/ochinchina-supervisord)

Was this useful?