Velos

High-performance AI-friendly process manager

Zig core + Rust shell. Next-gen PM2 alternative with native MCP server and zero-LLM smart log analysis.

Why Velos?

Process managers like PM2 and Supervisor were built before the AI era. Velos is designed from the ground up for a world where AI agents manage your infrastructure: a native MCP server lets Claude, Codex, or Gemini start, stop, and debug your processes directly. When something breaks, Velos detects the error in real time, analyzes it with AI, and can auto-fix the bug — all without you opening a terminal.

Under the hood, a Zig core keeps the daemon at ~3 MB RAM idle, growing just ~65 KB per managed process (vs PM2's ~60 MB baseline from the Node.js/V8 runtime). A Rust shell provides a modern CLI, smart log analysis, and observability stack — all in a single binary with zero runtime dependencies.

Quick Start

Install

# One-line installer (macOS / Linux)
curl -fsSL https://releases.velospm.dev/install.sh | bash

# macOS (Homebrew)
brew install Dave93/tap/velos

# Debian / Ubuntu
curl -fsSL https://releases.velospm.dev/setup-apt.sh | sudo bash

# RHEL / Fedora / CentOS
curl -fsSL https://releases.velospm.dev/setup-yum.sh | sudo bash

# From source (requires Zig 0.15+ and Rust 1.75+)
git clone https://github.com/Dave93/velos.git
cd velos
make build

Usage

# Start managing processes (daemon starts automatically)
velos start server.js --name api
velos start worker.py --name bg -i 4     # cluster mode: 4 instances
velos list                                # show all processes
velos logs api --summary                  # smart log summary
velos monit                               # TUI dashboard

Note: The daemon starts automatically on your first CLI command. No need to run velos daemon manually.

Shell Completions

# Bash
velos completions bash > ~/.bash_completion.d/velos
# Zsh
velos completions zsh > ~/.zfunc/_velos
# Fish
velos completions fish > ~/.config/fish/completions/velos.fish

Features

Process Management

• Start/stop/restart/reload with graceful shutdown (SIGTERM -> SIGKILL)
• Autorestart with crash loop detection (max_restarts, min_uptime, exp_backoff)
• Cluster mode — multi-instance with velos start -i N or -i max
• Watch mode — auto-restart on file changes (kqueue/inotify)
• Memory limits — restart when RSS exceeds threshold (--max-memory 150M)
• Cron restart — periodic restart on schedule (--cron-restart "0 3 * * *")
• Ready signal — process reports readiness via IPC (--wait-ready)
• Graceful shutdown — JSON message via IPC instead of SIGTERM (--shutdown-with-message)
• State persistence — save/resurrect process list across daemon restarts
• Auto-daemon — daemon starts automatically on first CLI command, no manual setup required

Runtime Error Detection (Sentry-like)

Velos monitors stderr of running processes for error patterns (Traceback, TypeError, panic, FATAL, segmentation fault, etc.) and sends notifications without requiring a process crash — similar to how Sentry detects runtime errors.

• Configurable via Telegram notifications
• Per-process 60-second cooldown to prevent notification spam
• Suppressed after AI auto-fix restart (no duplicate alerts)
• Works independently of crash detection

Smart Log Engine (Zero LLM Cost)

All "smart" features are algorithmic — regex, statistics, heuristics. No LLM API calls.

• Auto-classifier — detect log levels (regex + JSON-aware)
• Deduplication — collapse repeated messages with count and time range
• Pattern detection — frequency analysis with trend (rising/stable/declining)
• Anomaly detection — sliding window, mean + stddev, 2σ/3σ thresholds
• Summary — health score (0-100), top patterns, anomalies, last error

velos logs api --summary
velos logs api --level error --grep "timeout" --dedupe

MCP Server (AI Agent Integration)

Built-in Model Context Protocol server with 13 tools for AI agents. Supports stdio (local) and Streamable HTTP (remote) transports.

Local (stdio) — AI client and Velos on the same machine

{
  "mcpServers": {
    "velos": { "command": "velos", "args": ["mcp-server"] }
  }
}

{
  "mcpServers": {
    "velos": { "command": "/Users/you/.velos/bin/velos", "args": ["mcp-server"] }
  }
}

{
  "mcpServers": {
    "velos": { "command": "velos", "args": ["mcp-server"] }
  }
}

[mcp_servers.velos]
command = "velos"
args = ["mcp-server"]

{
  "mcpServers": {
    "velos": { "command": "velos", "args": ["mcp-server"] }
  }
}

Remote (HTTP) — Velos on VPS, AI client on your laptop

Start MCP server on your VPS:

velos mcp-server --port 8080

Then configure your AI client with the remote URL:

{
  "mcpServers": {
    "velos": { "type": "url", "url": "http://your-vps:8080/mcp" }
  }
}

[mcp_servers.velos]
url = "http://your-vps:8080/mcp"

{
  "mcpServers": {
    "velos": { "url": "http://your-vps:8080/mcp" }
  }
}

Tip: For production, use HTTPS via a reverse proxy (nginx/caddy) or SSH tunnel:

ssh -L 8080:localhost:8080 user@your-vps

Available Tools

Full reference: docs/mcp-tools.md

AI Output Mode (--ai)

The --ai flag outputs compact JSON with abbreviated keys, designed to minimize token usage when piping Velos output to LLMs or AI agents.

# Standard output
velos list
#  ID  Name  PID    Status   Memory    Uptime  Restarts
#  0   api   1234   online   45.2 MB   2h 30m  0

# JSON output (full keys)
velos list --json
# [{"id": 0, "name": "api", "pid": 1234, "status": "online", "memory_bytes": 47395840, ...}]

# AI output (abbreviated keys, ~40% fewer tokens)
velos list --ai
# [{"n":"api","i":0,"s":"online","m":47395840,"u":9000000,"r":0,"p":1234}]

Key abbreviations: n=name, i=id, s=status, p=pid, m=memory (bytes), u=uptime (ms), r=restarts, c=cpu (%), t=timestamp, l=level

Supported commands: velos list --ai, velos info <name> --ai, velos logs <name> --ai

AI Crash Analysis & Auto-Fix

When a process crashes, Velos can analyze the error with AI and auto-fix the bug. Supports Anthropic (Claude) and OpenAI-compatible providers (OpenAI, OpenRouter, Groq, Ollama, xAI).

# Configure AI provider
velos config set ai.provider anthropic
velos config set ai.api_key sk-ant-...
velos config set ai.model claude-sonnet-4-20250514

# Optional: enable auto-analysis on crash
velos config set ai.auto_analyze true

# Configure Telegram for crash notifications
velos config set telegram.bot_token 123456:ABC...
velos config set telegram.chat_id -100123456789
velos config set notifications.language ru    # en or ru

On crash or runtime error: logs are collected, stack traces parsed, source code extracted, AI analysis runs, and a Telegram notification is sent with Fix / Ignore inline buttons. After a successful AI fix, the process is automatically restarted and notifications are suppressed to prevent duplicate alerts.

# Manual commands
velos ai list                    # list crash records
velos ai analyze <crash-id>     # re-analyze a crash
velos ai fix <crash-id>         # run AI agent to auto-fix
velos ai ignore <crash-id>      # mark as ignored

The AI fix agent has 9 tools: read/edit/create/delete files, grep, glob, list directories, run commands, and git diff — all sandboxed to the project directory.

Supported AI providers: Anthropic (Claude), OpenAI, OpenRouter, Groq, Ollama, xAI — any OpenAI-compatible API.

Monitoring & Metrics

• TUI dashboard (velos monit) — real-time process table, memory sparkline, live logs
• Prometheus endpoint (velos metrics -p 9615) — scrape at /metrics
• OpenTelemetry — OTLP export (--otel-endpoint)
• REST API (velos api -p 3100) — JSON API + WebSocket real-time updates

CLI Reference

All commands support --json for machine-readable output.

Key Flags

# Start options
velos start app.js --name api --watch --max-memory 256M
velos start app.js -i 4                    # cluster: 4 instances
velos start app.js -i max                  # cluster: CPU count instances
velos start app.js --cron-restart "0 3 * * *"
velos start app.js --wait-ready --shutdown-with-message
velos start --config velos.toml

# Log options
velos logs api -l 200                      # last 200 lines
velos logs api --level error,warn          # filter by level
velos logs api --grep "timeout"            # regex filter
velos logs api --since "1h" --dedupe       # last hour, deduplicated
velos logs api --summary                   # health score + patterns

# Output modes
velos list --json                          # full JSON
velos list --ai                            # compact JSON for LLM

Configuration (TOML)

[apps.api]
script = "server.js"
cwd = "/app"
interpreter = "node"
autorestart = true
max_restarts = 15
min_uptime = 1000
kill_timeout = 5000
max_memory_restart = "150M"

# File watching
watch = true
watch_paths = ["src/", "config/"]
watch_ignore = ["node_modules", ".git", "*.log"]
watch_delay = 1000

# Environment variables
[apps.api.env]
NODE_ENV = "production"
PORT = "3000"

# Profile-specific env (--env production)
[apps.api.env_production]
DATABASE_URL = "postgres://prod:5432/db"

[apps.worker]
script = "worker.py"
interpreter = "python3"
autorestart = true
max_memory_restart = "256M"

velos start --config velos.toml
velos start --config velos.toml --env production

Full example: config/velos.example.toml

Stack Examples

Architecture

┌──────────────┐     Unix socket     ┌──────────────────────┐
│  velos CLI   │ <──── IPC ────────> │   Zig Daemon Core    │
│  (Rust)      │   binary protocol   │  fork/exec, kqueue,  │
│  clap, tokio │                     │  CPU/RAM monitoring,  │
└──────────────┘                     │  log collector,       │
                                     │  file watcher,        │
                                     │  cron scheduler       │
                                     └──────────────────────┘

Zig core (zig/src/): daemon, fork/exec, IPC server, event loop (kqueue/epoll), CPU/RAM monitoring via syscalls, log collector with error pattern detection, ring buffer, file watcher, cron parser, IPC channel (socketpair).

Rust shell (crates/): CLI (clap) with 27+ commands, IPC client, TOML config, Smart Log Engine, MCP Server (JSON-RPC stdio + Streamable HTTP), Prometheus/OpenTelemetry, REST API (axum), TUI (ratatui), AI crash analysis agent.

Bridge: Zig compiles to libvelos_core.a (static library, C ABI) -> Rust links via FFI.

IPC protocol: binary, 7-byte header (magic 0xVE10 + version + length LE u32) + MessagePack payload. Unix socket at ~/.velos/velos.sock.

Full architecture: docs/ARCHITECTURE.md

Runtime Directory

~/.velos/
├── velos.sock          # IPC Unix socket
├── velos.pid           # Daemon PID file
├── config.toml         # Global config (velos config set/get)
├── state.bin           # Saved process state (velos save / auto-save)
├── crashes/            # AI crash records and agent logs
│   ├── <id>.json       # Crash context + analysis
│   └── <id>.log        # AI agent execution log
└── logs/               # Process log files
    ├── api-out.log     # stdout
    └── api-err.log     # stderr

Building from Source

Requirements

• Zig 0.15+
• Rust 1.75+ (with cargo)
• macOS or Linux

Build

make dev          # Debug: Zig + Rust (fast iteration)
make build        # Release: Zig (ReleaseFast) + Rust (release)
make test         # All tests: Zig unit + Rust unit
make clean        # Clean build artifacts

Pipeline: zig build -> libvelos_core.a -> cargo build -> target/release/velos

Tests

# Zig unit tests
cd zig && zig build test

# Rust unit tests
cargo test --workspace

# Integration tests (49 tests, full lifecycle)
bash tests/integration_lifecycle.sh

Documentation

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, code style, and PR guidelines.

Before contributing, please read:

• CONTRIBUTING.md — development setup and workflow
• CODE_OF_CONDUCT.md — community standards
• docs/ARCHITECTURE.md — Zig+Rust hybrid architecture

For security vulnerabilities, see SECURITY.md.

License

MIT OR Apache-2.0