> ## 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

# 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...>`)

```sh theme={null}
$ 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                                                                  |
| `-`   | `--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

```sh theme={null}
$ sysg start
```

Looks for `systemg.yaml` or `sysg.yaml` in the current directory.

### Start with specific configuration

```sh theme={null}
$ sysg start --config /etc/myapp/services.yaml
```

### Daemon mode

Run the supervisor in the background. Subsequent commands communicate with this long-lived process.

```sh theme={null}
$ sysg start --daemonize
```

Check if the daemon is running:

```sh theme={null}
$ sysg status
```

### Debug mode

See detailed output during startup:

```sh theme={null}
$ sysg start --log-level debug
```

### Capture stderr in foreground

Useful for development and debugging:

```sh theme={null}
$ 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)

```sh theme={null}
$ 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`)

```sh theme={null}
$ 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`](/how-it-works/commands/stop) - Stop running services
* [`status`](/how-it-works/commands/status) - Check service health
* [`restart`](/how-it-works/commands/restart) - Restart services