How It Works

systemg is a single binary that manages processes as a supervisor.

Architecture

CLI → Unix Socket → Supervisor → Services
                 ↓
           State Files

When you run sysg start, systemg starts or joins one resident supervisor. The supervisor launches and monitors the selected project; subsequent commands use its Unix socket.

Process lifecycle

1. Start: Services launch as soon as their depends_on entries resolve
2. Monitor: Supervisor tracks PIDs and health
3. Restart: Unsuccessful services restart per policy; clean exits stay done
4. Stop: Services terminate in reverse order

State location

All runtime data lives under one root, with each project's PID/state/cron files nested in its own projects/{project.id}/ subdirectory:

User mode (default):

• ~/.local/share/systemg/ - Supervisor + per-project state (under projects/)
• ~/.local/share/systemg/logs/ - Service logs

System mode (sudo sysg --sys):

• /var/lib/systemg/ - Supervisor + per-project state (under projects/)
• /var/log/systemg/ - Service logs

See State for the full layout.

Daemon vs foreground

Foreground (default):

• The terminal attaches to one project and streams service | line
• Slow boot progress updates in place
• Ctrl+C stops that project; the supervisor and sibling projects stay up

Daemon (--daemonize):

• The command returns after the project reaches its target state
• The same resident supervisor owns the project without a terminal attachment
• Good for production

Topics

• Commands - CLI reference
• Configuration - Service definitions
• Cron - Scheduled tasks
• Hooks - Commands triggered by service outcomes
• State - Runtime files
• Logs - Supervisor logs
• Kernel Mode - system mode, container-init, sandboxing