Daemon | Ringleader Docs

The daemon is the local control plane: the controller manager (control loops that boot workstations, deliver the in-VM agent, and forward the Docker socket) plus an optional HTTP API. The Ringleader desktop app starts one for you. These commands let you run and control it directly.

Bare rl daemon (no subcommand) runs in the foreground; rl daemon start detaches it into the background.

rl daemon                # run in the foreground
rl daemon start          # start detached in the background
rl daemon start --foreground   # explicit foreground form
rl daemon status         # is one running?
rl daemon restart        # stop, then start a fresh one
rl daemon stop
rl daemon log-level debug   # raise the log level, kept across restarts

Subcommands

Command	Description
`start`	Start the daemon detached, logging to `<home>/daemon.log`. No-op if one is already running for the data dir. `--foreground` runs it in the foreground instead of detaching.
`stop`	Stop a backgrounded daemon, and wait until its process has exited. It prints `rl daemon: stopped (pid N)`. A daemon still running after 10 seconds is stopped by force, and the line reads `rl daemon: force-stopped (pid N)`. If even that fails, `stop` exits non-zero. With no daemon running, it prints `rl daemon: not running` and exits `0`.
`restart`	Stop the running daemon, then start a fresh one (forwards the full flag set).
`status`	Report running state, pid, uptime, home, log path, and the latest log line. Exits `3` when none is running.
`log-level [level]`	Show the daemon’s log level, or set it to `trace`, `debug`, `info`, `warn` or `error`. The setting is kept across restarts, and a running local daemon picks it up within a few seconds. A daemon started with `--log-level` or `RINGLEADER_LOG_LEVEL` starts at that level instead.

Flags

These apply to start/restart (and bare daemon):

Flag	Description
`--home <dir>`	Data directory.
`--addr <address>`	Also serve the HTTP API on this address (default: off).
`--require-auth`	With `--addr`, reject unauthenticated callers (`401`) instead of treating them as local admin. On by default when `--addr` is not a loopback address. Pass `--require-auth=false` to allow anonymous callers, for example behind your own authenticating proxy.
`--jwks-url <url>`	Auth-broker JWKS URL; with `--addr`, broker-minted tokens are accepted alongside local tokens.
`--store-dsn <dsn>`	PostgreSQL DSN for the control-plane store (default `$RINGLEADER_STORE_DSN`; empty = local SQLite).
`--qemu <auto\|on\|off>`	Register the qemu provider: `auto` (detect KVM on x86-64 Linux), `on` (force), `off` (never). Default `$RINGLEADER_ENABLE_QEMU`, else `auto`.
`--metrics-addr <address>`	Serve Prometheus `/metrics` on this address (default `$RINGLEADER_METRICS_ADDR`; empty = disabled, so the local daemon serves none by default).
`--log-level <level>`	`trace`, `debug`, `info`, `warn`, `error` (default `$RINGLEADER_LOG_LEVEL`, else `info`).
`--log-format <text\|json>`	Log format (default `$RINGLEADER_LOG_FORMAT`, else `text`).

`rl status`

Report which workstation providers this machine can use, and why a provider cannot be used when it cannot.

rl status
rl status -o json     # the same, to branch on in a script

Each local provider, such as vz, lima, qemu, wsl2 or hcs, and each cloud provider is reported as one of:

State	Meaning
`available`	You can run a workstation on it here.
`not-registered`	This machine can run it, and the daemon did not register it.
`unavailable`	This machine, or your account, cannot run it. The reason says why.
`unknown`	There is no check for it, or no permission to read one.

The local answer is the daemon’s last check of this machine. With no daemon ever run here, rl status checks the machine itself and says so.

The cloud answer comes from your organization’s CloudAccount objects on the control plane you are signed in to. It checks no cloud credential and makes no call to any cloud. Only an org administrator can read those objects, so for anyone else each cloud shows unknown. When you are not signed in, each cloud shows unavailable.

The report marks the local provider the daemon uses by default for a new workstation that names none. If the daemon runs edge VMs on this machine, the report lists each one. It shows the Edge each one serves, its workstations, and whether it is running and serving.

Flag	Description
`-o, --output <format>`	`text` (default) or `json`.
`--as <subject>`	Impersonate a subject.
`--home <dir>`	Data directory.

Inspecting a running daemon

cat  ~/.ringleader/daemon.pid     # the live daemon's pid (absent ⇒ none running)
tail -f ~/.ringleader/daemon.log  # provisioning, agent-delivery and configuration logs

Note

daemon status exits with code 3 (not 1) when no daemon is running, so scripts can distinguish “not running” from a real error, the same convention systemctl uses.