Getting started

Getting started

Python 3.11 or newer, four dependencies, no build step, no database. Three ways in, none of them needing sudo.

One line

curl -fsSL https://raw.githubusercontent.com/andreaderuvo/panoptes/master/install.sh | bash
panoptes

It downloads the code to ~/.local/share/panoptes, makes a virtual environment beside it, and writes a launcher at ~/.local/bin/panoptes. Nothing outside your home is touched, no system package is installed, and nothing runs in the background unless you ask with --service.

Run the same line again to update — your configuration is left alone — and … | bash -s -- uninstall takes it out again, keeping the configuration, because a fleet's worth of machines and keys is not the uninstaller's to throw away.

In a container

A board is the one of the two that belongs in a container: no tmux, no filesystem, no terminal, no processes to inspect — it holds one read-only key per machine and asks each one over HTTP. So it needs no host namespaces, no privileged mounts and no matching uid.

git clone https://github.com/andreaderuvo/panoptes && cd panoptes
docker compose up -d
docker compose logs            # the URL with the token is in here

The configuration lives in a volume, so a new image changes nothing about the board. PANOPTES_PORT=8880 docker compose up -d moves the port. This works anywhere Docker does, Windows included — unlike Argus, nothing in it is Unix-specific.

The machines it watches have to be reachable from the container: on the same host, network_mode: host is the simplest answer; across a network, whatever address you would type into a browser works as it is.

By hand

git clone https://github.com/andreaderuvo/panoptes
cd panoptes
pip install -r requirements.txt
python3 -m app.main

The first run writes ~/.config/panoptes/config.yaml with a fresh random token, at mode 600, and prints the URL to open. Add your machines to it and restart.

  panoptes 0.0.1 · 3 machine(s) · accepts announcements

  open    http://127.0.0.1:8070/?token=…
          (panoptes --qr prints a code to photograph)

Useful flags:

--version	what is installed, without starting anything
--config PATH	somewhere other than ~/.config/panoptes/config.yaml: the token, the machines, and the keys they gave you
--listen HOST:PORT	override the config for this run — usually because a port is taken. Default 127.0.0.1:8070
--qr	print the URL as a QR code too, one per address it answers on

To keep it running, a user unit is enough — and loginctl enable-linger so it survives your logging out:

# ~/.config/systemd/user/panoptes.service
[Unit]
Description=Panoptes
[Service]
ExecStart=/usr/bin/python3 -m app.main
WorkingDirectory=%h/panoptes
Restart=on-failure
[Install]
WantedBy=default.target

systemctl --user enable --now panoptes
sudo loginctl enable-linger "$USER"

Seeing it without any machines

There is a demo board that invents six of them, so you can look at the thing before wiring anything up. It is also where every picture in this README comes from — a screenshot of a real board publishes hostnames, ports and session names, and a made-up one stays identical between releases, so a retaken picture shows the change and nothing else.

python3 scripts/demo.py        # a board on 127.0.0.1:8770, six machines that do not exist