Running it as a service

An available native Linux package registers the service for you and starts it. The current release target is Linux x64 only; check asset availability before installation. Windows and macOS entries below describe separately built, validated reference deployments. They do not mean a native package is currently published for those platforms.

This page is for checking on it, and for the cases where you are managing the service yourself.

What you get

Platform	What is registered
Windows reference build with its wrapper included	A Windows Service in services.msc; without the wrapper, see the fallback below
macOS reference build	A LaunchDaemon under /Library/LaunchDaemons, with KeepAlive
Linux	A systemd unit running as an unprivileged plugboard account, with Restart=always and the filesystem locked to its own directory

These service registrations start at boot with nobody logged in when the corresponding launcher and service integration have been installed.

Checking on it

The status panel at localhost:9090 shows whether it is running, and has a Start button when it is not. That is the usual entry point for an installed native/reference launcher.

From a terminal, in the install directory:

plugboard service-status     # ask the platform how it is doing
plugboard install-service    # register it, if you are doing this by hand
plugboard uninstall-service  # remove the registration; your data is untouched

Uninstalling the service does not remove the application or its database. It removes the registration.

On Linux and macOS these need sudo. On Windows they need an elevated prompt.

Logs

Platform	Where
Windows reference launcher	logs/ in the install directory
macOS reference launcher	logs/ in the install directory
Linux	journald: journalctl -u plugboard -f

The status panel can show you the recent log without you going to find it.

Binding to port 443

The service is registered with what it needs to bind a privileged port.

If you changed the account it runs as on Linux, reinstall the service so that is re-applied. On Windows, check nothing else already has 443. IIS is the usual culprit on a fresh Windows Server.

To move the HTTPS listener elsewhere, set HTTPS_PORT.

The Windows service wrapper

A Windows Service has to talk to the Service Control Manager, and a plain Node process cannot. Pointing sc create at node.exe produces the well-known “error 1053: the service did not respond to the start request in time”.

The reference Windows packaging can include a service wrapper. Confirm that your separately supplied build contains it before expecting a service entry; Windows is not enabled in the current native release matrix.

If the wrapper is ever missing, registering the service falls back to a Scheduled Task that runs at system startup as LocalSystem. It survives reboots and runs with nobody logged in, but it appears in Task Scheduler instead of services.msc. Restoring the wrapper and re-registering the service upgrades it back.

Troubleshooting

Symptom	Cause
“Administrator rights are required”	Use an elevated prompt, or sudo
Starts then stops	Check the log. Usually a port already in use, or a certificate path that does not exist
“HTTPS not started”	The certificate path is wrong, or the PFX password is. The log names the file it tried
Cannot bind 443	On Linux, reinstall the service after changing the account. On Windows, something else has the port
Works by hand but not as a service	Usually a path. The service runs as a different account, so relative paths and per-user certificate stores behave differently