Oxmgr

Oxmgr — AI Skill Reference

Drop this file into your project (e.g. reference it from CLAUDE.md, .cursor/rules, or paste it into your AI context) so your AI assistant knows how to help you use Oxmgr.

What Oxmgr Does

Oxmgr is a lightweight process manager (PM2 alternative) for running and supervising long-running services. It works with any language — Node.js, Python, Go, Rust, shell scripts, anything you can run from a terminal.

You use it to:

• Start services and keep them running with auto-restart
• Manage multiple services with a single config file (oxfile.toml)
• Apply config idempotently in CI/CD: oxmgr apply ./oxfile.toml
• Tail logs, check status, monitor CPU/RAM
• Watch files and restart on changes (dev workflow)
• Do zero-downtime reloads with health checks
• Auto-update services via git pull or webhook

Install: npm install -g oxmgr or see oxmgr releases.

Everyday Commands

# Start a service
oxmgr start "node server.js" --name api --restart always

# List all services
oxmgr list          # aliases: ls, ps

# Check one service
oxmgr status api

# Tail logs
oxmgr logs api -f

# Stop / restart / reload
oxmgr stop api
oxmgr restart api   # alias: rs
oxmgr reload api    # zero-downtime if health check configured

# Delete
oxmgr delete api    # alias: rm

# Interactive TUI
oxmgr ui

# Config workflow
oxmgr validate ./oxfile.toml
oxmgr apply ./oxfile.toml
oxmgr apply ./oxfile.toml --env prod

Config File: oxfile.toml

The recommended way to manage services. One file, multiple services, repeatable deploys.

Minimal config

version = 1

[[apps]]
name = "api"
command = "node server.js"
restart_policy = "on_failure"
max_restarts = 10
stop_timeout_secs = 5

oxmgr apply ./oxfile.toml

Common fields

version = 1

[[apps]]
name = "api"
command = "node server.js"
cwd = "./services/api"               # working directory
restart_policy = "on_failure"        # always | on_failure | never
max_restarts = 10
crash_restart_limit = 3              # max auto-restarts in 5min window; 0 = disable
stop_signal = "SIGTERM"
stop_timeout_secs = 5
restart_delay_secs = 2
start_delay_secs = 0
namespace = "backend"                # logical group label

[apps.env]
NODE_ENV = "production"
PORT = "3000"

Health checks

[[apps]]
name = "api"
command = "node server.js"
health_cmd = "curl -fsS http://127.0.0.1:3000/health"
health_interval_secs = 15
health_timeout_secs = 3
health_max_failures = 3

Health check runs periodically. After health_max_failures consecutive failures the process is restarted.

Zero-downtime reload

health_cmd = "curl -fsS http://127.0.0.1:3000/health"
wait_ready = true
ready_timeout_secs = 30
pre_reload_cmd = "npm run build"     # optional: run before reload; failure aborts reload

oxmgr reload api starts the new process, waits until health check passes, then cuts over. If readiness times out, the old process keeps running.

File watch (dev)

watch = ["src", "package.json"]
ignore_watch = ["node_modules/", "\\.log$"]
watch_delay_secs = 1

watch = true watches cwd. watch = "path" or watch = ["a", "b"] watches explicit paths.

Multiple instances

instances = 4
instance_var = "INSTANCE_ID"         # env var set to 0/1/2/3 per instance

Oxmgr spawns api-0, api-1, api-2, api-3 as separate managed processes.

Node.js cluster mode

command = "node server.js"
cluster_mode = true
cluster_instances = 4               # omit to use all CPUs

Single managed process entry, Node.js handles worker fan-out internally. Command must be node <script>.

Resource limits

max_memory_mb = 512
max_cpu_percent = 80.0
cgroup_enforce = true               # Linux only: hard cgroup v2 limits at spawn

Soft limits are checked periodically; when exceeded the process is restarted. cgroup_enforce applies hard OS-level limits.

Service dependencies

[[apps]]
name = "db"
command = "docker compose up db"
start_order = 0
health_cmd = "pg_isready -h 127.0.0.1"

[[apps]]
name = "api"
command = "node server.js"
depends_on = ["db"]                 # waits for db to be up
start_order = 10

depends_on enforces start direction. start_order is a tie-break among apps ready to start at the same time.

Profiles (dev / staging / prod)

[[apps]]
name = "api"
command = "node server.js"
instances = 1

[apps.env]
NODE_ENV = "development"
PORT = "3000"

[apps.profiles.prod]
instances = 4
restart_policy = "always"
max_memory_mb = 768

[apps.profiles.prod.env]
NODE_ENV = "production"
PORT = "8080"

oxmgr apply ./oxfile.toml --env prod

Config resolution order: [defaults] → [[apps]] → [apps.profiles.<name>]. Scalars override; env maps merge.

Shared defaults

[defaults]
restart_policy = "on_failure"
max_restarts = 10
stop_timeout_secs = 5
health_interval_secs = 20
health_timeout_secs = 4
health_max_failures = 3
max_memory_mb = 512
env = { TZ = "UTC" }

[[apps]]
name = "api"
command = "node server.js"
# inherits all defaults above

[[apps]]
name = "worker"
command = "python worker.py"
max_memory_mb = 256                 # overrides default

Skip an app

[[apps]]
name = "worker"
command = "python worker.py"
disabled = true                     # skipped by apply

Git pull + webhook auto-update

[[apps]]
name = "api"
command = "node server.js"
git_repo = "git@github.com:org/repo.git"
git_ref = "main"
pull_secret = "your-long-random-secret"

oxmgr pull api
# or via HTTP webhook:
curl -X POST http://localhost:<port>/pull/api \
  -H "X-Oxmgr-Secret: your-long-random-secret"

Only reloads/restarts if the commit changed.

Full Field Reference

[[apps]] / [defaults]

Gotchas

• restart_policy uses underscores in oxfile.toml (on_failure) but hyphens in CLI flags (--restart on-failure).
• instances (Oxmgr multi-process) and cluster_mode (Node.js internal clustering) are separate features — don't combine them.
• crash_restart_limit = 0 disables the 5-minute crash-loop cutoff only, not the total max_restarts budget.
• wait_ready requires health_cmd to be set.
• cluster_mode requires the command to be node <script> — no runtime flags before the script.
• env tables are always merged (not replaced) across the defaults → app → profile layers.
• --prune flag on apply removes processes from the daemon that are no longer in the config.
• apply is idempotent — safe to run in CI/CD on every deploy. Unchanged apps are left untouched.

Source: Vladimir-Urik/OxMgr — distributed by TomeVault.