---
title: Units
---

# Units

Use `sysg start -- <command...>` to create and run a single managed unit without
writing a full project config.

When `--name` is omitted, systemg auto-generates a unit name.

## Common examples

Keep a lightweight HTTP server alive.

```bash
$ sysg start -d -- python3 -m http.server 8080
```

Keep a one-off script running.

```bash
$ sysg start --daemonize -- ./scripts/dev-health-check.sh
```

Tail application logs under supervision.

```bash
$ sysg start -d -- tail -F ./logs/app.log
```

Run a frontend dev server.

```bash
$ sysg start -d -- npm run dev
```

Run a backend API in reload mode.

```bash
$ sysg start --daemonize -- uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

Run a worker with explicit queue and concurrency settings.

```bash
$ sysg start -d -- sh -lc 'QUEUE=critical CONCURRENCY=4 ./bin/worker'
```

Run a live TypeScript watcher and build loop.

```bash
$ sysg start -d -- sh -lc 'pnpm install && pnpm run dev:watch'
```

Run a periodic heartbeat loop.

```bash
$ sysg start --daemonize -- sh -lc 'while true; do date; sleep 30; done'
```

Run a composed multi-step local pipeline.

```bash
$ sysg start -d -- sh -lc 'pnpm db:migrate && pnpm run seed && pnpm run start:prod'
```

## Where unit files are stored

Generated unit configs are saved under:

```bash
~/.local/share/systemg/units/*.yaml
```

systemg automatically prunes this folder to prevent unbounded growth.

## Applying a newly staged unit

If a supervisor is already running, `sysg start -d -- <command...>` stages
the unit YAML and prints the explicit restart command. This keeps restart decisions
under user control.

```bash
$ sysg restart -d --config ~/.local/share/systemg/units/<unit>.yaml
```

## Inspect and stop

```bash
$ sysg status
$ sysg logs --service <unit-name>
$ sysg stop --service <unit-name>
```
