Documentation

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

The [[apps]] array is TOML's array-of-tables syntax — each [[apps]] block defines one managed process.

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. e.g. "curl -fsS http://127.0.0.1:3000/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.
wait_ready	bool?	Gate reload on health check readiness. Old process stays up until new one passes. Requires health_cmd.
ready_timeout_secs	int?	Timeout for readiness during reload. Reload aborts if exceeded. Default 30.
pre_reload_cmd	string?	Command run before reload (e.g. build step). Reload aborts on failure.
watch	bool\|string\|string[]?	Watch paths for changes and auto-restart. true = watch cwd.
ignore_watch	string[]?	Regex patterns for paths to ignore during watch.
watch_delay_secs	int?	Debounce delay before restarting after file change.
reuse_port	bool?	Best-effort SO_REUSEPORT hint. Sets OXMGR_REUSEPORT=1 in child env (macOS/Linux).
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

File Watch

Auto-restart when source files change. watch accepts a boolean, a single path, or an array of paths. Use ignore_watch for regex-based exclusions and watch_delay_secs to debounce rapid changes.

[[apps]]
name = "api"
command = "node server.js"
watch = ["src", "package.json"]   # bool, string, or array of paths
ignore_watch = ["target/", "\.log$"]  # regex patterns
watch_delay_secs = 2               # debounce restart

Readiness-Aware Reload

With wait_ready = true, a reload waits for the new instance to pass the health check before cutting over. If readiness times out, the old process keeps running — zero user impact on a failed deploy.

[[apps]]
name = "api"
command = "node server.js"
health_cmd = "curl -fsS http://127.0.0.1:3000/health"
wait_ready = true
ready_timeout_secs = 30  # fail reload if not ready within 30s

See Health Checks for the full health check configuration reference.

Pre-Reload Build Hook

pre_reload_cmd runs before any reload attempt. If it exits non-zero, the reload is aborted and the current process keeps running.

[[apps]]
name = "api"
command = "./target/release/api"
pre_reload_cmd = "cargo build --release"
# Build runs before reload. If build fails, old process keeps running.

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

Still have questions?

Open an issue or browse the source on GitHub.

Open an Issue ↗