> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loom.teamecho.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Service management

> Run Loom as a background daemon with auto-start on boot.

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.

<Warning>
  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.
</Warning>

## Running modes

<Tabs>
  <Tab title="Foreground">
    Run the server in the current terminal session. Stops when you press Ctrl+C or close the terminal.

    ```bash theme={null}
    loom serve --port 8666
    ```
  </Tab>

  <Tab title="Background daemon">
    Run the server as a detached background process. The process continues after you close the terminal.

    ```bash theme={null}
    loom serve start
    loom serve --port 9000 start
    ```

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

  <Tab title="Daemon + auto-start">
    Start the daemon and register a systemd service so Loom auto-starts on boot.

    ```bash theme={null}
    loom serve start --autostart
    loom serve --port 9000 start --autostart
    ```
  </Tab>
</Tabs>

## Port configuration

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

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

```yaml theme={null}
# 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

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

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

```bash theme={null}
loom serve restart
loom serve --port 9000 restart
```

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

### Status

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

<Note>
  Install `psutil` (`pip install psutil`) for uptime, memory, and CPU metrics in the status output.
</Note>

## Boot auto-start

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

```bash theme={null}
loom serve start --autostart
```

This:

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

To remove auto-start later:

```bash theme={null}
loom serve stop --remove-autostart
```

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

### Manual systemd control

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

```bash theme={null}
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:

```bash theme={null}
# 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)           |