Commands

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

Short	Long	Description
`-c`	`--config`	Path to the configuration file. If not specified, systemg looks for `systemg.yaml` or `sysg.yaml` in the current directory
`-s`	`--service`	Optionally start only the named service instead of all services
`-p`	`--project`	Target a stable project id when a supervisor manages multiple projects
`-`	`--name`	Optional name for units or child-start units
`-`	`--daemonize`	Run the supervisor as a background daemon
`-`	`--parent-pid`	Run `start` in child mode by attaching the process to a parent service PID
`-`	`--ttl`	Optional time-to-live in seconds for child mode
`-`	`--child`	Explicit child-mode marker. Requires `--parent-pid`
`-`	`--sys`	Opt into privileged system mode. Requires running as root
`-`	`--drop-privileges`	Drop child service privileges during spawn. In root/system mode, services without an explicit `user` run as `nobody`
`-`	`--stderr`	Pipe stderr output from supervised processes to stdout in foreground mode
`-v`	`--verbose`	Print per-service boot progress
`-`	`--plain`	Disable terminal decoration and accidental log following for automation
`-`	`--log-level`	Set 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

Foreground mode

Without --daemonize, the terminal attaches to the selected project. Boot progress updates in place, and output from every running service is multiplexed with a per-service prefix. Ctrl-C stops only that project and returns the terminal; the resident supervisor and other projects remain running.

Daemon mode

Start without retaining a terminal attachment. The command returns after the project reaches its target state; subsequent commands use the same resident supervisor.

$ 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 identifies the service and captured stream:

api | 2026-07-19T04:45:26Z stderr Error: Database connection failed
worker | 2026-07-19T04:45:27Z stderr Warning: Queue full, retrying...

Unit mode (no config file)

Unit mode is for ad-hoc commands you want systemg to manage without writing a project manifest first:

$ sysg start --daemonize --name db-tunnel -- sh db-tunnel.sh

systemg stages the command by translating it into a generated version 2 manifest—the common format the central supervisor understands for services and projects.

Info

With no supervisor, the staged manifest starts a supervisor and the unit runs immediately. With a resident supervisor, staging does not alter live state: no process starts until you run the explicit sysg start --config ... command printed by systemg.

See Units for the complete stage, apply, inspect, and stop workflow.

Child mode for orchestrators (replacement for `spawn`)

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

What happens

Manifest mode validates the complete graph and starts dependencies first
Unit mode creates a single managed unit from the command
Child mode attaches a managed child to the parent process tree
Service output follows the configured logs.sink policy
PIDs, process groups, lifecycle state, and cron history are tracked by project

In either mode, the supervisor owns the services. Foreground versus daemon mode controls the terminal attachment, not whether supervision exists.

Startup order

depends_on is the only thing that orders a start. Every service whose declared dependencies have resolved starts at the same time, so a boot takes as long as its longest dependency chain rather than the sum of every service's readiness wait. A service never waits on one it did not declare.

Set start.max_concurrent in supervisor.xml to 1 to start services one at a time, or to a positive number to cap how many run at once. The cap is worth reaching for when a wide boot contends for something the supervisor cannot see — every service opening connections to the same database at the same moment.