Skip to main content
Glama

SPM

A simple, cross-platform manager for native system services.

SPM provides a unified command-line interface for managing native system services across Windows, Linux, and macOS.

It works with each operating system's native service manager:

  • Linux: systemd

  • macOS: launchd

  • Windows: Windows Services

SPM aims to make service management consistent, simple, and intuitive across platforms.

Built for coding agents

Coding agents such as Claude Code, Codex, and Cursor often start dev servers and workers with & or nohup. Those processes die or become orphans when the session ends, and their output is lost. With spm, an agent starts them as real native services instead: they keep running, restart on crash and at login, and their logs stay readable through spm logs or the built-in MCP server.

claude plugin marketplace add eyvant/spm && claude plugin install spm@eyvant-spm
codex mcp add spm -- spm mcp

Install in Cursor Install in VS Code

Install spm itself first (see Install). See Agent and MCP integration for every client.

Under the hood, Linux uses systemd and journald, macOS uses launchd LaunchAgents or LaunchDaemons, and Windows uses per-user supervisors with Startup integration or native SCM services for system scope.

User services do not require elevation. Use --system explicitly when a service must run at the machine level.

Install

Install the latest release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh

The installer verifies the release checksum, installs spm to ~/.local/bin, and installs completion for the shell named by $SHELL when it is Bash, Zsh, or Fish. Make sure ~/.local/bin is in PATH.

Choose a completion shell explicitly, or skip completion installation:

curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --completion bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --no-completion

The SPM_COMPLETION environment variable also accepts auto, bash, zsh, fish, or none.

On Windows, run PowerShell:

irm https://github.com/eyvant/spm/releases/latest/download/install.ps1 | iex

The Windows installer verifies the release checksum, installs spm.exe under %LOCALAPPDATA%\Programs\spm, adds it to the user PATH, and installs dynamic PowerShell completion. Use install.ps1 -NoCompletion or -NoPath when needed.

Uninstall SPM on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --uninstall

Uninstall SPM on Windows:

& ([scriptblock]::Create((irm https://github.com/eyvant/spm/releases/latest/download/install.ps1))) -Uninstall

The uninstallers remove the executable, installed shell completion, and—on Windows—the PowerShell profile entry and user PATH entry. They do not delete managed services or their data. If services still exist, uninstall stops and asks you to delete them first (spm delete all --yes, and sudo spm --system delete all --yes when applicable); use --force or -Force only when you intentionally want to leave those services behind.

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | \
  sh -s -- --version v0.1.0

Upgrading

Run the installer again; it works while services are running.

spm itself is only the command-line tool. Background work is done by two small runtimes installed next to it:

Runtime

Platforms

Runs

spm-supervisor

Windows

every service (systemd and launchd supervise services elsewhere)

spm-scheduler

Windows, macOS

the scheduler daemon and every scheduled-job run

Release builds of the runtimes are reproducible, and the installer replaces a runtime only when its file differs from the installed one. Most upgrades therefore replace just the CLI and restart nothing; a runtime changes when its code, a dependency or the Go toolchain release changes. spm-supervisor version and spm-scheduler version print the start of the file's SHA-256. When a runtime does change:

  • spm-scheduler: the scheduler daemon is restarted. Services are not touched, and a job that is running finishes normally; its next run uses the new version.

  • spm-supervisor: each running service is handed over to the new supervisor without being stopped. The old supervisor detaches and leaves the process running; the new one adopts it, keeping its start time and restart count. For system services the installer asks for Administrator approval once.

    An upgrade never restarts a service on its own. A service that cannot be handed over (for example one still running on the supervisor from spm 0.3.6 or earlier) keeps running on its current supervisor, and the installer reports it with the commands that move it over when a short interruption suits you: spm stop <name> then spm run <name>. If the new supervisor fails to start, the previous one takes the service back. Pass -RestartServices to restart services that cannot be handed over instead.

On macOS, system jobs need sudo. Linux needs neither runtime. Pass -NoRestart (Windows) or --no-restart (macOS) to keep running processes on the previous runtime until you restart them yourself.

Or install from source with Go 1.27 or later (the runtimes must sit next to spm, which go install does):

go install github.com/eyvant/spm/cmd/...@latest

Verify the installation:

spm version
spm doctor

Related MCP server: cs-agent-mcp

Start your first service

From the directory containing your application:

spm start ./my-server --name my-server

On Linux, that one command:

  1. Creates a native systemd user service.

  2. Uses the current directory as its working directory.

  3. Starts the process immediately.

  4. Enables it to start again with the user manager.

  5. Restarts it if it exits.

  6. Sends stdout and stderr to journald.

On Windows it creates an equivalent user service: a detached supervisor owns the process and its restart policy, a hidden Startup shortcut launches enabled services at logon, and output is written below %APPDATA%\spm\services\NAME.

On macOS it creates a LaunchAgent in ~/Library/LaunchAgents; output and saved configuration live under the user's Application Support directory.

User and system services

The default scope is per-user on all platforms:

  • Linux: runs under the systemd user manager and stores units in ~/.config/systemd/user.

  • Windows: runs as the current account, stores state in %APPDATA%\spm, and starts when that user logs on.

  • macOS: runs as the current account through a LaunchAgent and starts at login.

--system selects machine-wide services:

  • Linux: requires root and stores units in /etc/systemd/system.

  • Windows: requires an Administrator terminal, stores state in %ProgramData%\spm, and starts at boot without a user login. The default account is LocalSystem. Each service gets a private supervisor executable and data directory so its account does not depend on an administrator's profile or gain access to another service's configuration.

  • macOS: requires root, installs a LaunchDaemon in /Library/LaunchDaemons, stores state in /Library/Application Support/spm, and starts at boot.

Windows system services can select an account:

spm --system start --user LocalService --name api -- .\api.exe
spm --system start --user NetworkService --name proxy -- .\proxy.exe
spm --system start --user 'DOMAIN\svc-api' --name api -- .\api.exe
spm --system start --user 'DOMAIN\svc-api$' --name api -- .\api.exe
spm --system start --user 'NT SERVICE\spm-api' --name api -- .\api.exe

Aliases for SYSTEM, LocalSystem, LocalService, and NetworkService are accepted, as are group Managed Service Accounts (gMSA, ending in $) and NT SERVICE\... virtual accounts. For a regular local or domain user, spm grants SeServiceLogonRight, prompts securely, and passes the credential directly to SCM; spm never writes it to its configuration. System services are visible in services.msc. spm restricts %ProgramData%\spm ACLs to Administrators, SYSTEM, and the selected service account. --group is Unix-specific and rejected on Windows.

Check it:

spm list
spm logs my-server -f
spm show my-server

Manage it later from any directory:

spm restart my-server
spm stop my-server
spm start my-server
spm delete my-server

For services that must survive logout and start after a reboot, run this once:

spm startup

spm detects whether user lingering is already enabled and only prints a reminder when action is needed.

Common examples

Node.js

spm start app.js --name api

Use the explicit command form when the application needs arguments:

spm start --name api -- node app.js --port 3000

Python, Ruby, shell, and custom interpreters

spm start worker.py --name worker
spm start server.rb --name web
spm start cleanup.sh --name cleanup
spm start worker.ps1 --name windows-worker
spm start worker.ts --name typescript-worker --interpreter bun

spm recognizes .js, .mjs, .cjs, .py, .rb, .sh, and .ps1. PowerShell scripts use Windows PowerShell on Windows and pwsh on Linux or macOS. Use --interpreter to override the default or handle another type.

Native commands and application arguments

Put a complete command after --:

spm start --name proxy -- /opt/proxy/bin/proxy --port 8080 --verbose

Everything after -- belongs to the application, even when an argument has the same name as an spm option:

spm start --name public-api -- ./server --name internal-api --port 3000

Working directory and environment

spm start app.js \
  --name api \
  --cwd /opt/api \
  --env NODE_ENV=production \
  --env-file /opt/api/.env \
  --restart always \
  --restart-sec 5s

Use --env-file for secrets. Values passed with --env are stored in the generated unit and saved configuration.

Which command should I use?

Goal

Command

Keep a process running

spm start

Run a job on a schedule and let it exit

spm schedule

Restart a long-running service periodically

spm start --cron-restart

Run a service as root or another system user

sudo spm --system start

Manage several services from a file

spm apply spm.toml

The distinction between start and schedule is important: use start for servers and workers, and schedule for backups, checks, synchronization jobs, and other commands that finish.

Everyday commands

Command

Purpose

spm list

List managed services

spm list --watch

Continuously refresh CPU, memory, and status

spm show NAME

Show an spm configuration and runtime summary

spm status NAME

Show native systemctl status output

spm logs NAME -f

Follow logs

spm restart NAME

Restart using the current unit

spm restart --update NAME

Regenerate the unit from saved configuration, then restart

spm stop NAME

Stop now, but keep boot enablement

spm disable NAME

Stop and disable boot startup

spm enable NAME

Enable and start

spm delete NAME

Stop and remove the service and companion units

spm cat NAME

Print the generated unit and drop-ins

spm edit NAME

Open a persistent systemd drop-in editor

Lifecycle commands accept several names or all:

spm restart api worker
spm stop all
spm delete all --yes

all only selects units created by spm. Deleting all services requires --yes.

Logs

spm logs api                 # last 100 entries
spm logs api -n 20           # last 20 entries
spm logs api -f              # follow
spm logs api worker -f       # merge several services
spm logs                     # merge all spm services
spm logs api --since 1h --grep ERROR
spm logs api --boot --output json

Windows/macOS scheduled-task output (service.log) and scheduler diagnostics (scheduler.log) rotate at 10 MiB and retain five backups (.1 through .5). Rotation is applied while data is being written, including during one long-running scheduled invocation. Linux log capacity remains controlled by journald.

Change an existing service

Repeat the original start command with --force:

spm start app.js --name api --env NODE_ENV=production --force

Settings omitted from a --force update are normally inherited. Clear them explicitly when needed:

spm start app.js --name api --force --clear-env
spm start app.js --name api --force --no-cron-restart
spm start app.js --name api --force --no-max-memory

Small changes can also use set and unset:

spm set api --env NODE_ENV=production --restart-sec 5s
spm unset api --env OLD_KEY

spm keeps previous saved configurations:

spm history api
spm rollback api
spm rollback api --revision 2
spm clone api api-test

Scheduled jobs

Create a oneshot job that runs every 30 minutes:

spm schedule --name checker \
  --cron "*/30 * * * *" \
  --persistent \
  -- node ./scripts/check.js

Run it once immediately without waiting for the timer:

spm run checker

Or run immediately while creating the schedule:

spm schedule --name checker --cron "*/30 * * * *" \
  --run-now -- node ./scripts/check.js

Interval timers are also supported:

spm schedule --name cache-sync \
  --on-boot 5min \
  --interval 30min \
  --randomized-delay 2min \
  -- ./sync-cache

--persistent catches up a missed calendar run after downtime. --randomized-delay helps avoid many hosts starting the same job together. Use --timezone Asia/Singapore with --cron when the server's local timezone is not appropriate.

Scheduling is available on Linux, Windows, and macOS. Portable cron expressions use either five fields (minute hour day month weekday) or six fields (second minute hour day month weekday) and support numbers, *, lists, ranges, and steps. Windows and macOS use one on-demand scheduler per user/system scope; it sleeps until the nearest occurrence and asks Task Scheduler or launchd to run the task under its declared account. Linux continues to use native systemd timers. Five-field expressions remain compatible and run at second zero.

For example, this six-field expression runs every day at 04:00:30:

spm schedule --name precise --cron "30 0 4 * * *" -- ./job

Periodically restart a long-running service

This is different from a scheduled job:

spm start server.js --name api \
  --cron-restart "0 4 * * *" \
  --timezone Asia/Singapore

spm creates and manages a companion systemd timer. Cron expressions use five fields or six fields with leading seconds. Generated systemd calendar expressions are validated before installation.

System services

User mode is the default and does not need sudo. Use system mode only when the process needs system-level privileges, ownership, or dependencies:

sudo spm --system start /opt/api/server --name api
sudo spm --system status api
sudo spm --system logs api -f
sudo spm --system restart api

Run a system service as a non-root account:

sudo spm --system start /opt/api/server \
  --name api \
  --user www-data \
  --group www-data

The executable, working directory, environment file, and writable paths must be accessible to that account. spm resolves relative commands using the target user's home directory and search paths.

Important rules:

  • Put global --system before the command.

  • Keep using --system for every later operation on that service.

  • User and system services are separate namespaces and may have the same name.

  • Do not run sudo spm without --system; that targets root's user manager instead of the system manager.

User units live in ~/.config/systemd/user. System units live in /etc/systemd/system.

Declarative configuration

Use spm.toml when several services should be reviewed and applied together:

schema = 1

[[services]]
name = "api"
command = ["node", "app.js", "--port", "3000"] # common defaults
restart = "always"
restart_sec = "3s"

[services.linux]
cwd = "/opt/api"
max_memory = "512M"

[services.windows]
cwd = "C:\\apps\\api"

[services.macos]
cwd = "/Applications/api"

[[services]]
name = "worker"
cwd = "/opt/worker"
script = "worker.py"
args = ["--queue", "default"]
interpreter = "python3"
enable = false

[[services]]
name = "database"
command = ["./database"]

[[services]]
name = "frontend"
command = ["./frontend"]
requires = ["database"]
after = ["database"]

[[services]]
name = "backup"
command = ["./backup", "--incremental"]
schedule = "0 2 * * *"
timezone = "Asia/Singapore"
persistent = true

Common values apply everywhere. [services.linux], [services.windows], and [services.macos] only override fields that genuinely differ. All platform blocks are syntax-checked, while each host applies its own block. Dependencies use the same after, wants, and requires fields: systemd receives native dependencies; when spm starts services, Windows and macOS use ordered spm orchestration. Their native boot/login managers may activate enabled jobs in parallel, so applications should still tolerate concurrent machine startup.

The common UI remains the default. Platform-native details stay available through an explicit escape hatch:

spm native systemd status api       # Linux
spm native windows inspect api      # Windows
spm native launchd print api        # macOS

Preview and apply:

spm validate spm.toml
spm diff spm.toml
spm apply --dry-run spm.toml
spm apply spm.toml

Export existing services:

spm export all > spm.toml

Apply is declarative for services present in the file: omitted optional settings return to defaults. Services not listed in the file are not deleted. The file's directory is the default working directory.

Readiness and health checks

Wait for an application to become ready during spm start:

spm start --name api \
  --wait-http http://127.0.0.1:3000/health \
  --wait-timeout 30s \
  -- node server.js

HTTP, TCP, and command readiness probes are available through --wait-http, --wait-tcp, and --wait-command. They run in the invoking spm process and do not create background services.

Add a periodic health check:

spm start --name api \
  --health-http http://127.0.0.1:3000/health \
  --health-interval 30s \
  --health-timeout 5s \
  --health-retries 3 \
  --health-action restart \
  -- node server.js

Inspect health state and logs:

spm health api
spm logs api --health

Periodic checks use short-lived systemd oneshot units and timers; spm still does not run a daemon. The default action is none, which only records failures. Available actions are none, restart, and stop.

Resource limits and security

Resource options map directly to systemd cgroup controls:

spm start --name api \
  --max-memory 512M \
  --max-cpu 200% \
  --max-tasks 100 \
  --open-files 65535 \
  -- node server.js

--max-memory is a hard cgroup limit. If the process is OOM-killed, its restart policy determines whether it starts again.

Apply a security preset:

spm start --name api --sandbox basic -- node server.js
spm security api

basic protects the home directory and system paths. strict adds kernel, module, and SUID restrictions. The working directory remains writable. User-mode sandboxing requires unprivileged user namespaces; run spm doctor to check support.

Advanced systemd settings are available without editing a unit:

spm start --name api \
  --after network-online.target \
  --requires redis.service \
  --exec-start-pre '/usr/bin/test -f /opt/api/config.json' \
  --exec-reload '/bin/kill -HUP $MAINPID' \
  --property Nice=5 \
  -- node server.js

spm reload api

Core properties controlled by spm, such as ExecStart, WorkingDirectory, Environment, Restart, and User, cannot be overridden with --property.

Multiple instances

Run several fork-mode instances with a systemd template unit:

spm start server.js --name api --instances 4 \
  --env 'PORT=300{{instance}}'

spm scale api 8
spm restart api
spm logs api -f

Each instance receives SPM_INSTANCE and NODE_APP_INSTANCE. {{instance}} is replaced in arguments, environment values, and PID files. Restarts are rolling and scaling leaves unchanged instances running.

This is not PM2 cluster mode: instances do not share a listening socket. Give each instance a different port behind a load balancer, or make the application use SO_REUSEPORT. Instances cannot currently be combined with schedules, cron restart, readiness probes, or health checks.

Optional: mise integration

If a project uses mise, add --mise to run the application through mise exec --:

cd /opt/my-app
mise install
spm start --name api --mise -- node app.js --port 3000

The shorter script form works too:

spm start app.js --name api --mise

spm does not pin the resolved Node.js or other tool binary. Tool versions and [env] from mise.toml are reevaluated whenever the service starts. After changing a version, use a normal restart:

mise use node@24
spm restart api

Use --no-mise with --force to remove an inherited mise setting. In system mode with --user, spm finds mise from the target user's home directory and search paths instead of root's environment.

Snap normally launches mise through snap run, which can move child processes out of the service cgroup. spm detects a classic Snap installation and invokes its internal mise executable directly, preserving process cleanup, resource accounting, limits, and unit-scoped logs.

mise support is optional. spm does not install mise or any language runtime.

Native systemd access

spm creates ordinary systemd units, so native tools continue to work:

systemctl --user status spm-api.service
journalctl --user --unit spm-api.service --follow
systemctl --user cat spm-api.service

spm status intentionally shows native systemctl output. spm show and spm describe show the friendlier spm summary. spm cat prints the final unit, while spm edit stores manual changes in a drop-in that survives spm start --force.

Existing simple units can be imported:

spm import /etc/systemd/system/api.service --name api

spm refuses unit semantics it cannot preserve safely, such as socket activation and oneshot services.

Saved normalized configurations use mode 0600 and live in:

~/.config/spm/services/<name>.json
/etc/spm/services/<name>.json    # system mode

PM2 command map

PM2

spm

pm2 start index.js --name api

spm start index.js --name api

pm2 ls

spm list

pm2 show api

spm show api

pm2 logs api

spm logs api -f

pm2 restart api

spm restart api

pm2 reload api

spm reload api

pm2 stop api

spm stop api

pm2 delete api

spm delete api

pm2 sendSignal SIGUSR2 api

spm signal SIGUSR2 api

pm2 jlist

spm list --json

pm2 monit

spm list --watch

pm2 start app.js -i 4 in fork mode

spm start app.js -i 4

pm2 scale api 8

spm scale api 8

pm2 startup

spm startup

pm2 save

Not needed; spm enables services when they are created.

PM2 ecosystem file

spm export all > spm.toml, then spm apply spm.toml

Agent and MCP integration

spm includes a local stdio MCP server so Codex and other MCP clients can inspect and manage services through focused, structured tools:

spm mcp

The repository also ships an agent skill, plugins/spm/skills/spm/SKILL.md, that teaches an agent to start long-lived processes with spm instead of & or nohup, to check them with bounded log reads, and to ask before deleting or using --system. Any agent that reads SKILL.md files can use it; copy the spm directory into the agent's skills folder (for example ~/.claude/skills/ or ~/.codex/skills/).

Claude Code plugin

The plugin bundles the MCP server and the skill:

claude plugin marketplace add eyvant/spm
claude plugin install spm@eyvant-spm

Inside a session, /plugin marketplace add eyvant/spm does the same. The plugin runs the spm on your PATH, so install spm first.

Codex

Add it to Codex after installing spm:

codex mcp add spm -- spm mcp

Or add the server directly to ~/.codex/config.toml (or a trusted project's .codex/config.toml):

[mcp_servers.spm]
command = "spm"
args = ["mcp"]
default_tools_approval_mode = "writes"

Restart the Codex client after changing its configuration. The server exposes read-only tools for listing, inspecting, diagnostics, and bounded log reads, plus focused write tools for creating and controlling services. The spm_run_cli escape hatch covers all other non-interactive CLI functionality, including schedules, signals, scaling, configuration revisions, declarative apply/diff, import/export, health, and native inspection. Interactive editors and unbounded logs --follow or list --watch calls are intentionally rejected because an MCP tool call must finish. The general CLI tool and service deletion are marked destructive so MCP hosts can request approval. Machine-wide calls use the tool's system option and remain subject to normal platform privilege checks.

Claude Code without the plugin

claude mcp add spm -- spm mcp

Run /mcp inside Claude Code to verify that the server is connected and its tools are available.

Cursor and VS Code

Use the install buttons in Built for coding agents, or add {"command": "spm", "args": ["mcp"]} as a stdio server named spm in .cursor/mcp.json or VS Code's mcp.json (under servers).

Claude Desktop

For Claude Desktop, add the following entry to claude_desktop_config.json and fully restart the app:

{
  "mcpServers": {
    "spm": {
      "command": "spm",
      "args": ["mcp"]
    }
  }
}

Claude Desktop may start with a minimal PATH. If it cannot find spm, replace the command with the absolute path to spm or spm.exe. On Windows the config file is normally %APPDATA%\Claude\claude_desktop_config.json; on macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json.

Secrets should stay in an environment file referenced by env_file; do not put secret values directly in MCP tool arguments.

Shell completion

Bash:

mkdir -p ~/.local/share/bash-completion/completions
spm completion bash > ~/.local/share/bash-completion/completions/spm.bash

Zsh:

mkdir -p ~/.zfunc
spm completion zsh > ~/.zfunc/_spm
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Fish:

mkdir -p ~/.config/fish/completions
spm completion fish > ~/.config/fish/completions/spm.fish

Completion understands subcommands, options, enum values, and managed service names. It switches to system services when --system is present.

PowerShell:

spm completion powershell | Out-String | Invoke-Expression

Troubleshooting

Start with:

spm doctor
spm status NAME
spm logs NAME -n 100

For system mode:

sudo spm --system doctor
sudo spm --system status NAME

doctor checks systemd features, manager access, XDG_RUNTIME_DIR, lingering, journald, unit permissions, mise, user namespaces, and whether the spm executable path is stable. FAIL returns a non-zero exit status; WARN reports a risk without failing.

Every command also has focused help:

spm --help
spm start --help
spm schedule --help
spm logs --help

Build and test

go test -race ./...
go vet ./...
go build -o spm ./cmd/spm

Release builds inject the version with ldflags:

go build \
  -ldflags "-X github.com/eyvant/spm/internal/app.version=0.1.0" \
  -o spm ./cmd/spm

GitHub Actions runs tests, vet, builds, and real lifecycle integration tests on Ubuntu, Windows Server, and macOS runners. Every platform exercises user and system scopes, lifecycle operations, logs, restart behavior, dependencies, and declarative validate/apply/diff. Linux additionally verifies native systemd units and timers, Windows verifies Startup shortcuts, SCM dependencies and service accounts, and macOS verifies LaunchAgents and LaunchDaemons. Releases include Linux, Windows, and macOS archives.

License

spm is available under the MIT License.

Current limitations

  • Linux requires systemd. Windows 10/11 and Windows Server use the per-user Startup folder and the Service Control Manager. macOS uses launchd.

  • Windows currently supports the core lifecycle, logs, restart policies, readiness checks, user/system scopes, and selectable system accounts. Health timers, instances, resource limits, and systemd unit import remain Linux-specific. Scheduled system tasks on Windows currently use SYSTEM, LocalService, or NetworkService. macOS supports the common lifecycle, logs, declarations, restart policies, readiness checks, dependencies, and both LaunchAgent and LaunchDaemon scopes.

  • Cross-platform schedules use native activation plus shared SPM semantics; see the scheduling design.

  • PM2 cluster-mode socket sharing, watch mode, deployment, and remote management are not implemented.

  • --instances provides fork-mode instances, not PM2 cluster mode.

  • spm does not install language runtimes or runtime managers.

Available Tools

12 tools
spm_create_serviceCreate serviceA

Create a new persistent service from a command and start it immediately. By default it restarts when it exits and starts again at login, so use it instead of running long-lived processes in the background (&, nohup, start /b) for dev servers, workers and bots that must outlive the session. Use spm_start_service or spm_enable_service for a service that already exists. If the name is taken the call fails; set force=true only after the user agrees to replace that service. Put secrets in an env_file, never in command arguments. Afterwards, call spm_get_logs to confirm it started. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), command (required), cwd, force, +3 more.

spm_delete_serviceDelete serviceA
Destructive

Stop a managed service and permanently remove its definition, saved configuration and companion units such as schedules and health checks. This cannot be undone; the service must be created again with spm_create_service. Confirm the exact name and scope with the user first, and prefer spm_stop_service or spm_disable_service when the user may need it again. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_disable_serviceDisable serviceA

Stop a managed service and turn off start at login or boot, so it stays stopped until enabled again. Its definition is kept and spm_enable_service brings it back. Use spm_stop_service for a temporary stop, or spm_delete_service to remove it completely. For a scheduled job, this disables its timer. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_doctorDiagnose spmA
Read-only

Check that spm can manage services in the chosen scope: whether the service manager is reachable and recent enough, the unit directory, log access, login persistence and the spm executable; the exact checks depend on the platform. Use it when a create, start or list call fails unexpectedly, or before the first service on a new machine; use spm_get_logs for problems inside one service. Returns one line per check marked ok, info, warn or fail, with details on what is wrong. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: system.

spm_enable_serviceEnable serviceA

Turn on start at login or boot for an existing managed service, and start it now. Use it to undo spm_disable_service; use spm_start_service to run a service now without changing its startup setting. For a scheduled job, this re-enables its timer. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_get_logsGet service logsA
Read-only

Read recent log lines from one or more managed services. Use it to check that a service started cleanly, to find why it crashed or keeps restarting, or to read its output such as URLs, ports and errors; use spm_doctor instead when spm itself or the service manager seems broken. Returns at most lines entries (default 100) as text; with several names, their entries are combined. Set health=true to read health-check output instead of service output. It never follows logs, so call it again to see newer lines. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: grep, lines, names, since, +2 more.

spm_list_servicesList servicesA
Read-only

List every service spm manages in the chosen scope with its live state. Call this first to see what is running, to find an exact service name, or to confirm the effect of a create, start, stop or delete; use spm_show_service for one service's full configuration. Returns structuredContent.services with one entry per unit (a multi-instance service has one entry per instance): name, status, active_state, sub_state, health, pid, cpu_percent, memory_bytes, restarts, enabled, uptime_seconds, and schedule for scheduled jobs. Values the platform cannot report are null. An empty array means no services exist in that scope. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: system. Returns: services

spm_restart_serviceRestart serviceA

Stop and start a managed service so it picks up new code, configuration or environment. The process gets a new PID and is briefly unavailable; a multi-instance service is restarted one instance at a time so the others keep serving. A stopped service is simply started. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_run_cliRun advanced spm commandA
Destructive

Run any supported non-interactive spm CLI operation, including schedule, signal, scale, set, unset, clone, history, rollback, apply, validate, diff, native inspection, security analysis, export, health, and import. Prefer focused tools when one exists. Interactive editors and unbounded watch/follow modes are rejected. Returns the command's text output; run ["help", ""] first to see a command's options. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: arguments (required), system.

spm_show_serviceShow serviceA
Read-only

Show one managed service in detail as key-value text: status, enabled, PID, memory, restarts, uptime, last result and exit status, schedule, health, its saved configuration (command, working directory, restart policy and other options), and the paths of its unit and config files. Use it before changing or deleting a service, or to find out how a service was started; use spm_list_services to compare many services and spm_get_logs to see why one failed. Fails if the name is not managed by spm in that scope. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_start_serviceStart serviceA

Start an existing managed service that is stopped. It does not change whether the service starts at login; use spm_enable_service to start it and turn that on, or spm_create_service for a service that does not exist yet. A service that is already running is left as it is; use spm_restart_service to pick up code or configuration changes. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

spm_stop_serviceStop serviceA

Stop a running managed service for now. It keeps its definition and still starts again at the next login or boot if it is enabled; use spm_disable_service to keep it stopped, or spm_delete_service to remove it. For a scheduled job, this also stops its timer. Acts on the current user's services unless system is true; machine-wide services need root on Linux and macOS or an Administrator shell on Windows, so only use system when the user asks for it.

Inputs: name (required), system.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct service-management action; start vs enable and stop vs disable are explicitly differentiated in their descriptions, and spm_run_cli is positioned as a fallback only when no focused tool exists. No two tools appear to do the same thing.

    Naming Consistency4/5

    All tools use the spm_ prefix and snake_case, with a consistent verb_noun pattern for lifecycle and query operations. spm_doctor is the only noun-only name, a minor deviation from the otherwise predictable convention.

    Tool Count5/5

    Twelve tools is well within the appropriate range for a service manager, covering discovery, inspection, lifecycle, diagnostics, and an escape hatch without bloat. Each tool earns its place.

    Completeness5/5

    The set covers create/read/update/delete and full lifecycle operations (start, stop, restart, enable, disable), plus logs and diagnostics; configuration updates and advanced operations are available through spm_run_cli. No obvious dead ends exist for the stated domain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Multi-machine system monitor with a built-in MCP server that enables AI agents to query health metrics, manage processes, schedule cron jobs, and run diagnostics across local and remote machines.
      133 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      A lightweight, cross-platform MCP server for managing background processes. Enables AI coding agents to spawn, monitor, and interact with long-lived processes.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely create, manage, and monitor local processes such as dev servers, docker-compose, and test watchers, including restarting, checking status, and retrieving logs via MCP, HTTP, or WebSocket messaging.
      27 npm
      1
      MIT