Documentation

Oxmgr Docs

Everything you need to install, configure, and run Oxmgr in production.

Quick Start

Get from zero to running processes in under two minutes.

1 — Install

npm install -g oxmgr

More install methods: Homebrew, APT, Chocolatey, source

2 — Write your oxfile.toml

oxfile.toml

version = 1

[defaults]
restart_policy = "on_failure"
max_restarts = 10
stop_timeout_secs = 5

[[apps]]
name = "api"
command = "node server.js"
cwd = "./services/api"
health_cmd = "curl -fsS http://127.0.0.1:3000/health"

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

[[apps]]
name = "worker"
command = "python worker.py"
cwd = "./services/worker"

[apps.env]
PYTHONUNBUFFERED = "1"

3 — Apply

oxmgr apply ./oxfile.toml

apply is idempotent — safe to run in CI/CD. Starts new processes, restarts changed ones, leaves untouched ones alone.

4 — Monitor

oxmgr list           # show all processes
oxmgr logs api -f    # stream logs
oxmgr ui             # interactive terminal UI

Installation

Oxmgr supports Linux, macOS, and Windows.

npm / yarn

npm install -g oxmgr
# or
yarn global add oxmgr

Homebrew macOS

brew tap empellio/homebrew-tap
brew install oxmgr

Chocolatey Windows

choco install oxmgr -y

APT — signed Debian / Ubuntu (recommended)

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://vladimir-urik.github.io/OxMgr/apt/keyrings/oxmgr-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/oxmgr-archive-keyring.gpg &gt;/dev/null
echo "deb [signed-by=/etc/apt/keyrings/oxmgr-archive-keyring.gpg] https://vladimir-urik.github.io/OxMgr/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/oxmgr.list
sudo apt update &amp;&amp; sudo apt install oxmgr

Build from source Requires Rust toolchain

git clone https://github.com/Vladimir-Urik/OxMgr.git
cd OxMgr
cargo build --release
./target/release/oxmgr --help

Verify install

oxmgr --help
oxmgr list

CLI Reference

All commands grouped by category.

Runtime & monitoring

Command	Aliases	Description
oxmgr list	ls, ps	Show all processes with status, CPU, RAM, uptime
oxmgr status <name>		Detailed process info including restart policy, limits, log paths
oxmgr logs <name> [-f]	log	Stream or show logs. --lines <n> for history
oxmgr ui		Interactive terminal UI with keyboard + mouse

Lifecycle

Command	Aliases	Description
oxmgr start "<cmd>" --name <n>		Start a process. See start options below.
oxmgr stop <name>		Stop a running process
oxmgr restart <name>	rs	Restart a process (resets crash-loop counter)
oxmgr reload <name>		Graceful reload (zero-downtime where supported)
oxmgr pull [name]		Git pull + reload/restart only if commit changed
oxmgr delete <name>	rm	Stop and remove process from daemon state

Start options

Flag	Default	Description
--name <n>		Process name used in CLI commands
--restart <policy>	on-failure	always \| on-failure \| never
--max-restarts <n>	10	Max consecutive auto-restarts
--crash-restart-limit <n>	3	Stop restarting after N crashes in 5 min. 0 = disabled
--cwd <path>		Working directory for the process
--env KEY=VALUE		Environment variable (repeatable)
--watch	false	Watch cwd and restart on file changes
--health-cmd <cmd>		Command polled to verify health
--health-interval <s>	30	Seconds between health checks
--health-timeout <s>	5	Timeout for each health check
--health-max-failures <n>	3	Failures before restart
--cluster	false	Node.js cluster mode
--cluster-instances <n>	all CPUs	Worker count (requires --cluster)
--max-memory-mb <n>		Memory limit in MB
--max-cpu-percent <n>		CPU usage limit (%)
--restart-delay <s>	0	Delay between auto-restarts
--stop-timeout <s>	5	Grace period before force-kill

Config commands

oxmgr apply <path> [--env <profile>] [--only a,b] [--prune]	Apply oxfile config. --prune removes unmanaged processes.
oxmgr validate <path> [--env <profile>]	Validate oxfile before deploy. Great for CI.
oxmgr import <source> [--sha256 <hex>]	Import oxpkg bundle or ecosystem.config.json
oxmgr export <name>	Export process config as oxpkg bundle
oxmgr convert <ecosystem.json> --out <oxfile.toml>	Convert PM2 ecosystem JSON to oxfile.toml

Interactive UI — keyboard shortcuts

Key	Action
`j / k or ↑↓`	Move selection up / down
`n`	Create new process
`s`	Stop selected
`r`	Restart selected
`l`	Reload selected
`p`	Pull selected (git pull + reload)
`t`	Preview latest log line
`g / Space`	Refresh now
`?`	Show help overlay
`Esc`	Open / close menu
`q`	Quit

Mouse: click row to select, scroll wheel to navigate

oxfile.toml

Native Oxmgr configuration format. Designed for deterministic, idempotent process management via oxmgr apply.

File structure

version = 1

[defaults]
# optional defaults for all apps

[[apps]]
# repeated app entries

Full field reference

Field	Type	Description
name	string	Process identifier. Used in all CLI commands.
command	string*	Shell command to run. Required per app.
cwd	string?	Working directory for the process.
env	table?	Environment variables as key-value pairs.
restart_policy	string?	"always" \| "on_failure" \| "never". Default: on_failure.
max_restarts	int?	Max consecutive restarts before entering errored state.
crash_restart_limit	int?	Stop after N auto-restarts in 5 min. Default 3. Set 0 to disable.
stop_timeout_secs	int?	Seconds to wait for graceful shutdown before force-kill.
stop_signal	string?	Signal sent on stop (e.g. SIGTERM, SIGINT).
restart_delay_secs	int?	Delay between automatic restarts.
start_delay_secs	int?	Delay before initial process start.
health_cmd	string?	Command polled to verify process health.
health_interval_secs	int?	Seconds between health checks. Default 30.
health_timeout_secs	int?	Timeout per health check. Default 5.
health_max_failures	int?	Failures before process restart. Default 3.
max_memory_mb	int?	Memory limit in MB. Triggers restart if exceeded.
max_cpu_percent	float?	CPU limit (%). Triggers restart if exceeded.
cgroup_enforce	bool?	Linux only. Applies hard limits via cgroup v2.
deny_gpu	bool?	Best-effort GPU disable via environment variables.
cluster_mode	bool?	Node.js cluster fan-out mode.
cluster_instances	int?	Worker count. Defaults to all CPUs.
instances	int?	Expand one entry into N named processes.
instance_var	string?	Env var set to instance index (0, 1, 2…).
depends_on	string[]?	Start after listed apps are running.
start_order	int?	Tie-break start ordering.
namespace	string?	Group processes under a namespace.
git_repo	string?	Git remote URL for oxmgr pull.
git_ref	string?	Branch or tag to track.
pull_secret	string?	Secret for webhook endpoint authentication.
disabled	bool?	Skip this app during apply.

Profiles

Use [apps.profiles.<name>] to override fields per environment. Activate with --env prod.

oxfile.toml

version = 1

[defaults]
restart_policy = "on_failure"

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

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

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

oxmgr apply ./oxfile.toml --env prod

Instances — horizontal scaling

Expand one app entry into N managed processes. Each gets a unique name suffix and an INSTANCE_ID env var.

[[apps]]
name = "worker"
command = "node worker.js"
instances = 3
instance_var = "INSTANCE_ID"
# Expands to: worker-0, worker-1, worker-2
# Each gets env var INSTANCE_ID=0/1/2

Node.js cluster mode

Fan-out a single managed entry using Node.js cluster. Command must be node <script> shape.

[[apps]]
name = "api"
command = "node server.js"
cluster_mode = true
cluster_instances = 4  # omit to use all CPUs

Deploy environments

Define remote deployment targets directly in your oxfile.

[deploy.production]
user = "ubuntu"
host = ["192.168.0.13", "192.168.0.14"]
repo = "git@github.com:org/api.git"
ref = "origin/main"
path = "/var/www/api"
pre_deploy = "npm ci"
post_deploy = "oxmgr apply ./oxfile.toml --env production"

oxmgr deploy ./oxfile.toml production setup
oxmgr deploy ./oxfile.toml production

Health Checks

Command-based health checks are polled periodically. After health_max_failures consecutive failures, the process is automatically restarted.

oxfile.toml

[[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

Polling interval

health_interval_secs (default: 30s)

Check timeout

health_timeout_secs (default: 5s)

Restart trigger

After health_max_failures (default: 3)

Exit code

Non-zero = failure, zero = healthy

Resource Limits

Oxmgr monitors resource usage during daemon maintenance ticks. When limits are exceeded, the process is restarted. If the restart budget is exhausted, it's marked errored.

oxfile.toml

[[apps]]
name = "api"
command = "node server.js"
max_memory_mb = 512
max_cpu_percent = 80.0
cgroup_enforce = true  # Linux only — hard limits via cgroup v2
deny_gpu = true        # best-effort GPU disable

Platform notes

—cgroup_enforce requires Linux with cgroup v2 enabled (modern kernels).
—deny_gpu is best-effort: disables common GPU env vars but doesn't prevent hardware access.
—Memory and CPU limits apply on all platforms via daemon polling.

System Services

Install the Oxmgr daemon as a system service so it starts automatically on boot. --system auto detects your platform.

# Install daemon as system service (auto-detects platform)
oxmgr service install --system auto

# Check service status
oxmgr service status --system auto

# Uninstall service
oxmgr service uninstall --system auto

🐧

Linux

systemd

🍎

macOS

launchd

🪟

Windows

Task Scheduler

# Run oxmgr doctor to check daemon health
oxmgr doctor

Git & Webhooks

Enable auto-deployment by connecting a process to a git repository. oxmgr pull fetches the latest code and reloads/restarts only when the commit changed.

Configure in oxfile.toml

oxfile.toml

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

Manual pull

oxmgr pull api       # pull specific process
oxmgr pull           # pull all git-tracked processes

Webhook endpoint

The daemon exposes an HTTP webhook. Point your CI/CD or GitHub Actions to this endpoint to trigger automatic deploys on push.

# Trigger pull via webhook
curl -X POST http://localhost:PORT/pull/api \
  -H "X-Oxmgr-Secret: super-secret-token"

Endpoint	POST /pull/<name\|id>
Auth header	X-Oxmgr-Secret: <pull_secret>
Alt auth	Authorization: Bearer <pull_secret>
Bind address	OXMGR_API_ADDR env var (default: high localhost port)

PM2 Migration

Oxmgr supports PM2's ecosystem.config.json for a smooth migration path. Import existing config directly, then convert to the native format at your own pace.

# Step 1 — Import existing PM2 ecosystem file
oxmgr import ./ecosystem.config.json

# Step 2 — Convert to native oxfile format
oxmgr convert ecosystem.config.json --out oxfile.toml

# Step 3 — Validate
oxmgr validate ./oxfile.toml --env prod

# Step 4 — Apply
oxmgr apply ./oxfile.toml --env prod

Format comparison

Topic	PM2 ecosystem.json	oxfile.toml
Profiles	env_<name> pattern	[apps.profiles.<name>]
Dependencies	limited/indirect	explicit depends_on
Crash-loop cutoff	compatibility only	native crash_restart_limit
Apply idempotency	medium	high
Readability at scale	medium	high
Dynamic JS execution	yes (config.js)	no (safer)

Environment Variables

Configure Oxmgr behavior via environment variables.

Variable	Description
OXMGR_HOME	Custom Oxmgr data directory. Default: ~/.local/share/oxmgr (Linux/macOS), %LOCALAPPDATA%\oxmgr (Windows).
OXMGR_DAEMON_ADDR	Custom daemon bind address (host:port).
OXMGR_API_ADDR	HTTP API / webhook bind address. Default: high localhost port.
OXMGR_LOG_MAX_SIZE_MB	Log rotation size threshold in MB.
OXMGR_LOG_MAX_FILES	Number of rotated log files to retain.
OXMGR_LOG_MAX_DAYS	Rotated log retention period in days.

Still have questions?

Open an issue or browse the source on GitHub.

Open an Issue ↗