---
title: 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
$ 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
$ sysg start
```

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

### Start with specific configuration

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

### Daemon mode

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

```sh
$ sysg start --daemonize
```

Check if the daemon is running:

```sh
$ sysg status
```

### Debug mode

See detailed output during startup:

```sh
$ sysg start --log-level debug
```

### Capture stderr in foreground

Useful for development and debugging:

```sh
$ 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
$ 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
$ 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
