Service management

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

Only one Loom daemon can run at a time. If a daemon is already running, loom serve start will refuse to start a new one regardless of the port specified. Use loom 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.

loom serve --port 8666

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

loom serve start
loom serve --port 9000 start

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

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

loom serve start --autostart
loom serve --port 9000 start --autostart

Port configuration

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

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

# configs/loom.yaml
server:
  host: "0.0.0.0"
  port: 8666

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

Daemon management

Start

loom serve start
loom serve --port 9000 start
loom serve --port 8666 --template general start
loom 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

loom serve stop
loom 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

loom serve restart
loom serve --port 9000 restart

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

Status

loom 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:

loom serve start --autostart

This:

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

To remove auto-start later:

loom 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 loom
systemctl --user stop loom
systemctl --user restart loom
systemctl --user status loom
journalctl --user -u loom

Log management

View recent server output:

# Last 50 lines (default)
loom serve logs

# Last 200 lines
loom serve logs -n 200

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

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

File locations

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

Command reference

Command	Description
`loom serve`	Start in foreground (Ctrl+C to stop)
`loom serve start`	Start as background daemon
`loom serve start --autostart`	Start daemon + enable boot auto-start (systemd)
`loom serve stop`	Stop the daemon
`loom serve stop --remove-autostart`	Stop daemon + disable boot auto-start
`loom serve restart`	Restart the daemon
`loom serve status`	Show status, PID, uptime, memory, auto-start state
`loom 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