Station

Station is a monitoring dashboard for Station. It connects to your signal and broadcast adapters and provides a web interface for inspecting registered signals, browsing run history, and watching broadcast DAG execution in real time.

Station is a combined:

• Hono API server — REST endpoints for signals, runs, broadcasts, and health checks, plus a WebSocket endpoint for real-time event streaming
• Next.js frontend — Dashboard UI that renders signal metadata, run history, broadcast DAG visualization, and live log output

The API server runs on the configured port (default 4400). The Next.js frontend runs on port + 1 (default 4401). Both start automatically when you launch Station.

Install

pnpm add station-kit

Configuration

Create a station.config.ts (or .js / .mjs) in your project root:

import { defineConfig } from "station-kit";import { SqliteAdapter } from "station-adapter-sqlite";import { BroadcastSqliteAdapter } from "station-adapter-sqlite/broadcast"; export default defineConfig({  port: 4400,  signalsDir: "./signals",  broadcastsDir: "./broadcasts",  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),  broadcastAdapter: new BroadcastSqliteAdapter({ dbPath: "./jobs.db" }),});

The defineConfig helper provides type checking and autocompletion. It is a pass-through function — it returns the object unchanged.

Config options

Runner config (nested under runner)

Broadcast runner config (nested under broadcastRunner)

Running Station

npx station

Station looks for station.config.ts (or .js / .mjs) in the current working directory. If no config file is found, it starts with default settings (MemoryAdapter, no signal directory).

Active mode vs. read-only mode

Station operates in one of two modes depending on the runRunners setting.

Active mode (runRunners: true, default)

Station creates its own SignalRunner and BroadcastRunner. It discovers signals from signalsDir, polls the adapter for due runs, and executes them. Use this when you want Station to be your only runner process. The dashboard provides full functionality: monitoring, triggering signals, and cancelling runs.

Read-only mode (runRunners: false)

Station only reads from the adapter. It does not create runners, does not execute signals, and does not poll for due runs. Use this when you have a separate runner process and want Station purely for monitoring. Trigger and cancel endpoints return 403 in this mode.

Dashboard features

Signals list

View all registered signals with their name, input/output schemas (rendered from Zod definitions), timeout, retry count, recurring interval, concurrency settings, step names, and source file path.

Scheduled signals

Recurring signals get a dedicated view showing the interval, next scheduled run time, last execution time, and last execution status.

Run history

Browse all past and current signal runs. Filter by status (pending, running, completed, failed, cancelled) or by signal name. Each run shows the full detail: input data, output data, error messages, timing (created, started, completed), attempt count, and step execution records.

Run logs

View stdout and stderr output captured from signal handler execution. Logs are stored in an in-memory buffer and persisted to a separate SQLite database (station-logs.db) for survival across restarts.

Broadcast visualization

See the DAG structure of registered broadcasts — which nodes exist, their signal mappings, and dependency edges. During execution, node statuses (pending, running, completed, failed, skipped) update in real time. Includes skip reasons when nodes are bypassed due to guard conditions, upstream failures, or cancellation.

Real-time updates

A WebSocket connection on /api/events pushes lifecycle events as they happen. The frontend subscribes automatically — no polling required. Events cover the full signal and broadcast lifecycle (see WebSocket events table below).

Actions

In active mode, the dashboard allows triggering signals with custom input and cancelling in-progress runs or broadcast runs.

API endpoints

Station exposes a REST API on the configured port. All responses use the shape { data: ... } on success or { error: string, message: string } on failure.

Health

Signals

Runs

Broadcasts

WebSocket events

Connect to /api/events on the API server port. Each message is a JSON object with type, timestamp, and data fields.

Signal events

Broadcast events

Using Station with an existing runner

A common setup: one process runs signals, another runs Station for monitoring. Both point at the same SQLite database.

// runner.ts — executes signalsimport path from "node:path";import { SignalRunner } from "station-signal";import { SqliteAdapter } from "station-adapter-sqlite"; const runner = new SignalRunner({  signalsDir: path.join(import.meta.dirname, "signals"),  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),}); runner.start();

// station.config.ts — read-only monitoringimport { defineConfig } from "station-kit";import { SqliteAdapter } from "station-adapter-sqlite";import { BroadcastSqliteAdapter } from "station-adapter-sqlite/broadcast"; export default defineConfig({  port: 4400,  signalsDir: "./signals",  broadcastsDir: "./broadcasts",  adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),  broadcastAdapter: new BroadcastSqliteAdapter({ dbPath: "./jobs.db" }),  runRunners: false, // Don't execute signals — just monitor});

Graceful shutdown

Station listens for SIGINT and SIGTERM. On shutdown, it stops the broadcast runner first (it may query the database during cleanup), then the signal runner, then closes the WebSocket server, log store, and HTTP server. Both runners are given a 5-second grace period to finish in-flight work.