Supervisor Operations

Supervision model

supervisor uses only cross-platform POSIX primitives, identical behavior on Linux and macOS, no pgrep/pkill.

• Launch: services are started detached (setsid, their own process group); stdin/stdout/stderr are redirected to the log file or /dev/null so a service never holds the launcher’s terminal/pipes open. initenv: true runs through a login shell via exec "$@" (so config values are never interpolated into a shell string, no injection).
• Honest start: after launch, a short grace check confirms the process did not immediately exit before reporting success.
• PID file: <piddir>/<service>.pid records the launched PID.
• Liveness / status: a ps scan matches the binary as argv[0] (the executable, not any mention of the path), which also catches externally started or duplicate instances; the PID file is validated against it (so a stale PID reused by another program is correctly seen as down, safe across reboots). signal(0) is the fallback when ps is unavailable.
• Duplicate guard: start is a no-op if the service is already running.
• Stop: signals the process group (kill -- -<pgid>, or sudo kill for root-owned services), polls until the process is actually gone, and escalates SIGTERM → SIGKILL at half the stoptimeout. The PID file is removed only once the service is confirmed down.

Boot persistence

There are two complementary mechanisms:

1. The supervisor daemon (install-daemon): the OS starts supervisor at boot, and it reconciles every configured service up. One moving part, cross-platform; restart latency ≈ the poll interval.
2. Per-service OS units (install-service): the OS supervises a specific service directly (kisai-<name>.service / com.kisai.<name>), restarting it instantly on failure, independent of the supervisor daemon.

Service types

Set type: on a service entry (default generic).

services:
  # generic: any kis.ai .svc binary (the default; registry services use this)
  iam:
    state: up

  # kong: managed via `kong health|start|stop` (requires sudo)
  edge:
    type: kong
    state: up

  # openvpn: brings a tunnel interface up/down (Linux-oriented)
  vpn:
    type: openvpn
    state: up
    interface: tun0
    args: ["--config", "/etc/openvpn/client.ovpn"]

  # podman: manages named containers for a user
  workloads:
    type: podman
    state: up
    user: workspaceuser
    containers:
      - name: my-container
        options:
          memory: 4gb

Note: the generic type is fully cross-platform. kong, openvpn and podman are integrations with that software and are Linux-oriented.