Service management

CogOS can run as a long-lived background service. The cogos serve command supports subcommands for daemon lifecycle management, log viewing, and boot auto-start.

Only one CogOS daemon can run at a time. If a daemon is already running, cogos serve start will refuse to start a new one regardless of the port specified. Use cogos serve stop first, then start with a new port.

Running modes

Foreground
Background daemon
Daemon + auto-start

Run the server in the current terminal session. Stops when you press Ctrl+C or close the terminal.

cogos serve --port 8000

Run the server as a detached background process. The process continues after you close the terminal.

cogos serve start
cogos serve --port 9000 start

Logs are written to ~/.cogos/cogos.log and the PID is stored in ~/.cogos/cogos.pid.

Start the daemon and register a systemd service so CogOS auto-starts on boot.

cogos serve start --autostart
cogos serve --port 9000 start --autostart

Port configuration

The server port can be specified in two ways (highest priority wins):

Command-line flag: cogos serve --port 9000 start
Config file: server.port in configs/cogos.yaml
Default: 8000

# configs/cogos.yaml
server:
  host: "0.0.0.0"
  port: 8000

The --port flag is defined on the serve group, so it works with all subcommands and foreground mode.

Daemon management

Start

cogos serve start
cogos serve --port 9000 start
cogos serve --port 8000 --template general start
cogos serve start --autostart

Options --host, --port, and --template are defined on the parent serve command and apply to all subcommands. Pass --autostart to also enable boot auto-start via systemd.

Stop

cogos serve stop
cogos serve stop --remove-autostart

Sends SIGTERM to the daemon and waits for graceful shutdown. Falls back to SIGKILL after 15 seconds if the process does not exit. Pass --remove-autostart to also disable the systemd auto-start service.

Restart

cogos serve restart
cogos serve --port 9000 restart

Stops the running daemon (if any), then starts a new one.

Status

cogos serve status

Displays:

Running state and PID
Log file location
Uptime, memory usage, and CPU (when psutil is installed)
Whether auto-start is enabled

Install psutil (pip install psutil) for uptime, memory, and CPU metrics in the status output.

Boot auto-start

Use the --autostart flag on start to register a systemd user service:

cogos serve start --autostart

This:

Starts the daemon immediately
Generates a systemd unit file at ~/.config/systemd/user/cogos.service
Enables the service with systemctl --user enable cogos
Runs loginctl enable-linger so the service survives user logout

To remove auto-start later:

cogos serve stop --remove-autostart

Auto-start requires a Linux system with systemd. It is not supported on macOS or Windows.

Manual systemd control

After enabling auto-start, you can also manage the service directly with systemctl:

systemctl --user start cogos
systemctl --user stop cogos
systemctl --user restart cogos
systemctl --user status cogos
journalctl --user -u cogos

Log management

View recent server output:

# Last 50 lines (default)
cogos serve logs

# Last 200 lines
cogos serve logs -n 200

# Follow in real time (like tail -f)
cogos serve logs -f

Log file location: ~/.cogos/cogos.log

File locations

File	Purpose
`~/.cogos/cogos.pid`	PID of the running daemon process
`~/.cogos/cogos.log`	Server stdout and stderr output
`~/.config/systemd/user/cogos.service`	Systemd unit file (created by `--autostart`)

Command reference

Command	Description
`cogos serve`	Start in foreground (Ctrl+C to stop)
`cogos serve start`	Start as background daemon
`cogos serve start --autostart`	Start daemon + enable boot auto-start (systemd)
`cogos serve stop`	Stop the daemon
`cogos serve stop --remove-autostart`	Stop daemon + disable boot auto-start
`cogos serve restart`	Restart the daemon
`cogos serve status`	Show status, PID, uptime, memory, auto-start state
`cogos serve logs`	View logs (`-f` follow, `-n` line count)

​Running modes

​Port configuration

​Daemon management

​Start

​Stop

​Restart

​Status

​Boot auto-start

​Manual systemd control

​Log management

​File locations

​Command reference

Running modes

Port configuration

Daemon management

Start

Stop

Restart

Status

Boot auto-start

Manual systemd control

Log management

File locations

Command reference