mhost Documentation

mhost ships as a single static binary with zero runtime dependencies. Pick your preferred method:

Homebrew (macOS / Linux)

curl installer (Linux / macOS)

Cargo (from source)

GitHub Releases (manual binary)

Docker

Nix

Get your first process running in under 30 seconds.

Create mhost.toml in your project root, then run mhost start — mhost will auto-discover the file.

mhost has two components: a persistent daemon and a CLI. The daemon spawns and supervises processes, stores logs in an embedded SQLite database, and exposes a JSON-RPC socket. The CLI communicates with the daemon over a Unix socket at ~/.mhost/mhost.sock.

The daemon starts automatically the first time you run any mhost command. To start it explicitly: mhost daemon start. To stop: mhost daemon stop.

Every process moves through these states:

• --name <name>Assign a name (default: filename without extension).
• --instances <N>Number of instances to spawn (cluster mode).
• --max-memory <MB>Auto-restart when RSS exceeds this limit.
• --env <KEY=VAL>Inject environment variables (repeatable).
• --env-file <path>Load variables from a .env file.
• --cwd <path>Working directory for the process.
• --interpreter <bin>Override the auto-detected interpreter.
• --grace-period <dur>Time to wait for graceful shutdown (default: 10s).
• --no-autorestartDisable automatic restart on crash.
• --watchWatch files and restart on change (dev mode).

Auto-detect Interpreter

mhost infers the interpreter from the file extension so you can pass a filename directly:

Stop, Restart, Delete

Zero-Downtime Reload

Send SIGUSR2 to trigger a rolling restart with no dropped requests. mhost brings up new instances before tearing down the old ones:

Index-based Process Targeting

Every process in the registry has a numeric index (shown in mhost list). You can use the index instead of the name in any command:

Scaling

Scale a named process to N instances at runtime with no downtime — mhost adds or removes workers gracefully:

Process Groups & Dependencies

Groups let you start, stop, and restart related processes together. Declare them in your config:

Save & Resurrect

Persist the current process list to disk so mhost can restore it after a system reboot:

Full configuration reference for a single process:

YAML & JSON Alternatives

mhost auto-detects format by file extension. Use --config to specify a path:

All three formats support the same keys. TOML is recommended for production due to its comment support.

Environment Variable Expansion

Any string value in config can reference environment variables using ${VAR} syntax. Variables are resolved at daemon startup:

Health Probes

Three probe types are supported. A process is considered errored when the probe fails retries times consecutively.

HTTP Probe

TCP Probe

Script Probe

Cron Restarts

Schedule automatic restarts using standard cron syntax (UTC by default):

Memory Limits

When a process exceeds max_memory, mhost restarts it and fires a notification on configured channels. Supported suffixes: MB, GB.

Live Streaming

Log Format

Each line is timestamped and prefixed with the process name and instance ID:

JSON lines are automatically pretty-printed in the terminal. Pass --raw to disable pretty-printing.

FTS5 Search

mhost stores all logs in SQLite with FTS5 full-text search. Query logs without grep:

External Log Sinks

Ship logs to external systems by configuring sinks in mhost.toml:

Opens a real-time terminal UI showing CPU, memory, restart count, uptime, and log tail for every process. Use arrow keys to navigate, r to restart, s to stop, q to quit.

Web Dashboard

Configure port and basic auth in ~/.mhost/config.toml:

Health Checks

View current health status at a glance:

Metrics & Prometheus

mhost exposes a Prometheus-compatible /metrics endpoint. Enable it in ~/.mhost/config.toml:

Exported metrics include: mhost_process_cpu_percent, mhost_process_memory_bytes, mhost_process_restarts_total, mhost_process_status, mhost_health_probe_duration_ms.

Run the interactive wizard to configure any channel:

All Channels

Telegram Example

Slack Example

Event Types

Throttling & Escalation

Prevent alert storms with per-channel throttling and escalation policies:

AI Commands

Prompt Customization

Override any built-in system prompt by placing a file in ~/.mhost/prompts/:

Observe → Think → Act Loop

The agent runs a continuous loop every poll_interval:

Autonomy Levels

Telegram Conversation Examples

You can also chat with the agent directly: mhost agent ask "why is worker slow today?"

Built-in Playbooks

Add custom playbooks in ~/.mhost/brain/playbooks/my-playbook.toml.

Health Scores

Each process gets a rolling health score (0–100) computed from crash frequency, probe success rate, memory trend, and CPU stability. Scores below 40 trigger notifications; below 20 trigger the brain.

Auto-Learning

When the brain successfully remediates a novel incident, it serializes the diagnosis → action → outcome chain into a new playbook. On the next identical incident the playbook runs locally — no AI API call needed, zero latency, zero cost.

File Watching

In dev mode, mhost watches files using OS-native events (inotify on Linux, FSEvents on macOS). Configure per-process watch paths in mhost.toml:

Env File Loading

mhost merges env files in this priority order (later overrides earlier):

SSH Configuration

mhost uses your existing ~/.ssh/config by default. The key_file field is optional if the SSH agent is running.

Cloud Providers

AI Cloud Operations

Direct API integration with 10 cloud providers — no SSH required. Provision, deploy, scale, and manage services via provider APIs.

Cloud Secrets Management

Manage environment variables and secrets on cloud services without logging into provider dashboards.

Cloud Cost Tracking

Unified cost view across all configured cloud providers. See spending per service and per provider.

Configuration Drift Detection

Compare your local desired state against live cloud configuration. Optionally auto-fix detected drift.

Infrastructure Export

Export your cloud services as infrastructure-as-code for version control, migration, or disaster recovery.

Chat Commands

Permission System

Deploy Config

Hook Execution

All hooks run in the deploy path. A non-zero exit aborts the deployment and triggers rollback.

Load Balancing Strategies

TLS / ACME

mhost integrates with Let's Encrypt via the ACME protocol. Set tls = true and provide a domain — certificates are auto-provisioned and renewed.

Start new instances, wait for health checks to pass, then kill old ones. No dropped requests.

mhost reload api-server

If no health check is configured, falls back to a regular restart. If the new instances fail health checks, they are killed and the old instances are preserved.

Built-in HTTP load testing with configurable concurrency and duration.

# Default: 10 seconds, 10 concurrent workers
mhost bench https://api.example.com

# Custom settings
mhost bench https://api.example.com --duration 30 --concurrency 50

Reports total requests, requests/second, average and p99 latency, and error rate.

Scale up a canary instance, monitor for errors over a duration, then auto-promote or rollback.

# Default: 10% traffic, 300s monitoring window
mhost canary api-server

# Custom canary settings
mhost canary api-server --percent 20 --duration 600

Capture and restore full process state. Perfect for safe rollbacks before risky changes.

mhost snapshot create before-deploy    # Save current state
mhost snapshot list                    # List all snapshots
mhost snapshot restore before-deploy   # Restore a snapshot

Check SSL certificate expiry for one or more URLs. Warns when certificates expire within 30 days.

mhost certs --url https://api.example.com --url https://app.example.com

Calculate uptime from brain incident data, compare against your SLA target.

mhost sla api-server                   # Default target: 99.9%
mhost sla api-server --target 99.99    # Four-nines target

Shows uptime percentage, allowed vs actual downtime, incidents count, and budget remaining.

Replay an incident timeline for a process, showing events, log lines, and health score changes.

mhost replay api-server                # Full timeline
mhost replay api-server --time "3:47am" # Filter around a time

Visualize the dependency tree between your processes based on group configuration.

mhost link

Maps running process memory usage to EC2-equivalent instance types and estimates monthly costs.

mhost cost

Compare two fleet environments or server configs side-by-side.

mhost diff staging production

Expose a local process to the internet via tunneling services (ngrok, cloudflared, bore, serveo).

mhost share api-server                 # Auto-detect port
mhost share api-server --port 8080     # Override port

Execute a sequence of mhost commands from a text file. One command per line.

mhost run deploy-recipe.txt

Auto-convert PM2 configuration to mhost format.

mhost migrate --from pm2    # Reads ~/.pm2/dump.pm2 → generates mhost.toml

mhost exposes 25 REST endpoints on port 19516 with JSON request/response format.

# Start the API server
mhost api start --port 19516

# List processes
curl -H "Authorization: Bearer mhost_tok_..." http://localhost:19516/api/v1/processes

# Start a new process
curl -X POST -H "Authorization: Bearer mhost_tok_..." \
  -H "Content-Type: application/json" \
  -d '{"script": "server.js", "name": "api"}' \
  http://localhost:19516/api/v1/processes

Bearer token authentication with role-based access control. Tokens are hashed with Argon2 before storage.

# Create a token with a specific role
mhost api token create --name my-app --role operator

# List active tokens
mhost api token list

# Revoke a token
mhost api token revoke <id>

Four roles with increasing permissions: viewer (read-only), operator (start/stop/restart), admin (token and webhook management), super_admin (full access).

Real-time event, log, and metrics streaming over WebSocket at /api/v1/ws.

# Connect with token
wscat -c "ws://localhost:19516/api/v1/ws?token=mhost_tok_..."

# Subscribe to channels
{"type": "subscribe", "channel": "events"}
{"type": "subscribe", "channel": "logs", "process": "api-server"}
{"type": "subscribe", "channel": "metrics"}

# Unsubscribe
{"type": "unsubscribe", "channel": "events"}

Channels: events (process lifecycle), logs (stdout/stderr per process), metrics (CPU/memory snapshots).

Register HTTP endpoints to receive process events. Payloads are signed with HMAC-SHA256.

# Register a webhook
mhost api webhook add --url https://myapp.com/hook --events crash,restart --secret my-key

# List registered webhooks
mhost api webhook list

# Test a webhook
mhost api webhook test <id>

# View failed deliveries
mhost api webhook failures

Features: configurable retry with exponential backoff, dead letter logging for failed deliveries, per-webhook secret for payload verification.

Exit Codes

The daemon exposes a JSON-RPC 2.0 API over a Unix socket at ~/.mhost/mhost.sock. You can also enable an HTTP JSON-RPC endpoint.

Socket Location

Example Request

RPC Methods