dmon

A lightweight, cross-platform process manager for local services and development workflows. Run any command as a background task, or supervise a stack with readiness checks and repair failed members while healthy services keep running. Logging and log rotation are built in.

For developers and coding agents, dmon records process identities and exposes JSON status so later sessions can inspect and reuse existing services. See coding-agent setup.

Shipped as the CLI tool dmon.

Features

• 🖥️ Cross-platform: Works on Linux, macOS, and Windows.
• ⚡ Lightweight: No daemon service or container runtime required.
• 🧩 Flexible tasks: Tasks can be configured in pyproject.toml or dmon.yaml; or run ad-hoc commands directly.
• 🔗 Supervised stacks: Start dependent tasks in order, wait for HTTP, TCP, or command readiness, and report runtime degradation.
• 🌙 Foreground or detached: Keep a stack attached for development, or run it under a recoverable background supervisor with dmon stack up -d and dmon stack down.
• ⏱️ Reusable readiness: Wait for configured tasks or direct HTTP, TCP, and command probes from scripts and deployment workflows.
• 🪵 Logging & log rotation: Keep active log files manageable, with optional archive retention limits.

Demos

The demos below cover everyday task management and supervised stacks. Both use this dmon.yaml and a small heartbeat program:

tasks:
  api: [python, -u, service.py, api]
  worker: [python, -u, service.py, worker]
stacks:
  dev: [api, worker]

Everyday tasks. Run a command directly with run (no configuration needed), then use start, status, and stop for a configured task. exec runs a configured task in the foreground; Ctrl-C ends it. In this clip, stop --all stops the sole ad-hoc task before the configured API is started.

Keep healthy services running. Start a stack, deliberately stop its worker, and repair that member. The API keeps the same PID and its counter continues; stack down stops both members. The lower panes show real files and live logs.

Installation

dmon requires Python 3.8+ and is available as python-dmon on PyPI. Managed commands can use any language.

pip install python-dmon

We recommend installing into an isolated environment, e.g., with uv / pipx:

# Install globally with uv tool
uv tool install python-dmon

# Or with pipx
pipx install python-dmon

# Add as a dev dependency in your project
uv add --dev python-dmon

You can also run dmon without installing it permanently:

# With uvx (uv tool run)
uvx python-dmon

# Or with pipx
pipx run python-dmon

To get the latest features, install from source:

pip install git+https://github.com/atomiechen/dmon.git

For coding agents, see the setup instructions and the portable skill. The skill is installed separately from the CLI.

Getting Started

Prepare Configuration

Create a dmon.yaml file:

tasks:
  app: ["python", "-u", "server.py"]  # exec form
  # app: "python -u server.py"        # or a shell string

Without --config, dmon searches the current directory and its parents for dmon.yaml, dmon.yml, or pyproject.toml. See the configuration reference for TOML, environments, paths, defaults, and log rotation.

Run tasks

dmon start app      # Start in the background
dmon stop app      # Stop the recorded process tree
dmon restart app
dmon status app
dmon exec app      # Run in this terminal; Ctrl-C ends it

exec runs one configured command directly, without registering a managed background task. Use start to keep it discoverable through status and list. You can pass multiple names to the other task commands. Multi-task start is best-effort: successful tasks stay running if another fails. For related services with ordered startup and rollback, use a stack.

Run a stack

tasks:
  api:
    cmd: [python, api.py]
    ready:
      http: http://127.0.0.1:8000/health
  worker:
    cmd: [python, worker.py]
    depends_on: [api]
stacks:
  dev: [api, worker]

dmon stack up dev          # Foreground; Ctrl-C stops the stack
# Or keep it running under a background supervisor:
dmon stack up -d dev
dmon stack status dev
dmon stack logs --tail 100 dev
dmon stack repair dev worker --format json  # Replace an exited member
dmon stack down dev

Stack startup waits for readiness and rolls back tasks it started if startup fails. After startup, an exited member degrades the stack while healthy peers keep running. repair replaces that member through its live supervisor, so later down includes the replacement. It reuses the supervisor's launch configuration and environment; separately running dmon start worker does not repair stack membership.

See task and stack lifecycle for fail-fast behavior, detached restart, recovery, and ownership limits. Docker Compose is still appropriate when container behavior itself must be tested.

Wait for readiness

dmon wait checks readiness without starting or stopping anything. Configured tasks need a ready probe and must already be managed by start or a stack:

dmon wait api
dmon wait api --timeout 60 --interval 0.5

# Direct probes need no configuration
dmon wait --http http://127.0.0.1:8000/health
dmon wait --tcp 127.0.0.1:5432
dmon wait --timeout 30 --command -- python healthcheck.py --verbose

Put dmon options before --command; the optional second -- marks the child command. See readiness configuration for probe options, listener ownership checks, and wait results.

Run an ad-hoc command

dmon run --name myserver python -u server.py
dmon run --name timer -- python -c 'import time; time.sleep(30)'
dmon run --shell echo "Hello World"
dmon run --cwd /path/to/script bash myscript.sh

No configuration is needed. Without --name, dmon uses the fixed name default_run to prevent duplicate runs.

List recorded tasks and their status

dmon list
dmon status app --format json
dmon list --format json
dmon stack status dev --format json
dmon stack list --format json
dmon wait api --format json

JSON is written only to stdout; actionable diagnostics remain on stderr. The payload has a top-level ok field and a tasks, stacks, or waits array. Inspection results contain name, ok, error, and an optional snapshot; wait results contain the target, outcome, reason, elapsed time, and attempt count. Existing exit-code semantics are unchanged. Interactive and streaming commands do not offer JSON output.

Python API

The same task lifecycle and inspection logic is available without parsing CLI output:

from dmon import Dmon

client = Dmon(config="dmon.yaml")
started = client.start("app")
task = client.status("app")
stacks = client.list_stacks()
client.stop("app")

client.wait("app", timeout=30) also checks readiness when app has a configured ready probe. API calls are synchronous and silent. start, stop, and restart return an immutable BatchResult; status and stack_status return TaskResult and StackResult. List and wait methods return tuples of their corresponding result types. Expected runtime states such as missing or exited metadata are results, while invalid configuration raises DmonConfigError. The initial API intentionally does not start a supervised stack or create implicit background threads.

Documentation

Start with the documentation index:

• Configuration: task selection, YAML/TOML, environments, readiness, and logs.
• Task and stack lifecycle: startup, repair, recovery, and process ownership.
• Coding-agent setup: install the workflow and continue across sessions.

Development

See CONTRIBUTING.md for architecture, behavioral contracts, validation, and the release workflow. Process, signal, log-rotation, and stack changes must also pass the reproducible manual test lab.

License

dmon © 2025 by Atomie CHEN is licensed under the MIT License.