Starflow Designer vs Starflow Engine

Starflow Designer vs Starflow Engine

Starflow is the umbrella Celestial product for durable workflows and agent-adjacent orchestration. Implementation spans several npm packages; docs and UX should use Designer vs Engine when readers need to know which layer you mean.

Definitions

Name	What it is	Typical touchpoints
Starflow Designer	Authoring and operations: pipeline definitions, triggers, CI-shaped steps, operator CLIs	starflow.yaml, sf / starflow from @celestial/starflow-cli, harness scaffolds
Starflow Engine	Durable graph runtime: nodes, edges, checkpoints, WorkflowStateAdapter, wait / resumeWait, wake ports	npm @celestial/starflow-engine, used by @celestial/starflow-core default runtime and by API / starflow-server hosts

@celestial/starflow-core holds shared schema, parsing, and RuntimeAdapter contracts—it is the library seam between Designer-authored assets and Engine execution, not a separate customer brand.

starflow.yaml: sandbox and VPN steps

Pipeline steps compiled by @celestial/starflow-core support:

• use_sandbox (boolean) and sandbox_provider (string) on run: shell steps and on type: starsystem-deploy — mapped to engine shellUseSandbox / shellSandboxProvider (see Sandbox adapters).
• type: vpn-connect with optional vpn_mesh_provider, vpn_connect_profile_id, vpn_connect_mesh_name, vpn_connect_advertised_cidrs, vpn_connect_mode — mapped to the engine vpn-connect node (see VPN adapters).

Run starflow schema step or starflow schema config (@celestial/starflow-cli) to emit JSON Schema from the same Zod as the loader — use for editor $schema or CI checks. See CLI Reference.

Migration note

The graph runtime npm package was formerly named @celestial/flow-runner. It is now @celestial/starflow-engine (monorepo folder packages/starflow-engine). Historical ADRs and issues may still say “flow-runner”; prefer Starflow Engine in new prose.

Architecture Decision Records

• ADR 025 — canonical nomenclature (source of truth).
• ADR 024 — durable wait, persistence, wake channels.

Where Spacecraft fits

Spacecraft (sc) authors harness blueprints (agents, tools, memory). Starflow pipelines invoke those harnesses on a schedule or webhook. See Starflow Harness Design and Gateway + personal agent.