Getting Started with Zervox

Zervox is a Rust-based watchdog daemon that monitors your processes, detects crashes, runs AI-powered root cause analysis, and auto-fixes dependency issues.

Installation

Install from source 
$ git clone https://github.com/ziuus/Zervox
$ cd Zervox
$ cargo install --path .
Quick install script 
$ curl -fsSL https://raw.githubusercontent.com/ziuus/Zervox/master/scripts/install.sh | bash

Quick Start

Watch a Node.js app with automatic restart:

Basic usage 
$ zervox start -- node server.js

From a specific directory with auto-fix and crash limits:

Advanced usage 
$ zervox start --cwd /path/to/project --max-restarts 5 --auto-fix -- node server.js

Open the Dashboard

Launch web UI 
$ zervox web

Opens the web dashboard at http://127.0.0.1:3000 with real-time process monitoring and AI diagnostics.

CLI Reference

All Zervox commands follow zervox <subcommand> [options] [--] <command>.

zervox check

Run a command once, capture output, summarize failures. Useful for one-shot health checks.

$ zervox check -- node -e "require('express')"

zervox start

Watch a process with automatic restart on crash.

$ zervox start --node server.js
$ zervox start --detach --name my-api -- node app.js

zervox add

Save a command by name so it persists across sessions.

$ zervox add web-app -- node server.js

zervox status

Show runtime status for all tracked processes.

$ zervox status

zervox logs

Show persistent logs for a process. Each process gets a named log file, auto-rotated.

$ zervox logs my-api
$ zervox logs my-api -n 50

zervox stop

Gracefully stop a tracked process.

$ zervox stop my-api

zervox systemd

Generate a systemd user service unit for a tracked process. Supports enable/disable/status.

$ zervox systemd my-api
$ zervox systemd my-api --enable

zervox list

List all tracked and saved commands.

$ zervox list

AI Auto-Fix

Zervox can analyze crash logs and attempt automatic repairs using Gemini AI. This is opt-in and runs entirely locally.

How it works

  1. 1. Process crashes. Zervox captures the last 80 lines of stdout/stderr and the exit code.
  2. 2. Gemini AI analyzes the output to identify the root cause: missing module, port conflict, syntax error, permission issue, etc.
  3. 3. A fix command is generated (npm install <pkg>, pnpm install, bun install, etc.) and validated for safety.
  4. 4. With --auto-fix, Zervox applies the fix and restarts. Without it, the suggested fix is shown in the dashboard for manual approval.

Flags

--auto-fix Enable automatic repair execution
--analyze Diagnose crash but skip auto-repair
--provider <provider> AI provider: gemini, openai, ollama

Configuration

All configuration is done through CLI arguments. There's no config file to manage.

--cwd <dir> Working directory for the child process
--max-restarts <n> Max restarts before giving up (default: 5)
--delay <ms> Delay between restarts (default: 1000ms)
--detach Run daemon in background
--name <name> Assign a name to the process
--log-size <n> Max log lines retained per process (default: 1000)

Web Dashboard

Zervox ships with a lightweight web dashboard built on Axum and WebSocket.io. It provides real-time process monitoring and AI diagnostics.

$ zervox web
[info] Dashboard listening on http://127.0.0.1:3000

Dashboard features

  • ✓ Live process list — See all tracked processes with status indicators (running/stopped/idle)
  • ✓ Per-process details — CPU, memory, uptime, and restart count for each process
  • ✓ Live log tailing — Real-time log viewer with auto-scroll and filter controls
  • ✓ AI Diagnostics panel — See detected issues, confidence scores, and suggested fix commands

Systemd Integration

Zervox can generate systemd user service units, allowing processes to survive reboots and run as standard systemd services.

$ zervox systemd my-api
[systemd] ✓ Unit written to ~/.config/systemd/user/zervox-my-api.service
$ systemctl --user enable zervox-my-api
$ systemctl --user start zervox-my-api

Systemd commands in Zervox

zervox systemd <name> Generate a systemd unit file
--enable Also enable the unit for autostart
--start Generate, enable, and start in one step
Note

Systemd integration requires systemd --user to be available on the system. It's typically enabled on most modern Linux distributions by default.