Skip to main content
Fabro provides two interfaces — a CLI for local development and an HTTP API for production use. Both share a common workflow engine.

​
Shared engine

At the core of both modes is the WorkflowRunEngine. It parses the Graphviz graph, walks nodes, dispatches to handlers (agent, command, human, etc.), selects edges, and checkpoints after each stage. The engine is parameterized by an Interviewer trait that controls how human-in-the-loop questions are presented — terminal prompts in CLI mode, HTTP request/response in API mode.

​
CLI mode

fabro run workflow.fabro --goal "Implement the login feature"
The CLI parses the workflow, creates the engine with a ConsoleInterviewer, and executes synchronously. Events are printed to stderr, progress is shown with terminal indicators, and human-in-the-loop questions are answered via interactive terminal prompts. When the run finishes, the process exits. CLI mode is ideal for:
  • Local development and iteration on workflows
  • One-off runs and debugging
  • Scripting and CI/CD pipelines

​
API mode

fabro server start
fabro server start starts an HTTP server, binding to ~/.fabro/fabro.sock by default (or plain TCP when configured), with persistent run storage. Runs are submitted via the REST API and executed asynchronously. Public HTTPS, when needed, is terminated upstream by a reverse proxy or platform ingress.

​
Configuration

The server reads ~/.fabro/settings.toml for default settings (model, sandbox, variables, authentication). This file is live-reloaded — changes take effect within seconds without restarting the server. Key server config options:
SettingDescription
server.listenBind transport: Unix socket or plain TCP listener
server.api.url / server.web.urlExternal API base URL and the single canonical browser/API origin
server.auth.methodsBootstrap auth methods: dev-token, github, or both
server.scheduler.max_concurrent_runsScheduler concurrency limit (default 5)
[run.*]Defaults applied to every run (overridable per-run)

​
Run lifecycle

  1. Submit — POST /api/v1/runs with a Graphviz workflow source. The run is created with status Queued and the response returns immediately with the run ID.
  2. Schedule — A background scheduler promotes queued runs to Running in FIFO order, up to the concurrency limit.
  3. Execute — The engine walks the graph, streaming events to all subscribers.
  4. Complete — The run transitions to Completed, Failed, or Cancelled.

​
Event streaming

The API streams run events via Server-Sent Events (SSE). Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. See the run events endpoint in the API reference.

​
Human-in-the-loop

In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is received, then continues execution. See the list questions and submit answer API reference pages.

​
Authentication

API mode supports two bootstrap auth methods, configurable in settings.toml:
  • dev-token — Bearer token access for operators and automation
  • github — GitHub OAuth for browser users, resulting in a session cookie

​
Demo mode

Demo mode is per-request: send the X-Fabro-Demo: 1 HTTP header to get static mock data with authentication disabled. The web UI sends this header automatically when configured with FABRO_DEMO=1. This lets you explore the UI without API keys or real workflow execution.

​
Web UI

The web UI is a React app (apps/fabro-web) that connects to the API server. Start it alongside fabro server start: 
fabro server start                 # API on ~/.fabro/fabro.sock by default
cd apps/fabro-web && bun run dev   # rebuilds web assets on change; refresh the browser
The UI provides:
  • Run board — List and monitor all runs
  • Run detail — Real-time stage progress, event stream, diffs, usage stats
  • Start new run — Submit a Graphviz workflow from the browser
  • Human-in-the-loop — Answer agent questions through the web interface
  • Sessions — Interactive chat interface (coming soon)
  • Insights — SQL-based analysis across runs via DuckDB

​
Comparison

See Server Mode for a full feature comparison between standalone and server mode.