Installation#

Install it as a devDependency of the package that owns the host, and the commands appear.

Install#

pnpm add -D @sigx/actors-cli

npm install -D @sigx/actors-cli

yarn add -D @sigx/actors-cli

bun add -D @sigx/actors-cli

Requires @sigx/cli ≥ 0.9 and @sigx/terminal ≥ 0.11.

Flags#

SIGX_OPS_SECRET is the preferred way to pass the token — a secret in --secret lands in your shell history and in ps.

The app-module convention#

Embedded mode reads named exports from your app module. app is required; the rest each unlock panels:

// src/actors.app.ts
export const app = defineActorApp({ actors, storage }).use(metrics()).use(health());
export const metrics = m;        // unlocks the latency and error panels
export const ops = o;            // unlocks the ops sections
export const cluster = c;        // unlocks the cluster tab

Without metrics, the dashboard still runs — it simply has less to show.

Health exit codes#

sigx actors health --url http://host:3000

1 and 2 are deliberately distinct. A host answering "not ready" is alive and draining; a host answering nothing is a different incident. Collapsing them makes an alert unable to tell a rolling deploy from an outage.

The dashboard#

sigx actors (or top) opens the dashboard. It is width- and height-aware: tables window to the rows available and scroll to follow the cursor, columns shrink from the right so a host id or actor key is never truncated, and alert banners wrap.

Detail is only requested while a drill-down is open, so the extra load is opt-in.

Every panel states its scope — cluster-wide or one host. That distinction is easy to lose and expensive to get wrong. The READY column shows FATAL distinctly from not-ready, per Health & readiness.

Next steps#

• API reference — the /source data layer.
• Cluster stats — what the panels are showing.
• The ops endpoint — mounting what --url reads.