mac-agents-manager-ai 1.2.2

A web UI for managing macOS LaunchAgents -- create, edit, start, stop, and reload agents from your browser

Mac Agents Manager

Web UI and CLI for managing macOS LaunchAgents.

Mac Agents Manager lets you create, view, edit, start, stop, and reload user LaunchAgents from a web dashboard or the mam CLI — no manual plist editing or raw launchctl commands required.

Features

• Web Dashboard — Modern browser UI to browse, create, edit, and control LaunchAgents on localhost
• Unified CLI — Single mam command for all operations (list, create, start, stop, logs, delete)
• LaunchAgent Lifecycle — Load, unload, start, stop, restart, and delete agents with one command
• Agent Creation — Create new keepalive or scheduled LaunchAgents from the CLI or web UI
• Log Viewer — Tail stdout/stderr logs for any agent with follow mode
• Auto-Start — Install Mac Agents Manager itself as a LaunchAgent so the dashboard starts at login
• Localhost Only — Binds to 127.0.0.1 for single-user, local-only access

How It Works

┌────────────────────────────────────────────────────────────────┐
│                           Your Mac                             │
│                                                                │
│   🖥️ Web Dashboard (localhost:8081)    ⌨️ CLI (mam)            │
│   ├─ Browse all LaunchAgents           ├─ mam list             │
│   ├─ Create / Edit agents              ├─ mam create           │
│   ├─ Start / Stop / Restart            ├─ mam start <label>    │
│   └─ View logs                         └─ mam logs <label>     │
│           │                                    │               │
│           └────────────┬───────────────────────┘               │
│                        ▼                                       │
│      ┌───────────────────────────────────────────────┐         │
│      │      ~/Library/LaunchAgents/*.plist            │         │
│      │  User LaunchAgent property list files          │         │
│      └───────────────────────┬───────────────────────┘         │
│                              │                                 │
│                              ▼                                 │
│      ┌───────────────────────────────────────────────┐         │
│      │            launchctl (macOS)                   │         │
│      │  Load · Unload · Start · Stop · Status         │         │
│      └───────────────────────────────────────────────┘         │
│                                                                │
│      Everything runs locally. Nothing leaves your machine.     │
└────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• macOS (uses macOS-specific launchctl APIs)
• Python 3.10+ — check with python3 --version. If below 3.10, install it:

  brew install python@3.10
  

Install

# From PyPI
pip3 install mac-agents-manager-ai

# Or with uv
uv pip install mac-agents-manager-ai

# Or in a dedicated virtual environment
mkdir -p ~/.mac_agents_manager
python3 -m venv ~/.mac_agents_manager/venv
source ~/.mac_agents_manager/venv/bin/activate
pip install mac-agents-manager-ai

Run

# Install as macOS service (auto-start at login)
mam service install

# Or start manually
mam serve

# Open the dashboard
mam open

The dashboard is at http://localhost:8081.

Verify

# Check service status
mam service status

# List all LaunchAgents
mam list

# Check version
mam --version

CLI Reference

mam                              # Start web server (default)
mam serve [-p PORT] [--debug]    # Start web server
mam service install              # Install as LaunchAgent (auto-start at login)
mam service uninstall            # Uninstall the LaunchAgent
mam service start|stop|restart   # Control the LaunchAgent service
mam service status               # Show service status
mam list                         # List all agents with status
mam show <label>                 # Show agent details and plist XML
mam create <name> -c CAT -s SCRIPT [-t keepalive|scheduled]
mam load <label>                 # Register agent with launchd
mam unload <label>               # Unregister agent from launchd
mam start <label>                # Start a loaded agent
mam stop <label>                 # Stop a running agent
mam restart <label>              # Restart an agent
mam delete <label> [-y]          # Unload and delete an agent
mam start-all                    # Start all stopped keepalive agents
mam logs <label> [-f] [--stderr] [-n N]  # View agent logs
mam open                         # Open dashboard in browser
mam --version                    # Version info

Architecture

src/mac_agents_manager/
├── __init__.py       # Package version
├── cli.py            # Unified CLI (argparse)
├── app.py            # Flask web dashboard and routes
├── models.py         # LaunchAgent parsing, serialization, and UI data
├── launchctl.py      # Thin wrapper around launchctl commands
├── templates/        # HTML templates (Jinja2)
└── static/           # CSS styles

Environment Variables

Variable	Default	Description
MAM_PORT	8081	Port to listen on
FLASK_DEBUG	off	Set to 1 or true to enable Flask debug mode
MAM_LABEL_PREFIXES	—	Comma-separated extra label prefixes to include (e.g. com.myorg.,com.acme.)

Security

This tool binds to 127.0.0.1 only and is designed for single-user, localhost use. See SECURITY.md for the full security model and vulnerability reporting instructions.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request. This project follows the Contributor Covenant Code of Conduct.

Development

# Clone and install in dev mode
git clone https://github.com/pkasinathan/mac-agents-manager.git
cd mac-agents-manager
make dev

# Run linter
make lint

# Auto-format
make format

# Run tests
make test

# All quality checks
make check

Uninstall

mam service uninstall
pip3 uninstall mac-agents-manager-ai
rm -rf ~/.mac_agents_manager

License

Apache License 2.0 — see LICENSE.