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:7311

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.

What the screens show#

Hosts and nodes. When hosts publish meta.node, the Hosts table gains a NODE column — a short label, the tail that tells one node from another — the host drill-down a node row with the full name, and the Overview a nodes row. The scope reads cluster · 3 host(s) / 1 node(s), and the non-TTY top summary carries the same spread. A fleet reporting no node shows — in the column and no nodes row.

Locality. The Cluster screen has a locality row, NN% local (N dispatches) — the per-request fraction from dispatchesLocal / dispatchesRemote, described on Locality routing. A host on a build without those counters reads 0%.

Socket sessions. Once some host publishes the sockets ops section (registry.reportOps('sockets', () => stats.snapshot())), the Hosts table gains a SOCKETS column of open sessions and the host drill-down shows the session rows: open sessions and in flight, subscriptions and throttle-quantized count, deliveries and bytes, buffered bytes, connections opened / closed / refused, evictions, and lifetime percentiles. Only the polled host can report them.

sigx actors stats prints the same: a nodes line and a per-host node, and a sockets — host <id> ONLY block when the host publishes the section.

Next steps#

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