Overseer

Features

What it does

Single FastAPI server, single HTML file. No build step or frontend toolchain required.

📊Live CPU & Memory

CPU% is computed from /proc/<pid>/stat over a 10-second sliding window. RSS and swap are read from /proc/<pid>/status.

▶Process Control

Start, stop, and restart individual processes via the XML-RPC API. Destructive actions require a confirmation click.

☑Bulk Actions

Check multiple rows — shift-click for range selection — then start, stop, or restart all selected processes in parallel.

📋Log Viewer

Opens a modal showing the last 64 KB of stdout or stderr for any process. Uses tailProcessStdoutLog / tailProcessStderrLog via XML-RPC.

⚙Config Inspector

Expand any row to see its [program:] config fetched via getAllConfigInfo — command, working directory, user, log paths, and stop signal.

🔄Reread & Update

Calls reloadConfig and optionally addProcessGroup / removeProcessGroup to apply changes. Reports which groups were added, changed, or removed.

📡Prometheus Metrics

The /metrics endpoint returns per-process gauges in Prometheus text format. See the metrics reference below for the full list.

📱Mobile Friendly

Secondary columns (PID, uptime, CPU, RSS) are hidden on narrow viewports. On mobile, per-row action buttons are replaced with a tap-to-open action menu.

Reference

Prometheus metrics

The /metrics endpoint returns Prometheus text format. All gauges carry a name label in group:process form.

supervisor_process_up

1 if the process state is RUNNING, 0 for all other states.

supervisor_process_cpu_percent

CPU usage in percent, averaged over a 10-second sliding window.

supervisor_process_rss_bytes

Resident set size from /proc/<pid>/status in bytes.

supervisor_process_swap_bytes

VmSwap from /proc/<pid>/status in bytes.

supervisor_process_uptime_seconds

Seconds since the process started. 0 for non-RUNNING processes.

All metrics carry a name="group:process" label. For processes not in a group, name is just the process name.

example · /metrics output

# HELP supervisor_process_up 1 if the process is in RUNNING state, 0 otherwise
# TYPE supervisor_process_up gauge
supervisor_process_up{name="worker:celery",state="RUNNING"} 1
supervisor_process_up{name="beat",state="FATAL"} 0

# HELP supervisor_process_cpu_percent CPU usage of the process in percent
# TYPE supervisor_process_cpu_percent gauge
supervisor_process_cpu_percent{name="worker:celery"} 12.4
supervisor_process_cpu_percent{name="beat"} 0.0

# HELP supervisor_process_rss_bytes Resident set size of the process in bytes
# TYPE supervisor_process_rss_bytes gauge
supervisor_process_rss_bytes{name="worker:celery"} 183500800

Installation

Getting started

Requires Python 3.10+ and uv. supervisord must be running and configured with a Unix socket (see below).

Clone the repository

$ git clone https://github.com/torpedro/overseer
$ cd overseer

Install dependencies with uv

$ uv sync

Start the server

$ python main.py --port 8000 --socket /var/run/supervisor.sock

all options

--socket       /tmp/supervisor.sock   # path to supervisor Unix socket
--port         8000                   # port to listen on
--host         0.0.0.0                # host to bind to
--cpu-interval 1.0                    # CPU sampling interval in seconds

supervisord.conf — enable the Unix socket

[unix_http_server]
file = /var/run/supervisor.sock

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface