SManager

A simple server manager for self-hosted services, with VPN integration and support for local/systemd, Docker, and PHP runtimes.

When building a self-hosted setup, it’s common to end up with dozens of local services, Docker containers, and maintenance scripts scattered across your system. Tasks as simple as restarting or stopping a service can quickly become frustrating when there’s no clear overview of what is running, how components relate to each other, or how everything is managed.

SManager provides a simple and unified CLI for managing local, Docker, and PHP services, with built-in support for VPN integration and interactive metadata management.

Reseting all your music-related services becomes as simple as:

smanager group restart music

Features

• Unified service management for local/systemd, Docker, and PHP runtimes.
• Per-service custom start/stop/restart/status scripts.
• VPN integration (Tailscale provider support).
• Interactive metadata creation and editing.
• YAML-based global configuration.
• Rich service status reporting with optional JSON output.

Phylosophy

SManager is designed to work alongside your existing setup, not replace it. However here are some best practices to get the most out of SManager:

• Use one directory per service (service directory), put all the service-related files there (metadata, scripts, Dockerfiles, documentation, etc).
• Define one directory to store all the service directories (services root).
• Each time you create a new service, create a metadata file for it using smanager metadata init and place it in its service directory.

SManager does not enforce any specific structure for your services, but following these guidelines will help you maintain a clear and organized setup that SManager can effectively manage. If you don't want to follow this structure, just point services_root to your $HOME and SManager will work with whatever it finds there.

Installation

pip install smanager

After installation, you need to configure SManager by running:

smanager config init
smanager config edit

An editor will open with the global configuration file. Set the services_root to the directory where you want to store your service directories, and configure the VPN provider if you are using one.

CLI Usage

Use this command pattern:

smanager <group> <command> [options]

Discover available commands at any level:

smanager --help
smanager <group> --help
smanager <group> <command> --help

Status Commands

Status is now a subcommand under each resource group:

smanager service status <service_id>
smanager group status <group_name>
smanager dependency status <dependency_name>
smanager all status

Optional JSON output is available for each status command:

smanager service status <service_id> --json

Info Commands

Info is available under each resource group and shows service name plus WebUI URL:

smanager service info <service_id>
smanager group info <group_name>
smanager dependency info <dependency_name>
smanager all info

Use --details to include extra operational columns:

smanager service info <service_id> --details

Metadata Commands

The metadata group provides interactive workflows for service metadata files.

Create Metadata

smanager metadata init

Optional output override:

smanager metadata init --output /path/to/sd_info.json

Edit Existing Metadata

smanager metadata edit

Edit a specific file directly:

smanager metadata edit --file /path/to/sd_info.json

Validate Metadata

Validate a single metadata file:

smanager metadata validate --file /path/to/sd_info.json

Validate all metadata files from a directory recursively:

smanager metadata validate --root /path/to/services

Use JSON output for CI/automation:

smanager metadata validate --root /path/to/services --json

Behavior summary:

• Interactive prompts with inline defaults.
• Runtime-aware sections (Docker, Local, and PHP).
• Multi-select support for groups and depends_on.
• Validation before writing changes.

PHP Runtime Metadata

For runtime.type: php, define the php section with:

• start_command (required)
• stop_command (required)
• status_command (optional, if present takes precedence over healthcheck for status)
• healthcheck_url (optional, used by status checks)
• healthcheck_timeout (optional, defaults to 3)
• working_dir (optional)
• env (optional map of environment variables)

Custom Scripts

Any service can override start, stop, restart, and/or status with a shell script. Provide any subset of them; the operations you do not override keep using the default mechanism for the runtime type.

{
  "scripts": {
    "start": "scripts/start.sh",
    "stop": "scripts/stop.sh",
    "restart": "scripts/restart.sh",
    "status": "scripts/status.sh",
    "working_dir": ".",
    "env": { "APP_ENV": "production" }
  }
}

• Values are paths to .sh files, relative to the service directory (or absolute).
• Scripts run with bash (fallback sh) from working_dir (default: the service directory), with env merged over the current environment.
• status exit code drives the result: 0 = running, anything else = stopped.
• A restart script owns the stop/start sequence; SManager still re-establishes the VPN HTTPS serve afterwards when vpn.serve_https is enabled.
• When scripts.start and scripts.stop are both present, local.systemd_services and docker.compose_file become optional.

HTTPS over VPN without passwords

By default SManager runs the privileged Tailscale operations non-interactively and never blocks waiting for a password:

1. It first tries the command as the current user (Tailscale operator mode).
2. It falls back to sudo -n (non-interactive; requires NOPASSWD).

To avoid sudo entirely, once per machine run:

sudo tailscale set --operator=$USER

Alternatively, grant passwordless access to the Tailscale binary:

echo "$USER ALL=(root) NOPASSWD: $(command -v tailscale)" | \
  sudo tee /etc/sudoers.d/smanager-tailscale
sudo chmod 0440 /etc/sudoers.d/smanager-tailscale

start and restart (re)create the Tailscale HTTPS serve when vpn.serve_https is true; stop takes it down. If the VPN is disconnected it is brought up first. Failures are reported as clean errors, and a failing VPN serve never leaves the service itself down.

Notes

• metadata init creates a new file.
• metadata edit modifies an existing file.
• metadata validate checks script paths and runtime-specific rules.
• Use command-specific --help for the latest options and examples.