Skip to content
Kickoutchi
installdocschangeloggithub
Documentation menu

Safety

How Kickoutchi avoids killing the wrong thing • confirmations, guardrails, scoped checks, and last-moment re-checks.

Terminating the wrong process is the scary part of a tool like this. Kickoutchi treats it that way. Every guarantee below is real behaviour, not a promise on a marketing page.

Confirmations

Nothing is terminated without a confirmation step, and the prompt scales with the risk:

  • Normal kill • type y.
  • Force kill • type the word force (unless you set confirm_force_kill = false).
  • Tree kill • type tree for normal scoped termination, or force for force tree kill.
  • Group kill • type group for normal scoped termination, or force for force group kill.
  • Protected process • type the PID or the process name.

Before any prompt, Kickoutchi prints the target’s identity, the affected ports, the equivalent shell command, and any warnings.

Hard guardrails

  • PID 0, PID 1, Kickoutchi’s own PID, and Windows PID 4 are blocked outright • they can’t be targeted at all.
  • kill --port refuses ambiguous ports. If two PIDs own the same port, Kickoutchi lists the candidates and makes you choose with --pid instead of guessing.
  • A port with no readable owner is not killable • it exits 4 (permission denied) rather than acting on incomplete information.
  • Scoped kills are bounded. Over-cap or non-converging trees/groups refuse instead of partially killing a moving target.

Protected processes

Some processes are load-bearing: init, your database, Docker, core OS services. These are marked protected and require typing the PID or name to confirm • force or --yes can’t shortcut it. The built-in list includes Docker owners such as dockerd, docker-proxy, and com.docker.backend, and it is extensible via config.

Human-facing output also sanitizes OS-provided names, paths, and status text before rendering them, including control bytes, ANSI escapes, bidi controls, and zero-width display controls.

The target can’t wander off

This is the important one. After you confirm, Kickoutchi re-validates the target right before it signals:

  • It re-collects ports and checks the confirmed target still matches.
  • If the port’s owner changed, it aborts • no termination is sent.
  • If the owner became unreadable, it aborts as ownership-unavailable (exit 4).
  • If the target became protected in the meantime, it aborts (exit 6).

For normal process scope, only the confirmed PID is ever signalled. For tree/group scope, only the explicitly confirmed scope is signalled, after a fresh scan and verification.

Scoped-kill safety on Linux/macOS

Tree and group kill are ogre-sized controls: broader than one PID, so they use a stricter pipeline:

  • They are opt-in: --tree, --group, or TUI t/T for tree scope.
  • They count before signalling; cap refusals happen with zero side effects.
  • They freeze the root first, then sweep members to a fixed point.
  • They verify every stopped member’s identity where PID reuse is impossible.
  • They thaw everything on any refusal, permission problem, identity drift, protected descendant, or partial metadata.
  • Group termination queues every SIGTERM before any SIGCONT, so parent-like members cannot wake up early and spawn survivors.

Read the full flow in Scoped kills.

Scoped-kill safety on Windows

Windows tree kill uses Job Object containment rather than a freeze-first signal pipeline:

  • It preflights the confirmed root and observed tree before any Job Object assignment.
  • It refuses before commit for unsafe PIDs, protected descendants, incomplete metadata, identity drift, or an over-cap tree.
  • It treats assigning the root to the Job Object as the irreversible commit boundary.
  • It terminates contained members with hard termination and reports partial containment, fallback-terminated, and not-terminated members honestly.
  • It fails closed when missing creation-time metadata could hide a descendant inside the confirmed tree.

Platform specifics

Platform How termination stays honest
Linux Uses pidfd on kernel 5.3+ for delivery. Tree/group kill opens pidfds before SIGSTOP, then reuses them for thaw/final signals.
macOS No pidfd, so tree/group kill uses stop-verify: once a process is stopped, its verified PID cannot be recycled before the signal lands.
Windows Uses process handles for precise single-PID termination and Job Objects for CLI tree kill. inspect is available; --group and TUI t/T are not.

After the kick

On a successful termination, Kickoutchi does a best-effort re-collection and tells you whether the confirmed ports are actually gone • instead of just assuming success and leaving you to check.

See the exit codes for how each of these outcomes is reported to scripts.