| name | sidecar |
| description | Elect and run the per-installation sidecar daemon that uplinks telemetry to the fleet control plane and receives commands over SSE (stackctl sidecar run) — specs/036-fleet-control-plane. Wraps `stackctl sidecar`. |
/stack-control:sidecar
Thin adapter over the stackctl sidecar verb. It fronts the one subaction of
the fleet-control-plane sidecar daemon (specs/036-fleet-control-plane): the
runnable local process that elects itself for this installation, spools local
telemetry, and uplinks to the fleet control plane.
Per .claude/rules/enforcement-lives-in-skills.md, this skill body is a thin
wrapper over stackctl sidecar — it adds no behavior the CLI lacks.
run — elect + run the sidecar daemon
stackctl sidecar run [--plane-url <url>]
Elects the sidecar for the current installation via the bind-wins local-socket
protocol (contracts/local-socket-protocol.md § C6) and, on a WON election,
stays alive holding the local socket + the plane uplink open until SIGINT/
SIGTERM, then stops gracefully. Only one sidecar can be elected per
installation at a time.
- Won election: prints
sidecar: elected — listening at <socketPath> and
blocks until a stop signal.
- Lost election: exits silently (exit 0) — another sidecar is already
elected for this installation; this is the normal, expected outcome, not an
error.
--plane-url <url> is optional. When omitted, the daemon falls back to
the STACKCTL_CP_URL environment variable. (A config-file plane.url
resolution is a known gap — the installation config-loader does not yet
parse a plane block.)- An unknown flag, a missing
--plane-url value, or a stray positional is a
usage error (exit 2).
Every connection this daemon opens is sidecar-outbound — commands arrive
over a held-open SSE stream the sidecar itself opens; telemetry leaves via
HTTP POST (contracts/sidecar-plane-protocol.md § C1). The plane can never dial
the sidecar.
Provisioning the credential
The sidecar authenticates to the plane with a bearer token. See
/stack-control:plane provision-token for placing that
token into this installation's machine-local custody before running sidecar run against a plane that enforces auth.
Fail-loud cases (exit 2)
- Missing/unrecognized subaction (
run is the only one).
--plane-url with a missing value.- Any unknown flag or stray positional.
