spm
This MCP server exposes tools to inspect and manage native system services (Linux systemd, macOS launchd, Windows Services) via spm, including lifecycle control, log reading, diagnostics, and an escape hatch to run arbitrary non-interactive spm CLI commands.
List services (
spm_list_services): enumerate managed services and their runtime state as JSON.Inspect a service (
spm_show_service): view configuration and runtime details for a named service.Read logs (
spm_get_logs): fetch a bounded number of recent service or health-check log entries (1–1000 lines), with optional grep,sincetime filter, multiple service names, and health-log mode; never streams/follows.Diagnose environment (
spm_doctor): run spm environment and service-manager diagnostics.Create a service (
spm_create_service): define and start a persistent service from an explicit command array, with options for working directory, restart policy, environment file (for secrets), andforceto replace an existing definition.Control lifecycle: start, restart, stop (keeping boot enablement), enable (enable + start), and disable (stop + disable boot startup) a managed service.
Delete a service (
spm_delete_service): stop and permanently remove a service and its companion units (marked destructive).Run advanced commands (
spm_run_cli): execute any supported non-interactive spm CLI operation—schedules, signals, scaling, set/unset, clone, history, rollback, declarative apply/validate/diff, native inspection, security analysis, export, health, and import—while rejecting interactive editors and unbounded watch/follow modes (marked destructive and open-world).Scope selection: every tool accepts a
systemflag to target machine-wide services instead of the current user's services (subject to normal platform privilege checks).
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 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
--systemexplicitly 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 | shThe 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-completionThe 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 | iexThe 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 -- --uninstallUninstall SPM on Windows:
& ([scriptblock]::Create((irm https://github.com/eyvant/spm/releases/latest/download/install.ps1))) -UninstallThe 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.0Upgrading
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 |
| Windows | every service (systemd and launchd supervise services elsewhere) |
| 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>thenspm run <name>. If the new supervisor fails to start, the previous one takes the service back. Pass-RestartServicesto 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/...@latestVerify the installation:
spm version
spm doctorRelated MCP server: cs-agent-mcp
Start your first service
From the directory containing your application:
spm start ./my-server --name my-serverOn Linux, that one command:
Creates a native systemd user service.
Uses the current directory as its working directory.
Starts the process immediately.
Enables it to start again with the user manager.
Restarts it if it exits.
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 isLocalSystem. 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.exeAliases 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-serverManage it later from any directory:
spm restart my-server
spm stop my-server
spm start my-server
spm delete my-serverFor services that must survive logout and start after a reboot, run this once:
spm startupspm 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 apiUse the explicit command form when the application needs arguments:
spm start --name api -- node app.js --port 3000Python, 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 bunspm 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 --verboseEverything 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 3000Working 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 5sUse --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 |
|
Run a job on a schedule and let it exit |
|
Restart a long-running service periodically |
|
Run a service as root or another system user |
|
Manage several services from a file |
|
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 |
| List managed services |
| Continuously refresh CPU, memory, and status |
| Show an spm configuration and runtime summary |
| Show native |
| Follow logs |
| Restart using the current unit |
| Regenerate the unit from saved configuration, then restart |
| Stop now, but keep boot enablement |
| Stop and disable boot startup |
| Enable and start |
| Stop and remove the service and companion units |
| Print the generated unit and drop-ins |
| Open a persistent systemd drop-in editor |
Lifecycle commands accept several names or all:
spm restart api worker
spm stop all
spm delete all --yesall 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 jsonWindows/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 --forceSettings 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-memorySmall changes can also use set and unset:
spm set api --env NODE_ENV=production --restart-sec 5s
spm unset api --env OLD_KEYspm keeps previous saved configurations:
spm history api
spm rollback api
spm rollback api --revision 2
spm clone api api-testScheduled jobs
Create a oneshot job that runs every 30 minutes:
spm schedule --name checker \
--cron "*/30 * * * *" \
--persistent \
-- node ./scripts/check.jsRun it once immediately without waiting for the timer:
spm run checkerOr run immediately while creating the schedule:
spm schedule --name checker --cron "*/30 * * * *" \
--run-now -- node ./scripts/check.jsInterval 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 * * *" -- ./jobPeriodically restart a long-running service
This is different from a scheduled job:
spm start server.js --name api \
--cron-restart "0 4 * * *" \
--timezone Asia/Singaporespm 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 apiRun a system service as a non-root account:
sudo spm --system start /opt/api/server \
--name api \
--user www-data \
--group www-dataThe 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
--systembefore the command.Keep using
--systemfor every later operation on that service.User and system services are separate namespaces and may have the same name.
Do not run
sudo spmwithout--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 = trueCommon 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 # macOSPreview and apply:
spm validate spm.toml
spm diff spm.toml
spm apply --dry-run spm.toml
spm apply spm.tomlExport existing services:
spm export all > spm.tomlApply 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.jsHTTP, 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.jsInspect health state and logs:
spm health api
spm logs api --healthPeriodic 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 apibasic 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 apiCore 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 -fEach 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 3000The shorter script form works too:
spm start app.js --name api --misespm 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 apiUse --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.servicespm 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 apispm 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 modePM2 command map
PM2 | spm |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Not needed; spm enables services when they are created. |
PM2 ecosystem file |
|
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 mcpThe 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-spmInside 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 mcpOr 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 mcpRun /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.bashZsh:
mkdir -p ~/.zfunc
spm completion zsh > ~/.zfunc/_spm
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinitFish:
mkdir -p ~/.config/fish/completions
spm completion fish > ~/.config/fish/completions/spm.fishCompletion 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-ExpressionTroubleshooting
Start with:
spm doctor
spm status NAME
spm logs NAME -n 100For system mode:
sudo spm --system doctor
sudo spm --system status NAMEdoctor 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 --helpBuild and test
go test -race ./...
go vet ./...
go build -o spm ./cmd/spmRelease builds inject the version with ldflags:
go build \
-ldflags "-X github.com/eyvant/spm/internal/app.version=0.1.0" \
-o spm ./cmd/spmGitHub 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.
--instancesprovides fork-mode instances, not PM2 cluster mode.spm does not install language runtimes or runtime managers.
Available Tools
12 toolsspm_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 serviceADestructive
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 spmARead-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 logsARead-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 servicesARead-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 commandADestructive
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 serviceARead-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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceMulti-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 npmApache 2.0
- AlicenseAqualityCmaintenanceA local stdio MCP service that unifies coding agents like Codex and Claude into cs_agent_* tools, enabling the root agent to create, invoke, and manage child agents with recursive delegation.1456 npm2MIT
- AlicenseNot gradedqualityCmaintenanceA lightweight, cross-platform MCP server for managing background processes. Enables AI coding agents to spawn, monitor, and interact with long-lived processes.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT