Skip to content

Stargraph Serve — Overview

Stargraph's serve subsystem is the FastAPI + WebSocket surface that exposes the engine to operators, agents, and human-in-the-loop workflows. It pins a profile-driven authentication chain, a default-deny capability gate, and a single-process invariant (locked Decision #5).

The serve surface is the contract between Stargraph and the outside world: HTTP routes, WebSocket streams, scheduler triggers, run-history queries, and HITL response handling. Everything else (engine, replay, fathom) sits behind it.

Topics

  • HTTP API — REST routes under /v1/*.
  • WebSocket stream — /v1/runs/{id}/stream events.
  • Triggers — cron, webhook, and idempotency-keyed inbound.
  • Scheduler — pending-runs queue + dispatch.
  • Run history — runs_history table + listing API.
  • CLI — stargraph serve flags + lifecycle.
  • Bosun packs — pack discovery + signing in serve context.
  • Profiles — oss-default + cleared.
  • Nautilus broker — broker-emit integration.
  • HITL — human-in-the-loop pause/respond flow.
  • Artifacts — content-addressed artifact store.

TODO: expand with cross-references to the matching stargraph.serve.* modules.