spm

Cross-platform native service manager (systemd, launchd, Windows services) with a built-in MCP server, so coding agents can start, inspect, read logs of, and schedule long-running processes as persistent services instead of backgrounding them with & or nohup.

Documentation

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:

RuntimePlatformsRuns
spm-supervisorWindowsevery service (systemd and launchd supervise services elsewhere)
spm-schedulerWindows, macOSthe 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

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?

GoalCommand
Keep a process runningspm start
Run a job on a schedule and let it exitspm schedule
Restart a long-running service periodicallyspm start --cron-restart
Run a service as root or another system usersudo spm --system start
Manage several services from a filespm 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

CommandPurpose
spm listList managed services
spm list --watchContinuously refresh CPU, memory, and status
spm show NAMEShow an spm configuration and runtime summary
spm status NAMEShow native systemctl status output
spm logs NAME -fFollow logs
spm restart NAMERestart using the current unit
spm restart --update NAMERegenerate the unit from saved configuration, then restart
spm stop NAMEStop now, but keep boot enablement
spm disable NAMEStop and disable boot startup
spm enable NAMEEnable and start
spm delete NAMEStop and remove the service and companion units
spm cat NAMEPrint the generated unit and drop-ins
spm edit NAMEOpen 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

PM2spm
pm2 start index.js --name apispm start index.js --name api
pm2 lsspm list
pm2 show apispm show api
pm2 logs apispm logs api -f
pm2 restart apispm restart api
pm2 reload apispm reload api
pm2 stop apispm stop api
pm2 delete apispm delete api
pm2 sendSignal SIGUSR2 apispm signal SIGUSR2 api
pm2 jlistspm list --json
pm2 monitspm list --watch
pm2 start app.js -i 4 in fork modespm start app.js -i 4
pm2 scale api 8spm scale api 8
pm2 startupspm startup
pm2 saveNot needed; spm enables services when they are created.
PM2 ecosystem filespm 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.