Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sysg.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
start

Launch managed processes in one of three modes:
  • manifest services (sysg start)
  • units (sysg start <command...>)
  • child units (sysg start --child --parent-pid <pid> -- <command...>)
$ sysg start

​
Options

ShortLongDescription
-c--configPath to the configuration file. If not specified, systemg looks for systemg.yaml or sysg.yaml in the current directory
-s--serviceOptionally start only the named service instead of all services
---nameOptional name for units or child-start units
---daemonizeRun the supervisor as a background daemon
---parent-pidRun start in child mode by attaching the process to a parent service PID
---ttlOptional time-to-live in seconds for child mode
---childExplicit child-mode marker. Requires --parent-pid
---sysOpt into privileged system mode. Requires running as root
---drop-privilegesDrop child service privileges during spawn. In root/system mode, services without an explicit user run as nobody
---stderrPipe stderr output from supervised processes to stdout in foreground mode
---log-levelSet logging verbosity for this invocation. Accepts named levels (trace, debug, info, warn, error, off) or numeric values (5-0)
:::info The --stderr flag is particularly useful for:
  • Development: See error output immediately while debugging
  • CI/CD Pipelines: Capture all output in a single stream
  • Real-time Monitoring: Watch for errors as they happen
Note: This flag only affects foreground mode. In daemonized mode, stderr is written to log files when the service uses logs.sink: file. :::

​
Examples

​
Start with default configuration

$ sysg start
Looks for systemg.yaml or sysg.yaml in the current directory.

​
Start with specific configuration

$ sysg start --config /etc/myapp/services.yaml

​
Daemon mode

Run the supervisor in the background. Subsequent commands communicate with this long-lived process. 
$ sysg start --daemonize
Check if the daemon is running: 
$ sysg status

​
Debug mode

See detailed output during startup: 
$ sysg start --log-level debug

​
Capture stderr in foreground

Useful for development and debugging: 
$ sysg start --stderr
Output will show stderr lines with service prefix: 
[api:stderr] Error: Database connection failed
[worker:stderr] Warning: Queue full, retrying...

​
Unit mode (no config file)

$ sysg start --daemonize -- sleep 30
If the supervisor is already running, this command stages a unit config in ~/.local/share/systemg/units/ and prints an explicit restart command. It does not restart the supervisor implicitly.

​
Child mode for orchestrators (replacement for spawn)

$ sysg start --parent-pid 4242 --name worker-1 --ttl 900 -- python worker.py

​
What happens

  1. Manifest mode starts services in dependency order
  2. Unit mode creates a single managed unit from the command
  3. Child mode attaches a managed child to the parent process tree
  4. Service output follows the configured logs.sink policy
  5. PIDs are tracked for other commands
In daemon mode, the supervisor monitors services and handles restarts according to your configuration.

​
See also

  • stop - Stop running services
  • status - Check service health
  • restart - Restart services