https://github.com/ziuus/zervox
Node.js monitoring daemon experiment with automated health checks and recovery actions.
https://github.com/ziuus/zervox
Last synced: 7 days ago
JSON representation
Node.js monitoring daemon experiment with automated health checks and recovery actions.
- Host: GitHub
- URL: https://github.com/ziuus/zervox
- Owner: ziuus
- License: mit
- Created: 2026-03-03T19:36:01.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-05-21T22:32:21.000Z (25 days ago)
- Last Synced: 2026-05-22T07:47:22.237Z (24 days ago)
- Language: Rust
- Homepage: https://zervox.vercel.app
- Size: 107 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Zervox
A Rust watchdog for Node.js apps and long-running development commands.
Zervox can run commands in the foreground for quick checks, or start a detached supervisor that keeps runtime state, tracks PIDs, writes persistent logs, restarts crashed processes with backoff, and reports useful crash hints.
## Why Rust
- Ships as a single binary
- Lower memory footprint than a Node daemon
- Better fit for long-running process supervision
- Easier to install on servers and developer machines
- Strong foundation for native process control, systemd integration, and safe AI-assisted diagnostics
## Implemented
- `zervox check -- ` - run once and summarize failures
- `zervox start -- ` - foreground watchdog with restart limit
- `zervox start --detach --name -- ` - background supervisor
- `zervox add -- ` - save a command locally
- `zervox up ` - start a saved command in detached mode
- `zervox status [name]` - show runtime status, supervisor PID, child PID, restarts, and log path
- `zervox logs ` - tail persistent logs
- `zervox stop ` - stop supervisor and child process
- `zervox restart ` - restart a saved supervised process
- `zervox cleanup` - remove stopped runtime records and mark stale supervisors
- `zervox systemd ` - print a user-level systemd unit for a tracked command
- `zervox systemd --install` - install the user-level systemd unit
- `zervox list`, `zervox run`, `zervox remove`, `zervox doctor`
- Crash hints for common Node errors like port conflicts, missing modules, permission issues, and syntax errors
## Runtime files
- Config: `~/.config/zervox/processes.json`
- Runtime state: `~/.local/state/zervox/runtime.json`
- Logs: `~/.local/state/zervox/logs/.log`
Use `zervox doctor` to print the exact paths on your machine.
## Build
```bash
cargo build --release
```
The binary will be available at:
```bash
./target/release/zervox
```
## Usage
Run a command once:
```bash
zervox check -- node server.js
```
Run in the foreground and restart it up to five times:
```bash
zervox start --max-restarts 5 -- node server.js
```
Start as a detached supervised process:
```bash
zervox start --detach --name api --max-restarts 5 -- node server.js
```
Inspect and operate it:
```bash
zervox status api
zervox logs api -n 50
zervox restart api
zervox stop api
```
JavaScript entry files are automatically run with Node:
```bash
zervox start server.js
```
Track a command for later:
```bash
zervox add api --max-restarts 5 -- node server.js
zervox list
zervox up api
```
Run in another directory:
```bash
zervox start --detach --name api --cwd ./apps/api -- npm run dev
```
## Example crash summary
```text
Crash detected
command: node server.js
exit code: 1
hint: port conflict detected. Stop the existing process or change PORT.
recent output
Error: listen EADDRINUSE: address already in use :::3000
```
## Production-readiness status
Zervox now has the core pieces of a production watchdog:
- Detached supervisor process
- PID tracking for supervisor and child
- Persistent runtime state
- Persistent per-process logs
- Stop/restart/status/log commands
- Restart limit and exponential backoff
- Stale PID detection for killed supervisors or rebooted machines
- User-level systemd unit generation
- Integration tests around the real CLI and detached lifecycle
- Strict Rust checks passing
Still needed before a serious public release:
1. GitHub Actions release pipeline for Linux binaries
2. Optional AI diagnostics with review-before-run safety controls
3. TUI or web dashboard
4. More platform testing outside Linux/systemd
## Install from release
The recommended public install path is a one-line installer script. The script downloads the prebuilt release binary, verifies the SHA256 checksum when available, and installs `zervox` into `~/.local/bin` by default.
```bash
curl -fsSL https://raw.githubusercontent.com/ziuus/Zervox/master/scripts/install.sh | bash
```
Install a specific version:
```bash
VERSION=v0.1.0 curl -fsSL https://raw.githubusercontent.com/ziuus/Zervox/master/scripts/install.sh | bash
```
Install somewhere else:
```bash
BIN_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/ziuus/Zervox/master/scripts/install.sh | bash
```
Uninstall:
```bash
curl -fsSL https://raw.githubusercontent.com/ziuus/Zervox/master/scripts/install.sh | bash -s -- --uninstall
```
## Release
Tag a version to trigger the Linux binary release workflow:
```bash
git tag v0.1.0
git push origin v0.1.0
```
The workflow uploads `zervox-x86_64-unknown-linux-gnu.tar.gz` and a SHA256 file.
## Development
```bash
cargo fmt --check
cargo test --all-targets
cargo clippy --all-targets --all-features -- -D warnings
cargo run -- check -- node -e "console.log('ok')"
```