Configure HTTPS and Register Octop as a System Service

Run Octop over HTTPS using a self-signed or custom certificate, then register it as a persistent system service via systemd or launchd.

Octop can serve traffic over HTTPS using either an auto-generated self-signed certificate or your own certificate and key. On Linux it registers itself as a systemd unit; on macOS it uses launchd — so it starts automatically on boot and restarts after crashes without any extra tooling.

​

Enable HTTPS

​

Option 1 — Self-signed certificate (quick start)

Pass --ssl to octop run and Octop generates a certificate automatically, saving it under ~/.octop/ssl/:

octop run --ssl

The generated certificate is self-signed, so browsers will show a security warning. This is fine for local development or internal tools where you control every client.

​

Option 2 — Custom certificate

Point Octop at your own certificate and private key:

octop run --ssl \
  --certfile /path/to/cert.pem \
  --keyfile /path/to/key.pem

You can use a certificate issued by Let’s Encrypt, your organisation’s internal CA, or any other trusted authority.

​

Option 3 — Persist TLS settings in config.json

To avoid passing flags on every start, write the TLS configuration into ~/.octop/config.json:

{
  "tls": {
    "enabled": true,
    "cert_file": "/etc/ssl/octop/cert.pem",
    "key_file": "/etc/ssl/octop/key.pem"
  }
}

Octop picks this up automatically on every subsequent start, including when running as a system service.

After updating config.json, restart the server for the TLS change to take effect: octop service restart.

​

Register as a system service

The octop service subcommand manages the platform-native service unit for you — systemd on Linux and launchd on macOS.

On Linux, octop service start defaults to a user-level systemd unit (systemctl --user), which runs under your own account and does not require root. To install a system-wide unit that starts before login, pass --scope system:

sudo octop service start --scope system

Pass --scope user to explicitly use the user unit.

After enabling the service, run octop service status to confirm Octop started cleanly. The output includes the last few log lines, making it the fastest way to catch certificate path errors or port conflicts before you open a browser.