> ## Documentation Index
> Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# loco-server CLI: BigFred Backend Command Reference

> Reference for the loco-server command that starts the BigFred backend. Key flags for HTTP address, database path, JWT secret, Redis, and logging.

`loco-server` is the binary that runs the BigFred backend. When you start it, it brings up the HTTP and WebSocket server that the web UI connects to, manages a Redis/Valkey sidecar via supervisord for real-time state, and spawns a `dcc-bus` daemon for each configured command station. For most deployments you run it once on your hub and leave it running.

## Basic usage

```bash theme={null}
# Start with all defaults (listens on 0.0.0.0:8080)
./loco-server

# Listen on a different address or port
./loco-server --http 0.0.0.0:9090

# Set a persistent JWT secret so sessions survive restarts
./loco-server --jwt-secret "$(openssl rand -hex 32)"
```

<Note>
  If you do not set a JWT secret, `loco-server` generates a random one at startup and logs a warning. All logged-in sessions will be invalidated whenever the server restarts. Set `--jwt-secret` (or the `BIGFRED_JWT_SECRET` environment variable) in any environment where session persistence matters.
</Note>

***

## Flag reference

| Flag                 | Default                   | Description                                                                                                                                                          |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--http`             | `0.0.0.0:8080`            | HTTP listen address and port                                                                                                                                         |
| `--db`               | `bigfred.db`              | Path to the SQLite database file                                                                                                                                     |
| `--jwt-secret`       | *(random)*                | Hex or base64 secret used to sign session JWTs. Falls back to `BIGFRED_JWT_SECRET`, then generates a random per-run value                                            |
| `--secure-cookie`    | `false`                   | Set the `Secure` flag on session cookies. Enable this whenever the server is accessed over HTTPS                                                                     |
| `--log-level`        | `info`                    | Log verbosity: `debug`, `info`, `warn`, or `error`                                                                                                                   |
| `--redis-external`   | `false`                   | Connect to an existing Redis/Valkey instance instead of the managed sidecar. When set, `loco-server` dials `--redis-addr` directly and does not spawn its own daemon |
| `--redis-addr`       | *(redis-bind:redis-port)* | Redis dial address (`host:port`), used by both `loco-server` and `dcc-bus`. Defaults to the managed bind address and port when unset                                 |
| `--redis-no-persist` | `false`                   | Disable RDB snapshots for the managed Redis daemon. Useful in ephemeral or low-write deployments where you do not need on-disk state                                 |
| `--enable-telemetry` | `false`                   | Start Grafana Alloy via supervisord and export OTLP metrics for `loco-server` and `dcc-bus`                                                                          |
| `--no-supervisor`    | `false`                   | Skip supervisord entirely. Disables the Redis sidecar and `dcc-bus` process management. Intended for local development only                                          |

<Warning>
  Do not use `--no-supervisor` in production. Without supervisord, the Redis sidecar and `dcc-bus` daemons are not started, which disables real-time throttle commands, drive leases, and takeover requests.
</Warning>

***

## Environment variables

| Variable             | Description                                                                                                                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BIGFRED_JWT_SECRET` | Sets the JWT signing secret without putting it on the command line. Takes precedence over `--jwt-secret` if both are present. Use this in systemd unit files and container environments to keep the secret out of process listings |
| `BIGFRED_LOG_LEVEL`  | Overrides the `--log-level` flag. Accepts the same values: `debug`, `info`, `warn`, `error`                                                                                                                                        |

Setting the JWT secret via the environment is the recommended approach for production deployments:

```bash theme={null}
export BIGFRED_JWT_SECRET="$(openssl rand -hex 32)"
./loco-server
```

***

## Configuration file

On hub images, `loco-server` reads settings from `/data/etc/loco-server.conf` at startup. The file uses a simple `KEY=VALUE` format (dotenv style); comments start with `#` and blank lines are ignored. CLI flags always override values in the file.

```text /data/etc/loco-server.conf theme={null}
HTTP=0.0.0.0:8080
DB=/data/bigfred.db
# JWT_SECRET=          # empty = BIGFRED_JWT_SECRET env or random per-run secret
SECURE_COOKIE=true
LOG_LEVEL=info

REDIS_EXTERNAL=false
REDIS_NO_PERSIST=false

ENABLE_TELEMETRY=false
```

On every startup, `loco-server` also writes a fully-commented reference template to `/data/etc/loco-server.conf.defaults`. That file documents every supported key with its built-in default. It is not read at runtime — copy keys from it into `loco-server.conf` to apply changes.

For the full configuration key reference and persistence details, see the [Configuration](/admin-guide/configuration) page.

***

## The `dcc-bus` subcommand

`loco-server` includes a `dcc-bus` subcommand that is spawned automatically by supervisord — one instance per command station configured in the database. Each `dcc-bus` process owns the low-level DCC communication for one station and exchanges drive, function, and CV messages with `loco-server` over Redis.

```bash theme={null}
# This is run automatically — you do not need to call it manually
loco-server dcc-bus ...
```

<Note>
  You should not need to run `loco-server dcc-bus` directly. If a `dcc-bus` daemon is not starting or is restarting unexpectedly, check the supervisord log files and increase `--log-level` to `debug` for more detail.
</Note>