diff --git a/docs/administration/deploy-server.mdx b/docs/administration/deploy-server.mdx index ea5e4fb5d..8955d3022 100644 --- a/docs/administration/deploy-server.mdx +++ b/docs/administration/deploy-server.mdx @@ -1,8 +1,145 @@ --- -title: "Server Deployment" -description: "Deploy the Fabro server to production" +title: "Server Mode" +description: "Run Fabro as an API server with a web UI, concurrent runs, and team access" --- -This guide is coming soon. Deployment guides are currently in development. + Server mode is in private early access. Contact [bryan@qlty.sh](mailto:bryan@qlty.sh) if you're interested in trying it. + +Fabro has two modes: **standalone** and **server**. Standalone mode (`fabro run`) executes a single workflow synchronously in your terminal. Server mode (`fabro serve`) starts an HTTP API that queues runs, streams events, and serves a web UI — so you can close your laptop and let workflows run. + +Both modes use the same workflow engine, the same DOT files, and the same sandbox providers. The difference is how you interact with them. + +## Standalone vs. server mode + +| | Standalone | Server | +|---|---|---| +| **Command** | `fabro run workflow.fabro` | `fabro serve` | +| **Best for** | Local development, one-off runs, CI/CD | Production, team use, running at scale | +| **Execution** | Synchronous, one run per process | Asynchronous, queued with configurable concurrency | +| **Human-in-the-loop** | Terminal prompts | Web UI or HTTP endpoints | +| **Events** | Printed to stderr | Streamed via SSE | +| **Persistence** | Checkpoint files only | SQLite database + checkpoint files | +| **Web UI** | Not available | Full React interface | +| **Authentication** | None | JWT and/or mTLS | + +## Starting the server + +```bash +fabro serve +``` + +This starts the API on `127.0.0.1:3000` by default. To also run the web UI: + +```bash +fabro serve # API on port 3000 +cd apps/fabro-web && bun run dev # Web UI on port 5173 +``` + +Common flags: + +| Flag | Default | Description | +|---|---|---| +| `--port` | `3000` | Port to listen on | +| `--host` | `127.0.0.1` | Host address to bind to | +| `--model` | — | Override default LLM model | +| `--sandbox` | — | Override default sandbox provider | +| `--max-concurrent-runs` | `5` | Maximum concurrent run executions | + +See [Server Configuration](/administration/server-configuration) for the full `server.toml` reference. + +## Submitting runs + +In server mode, workflows are submitted via the REST API and executed in the background: + +```bash +curl -X POST http://localhost:3000/runs \ + -H "Content-Type: application/json" \ + -d '{"workflow": "implement-feature", "goal": "Add user authentication"}' +``` + +The server returns immediately with a run ID. A background scheduler promotes queued runs to `Running` in FIFO order, up to the concurrency limit. + +## Run lifecycle + +1. **Submit** — `POST /runs` creates the run with status `Queued`. +2. **Schedule** — The scheduler picks up queued runs up to `max_concurrent_runs`. +3. **Execute** — The engine walks the graph, streaming events to all subscribers. +4. **Complete** — The run transitions to `Completed`, `Failed`, or `Cancelled`. + +## Web UI + +The web UI connects to the API server and provides: + +- **Runs board** — Monitor all active runs organized by status +- **Run detail** — Real-time stage progress, event stream, diffs, and usage stats +- **Start new run** — Submit workflows from the browser +- **Human-in-the-loop** — Answer agent questions through the web interface +- **Workflows** — Browse available workflows, view their graphs, and see run history +- **Insights** — SQL-based analysis across runs via DuckDB + + + Fabro web UI Runs board with Working, Pending, Verify, and Merge columns + + + + Fabro web UI run detail showing stages and workflow graph + + +## Event streaming + +The API streams run events via [Server-Sent Events (SSE)](/api-reference/runs#get-events). Every stage start, LLM call, tool invocation, and edge selection is emitted as a structured JSON event. Any HTTP client that supports SSE can subscribe — the web UI is just one consumer. + +## Human-in-the-loop + +In server mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is submitted, then continues execution. See the [Human-in-the-Loop API reference](/api-reference/human-in-the-loop) for the polling and answer endpoints. + +## Authentication + +Server mode supports two authentication strategies, configurable in `server.toml`: + +- **JWT** — EdDSA-signed bearer tokens. Used by the web UI. See [API Overview](/api-reference/overview#jwt-bearer-token) for token format. +- **mTLS** — Mutual TLS with client certificates. Used for service-to-service communication. See [API Overview](/api-reference/overview#mtls-mutual-tls) for setup. + +Both strategies can be enabled simultaneously — the first successful match wins. + +## Demo mode + +Send the `X-Fabro-Demo: 1` header on any API request to get static mock data with authentication disabled. The web UI enables this automatically with the `FABRO_DEMO=1` environment variable. This lets you explore the UI without API keys or real workflow execution. See [Demo Mode](/api-reference/demo-mode) for details. + +## Pointing the CLI at a server + +The CLI can delegate commands to a running Fabro server instead of executing locally. Set `mode = "server"` in `~/.fabro/cli.toml`: + +```toml title="cli.toml" +mode = "server" + +[server] +base_url = "https://fabro.example.com:3000" +``` + +Or use the `--mode` flag: + +```bash +fabro --mode server --server-url https://fabro.example.com:3000 models list +``` + +This applies to commands like `fabro models list`, `fabro llm chat`, and `fabro exec`. See [CLI Configuration](/reference/cli-configuration#mode) for the full options including mTLS setup. + +## Next steps + + + + Full server.toml reference — authentication, TLS, run defaults, and more. + + + Step-by-step guide for deploying Fabro on Railway. + + + REST API for submitting runs, streaming events, and managing resources. + + + The workflow engine that powers both modes. + + diff --git a/docs/core-concepts/how-fabro-works.mdx b/docs/core-concepts/how-fabro-works.mdx index fc9bf4313..a2e19b50c 100644 --- a/docs/core-concepts/how-fabro-works.mdx +++ b/docs/core-concepts/how-fabro-works.mdx @@ -16,7 +16,7 @@ Fabro has two interfaces, both backed by the same workflow engine: - **Standalone mode** (`fabro run`) — Run a single workflow synchronously in your terminal. Best for local development, one-off runs, and CI/CD. - **Server mode** (`fabro serve`) — Start an HTTP API server with a web UI, concurrent run scheduling, and team access. Best for production use and running at scale. -Both modes parse the same DOT files, use the same execution engine, and support the same sandbox providers. See [Server Mode](/core-concepts/server-mode) for a detailed comparison and setup guide, or [Architecture](/reference/architecture) for internals. +Both modes parse the same DOT files, use the same execution engine, and support the same sandbox providers. See [Server Mode](/administration/deploy-server) for a detailed comparison and setup guide, or [Architecture](/reference/architecture) for internals. ## Author time diff --git a/docs/core-concepts/server-mode.mdx b/docs/core-concepts/server-mode.mdx deleted file mode 100644 index c31fa3d51..000000000 --- a/docs/core-concepts/server-mode.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "Server Mode" -description: "Run Fabro as an API server with a web UI, concurrent runs, and team access" ---- - - - Server mode is in private early access. Contact [bryan@qlty.sh](mailto:bryan@qlty.sh) if you're interested in trying it. - - -Fabro has two modes: **standalone** and **server**. Standalone mode (`fabro run`) executes a single workflow synchronously in your terminal. Server mode (`fabro serve`) starts an HTTP API that queues runs, streams events, and serves a web UI — so you can close your laptop and let workflows run. - -Both modes use the same workflow engine, the same DOT files, and the same sandbox providers. The difference is how you interact with them. - -## Standalone vs. server mode - -| | Standalone | Server | -|---|---|---| -| **Command** | `fabro run workflow.fabro` | `fabro serve` | -| **Best for** | Local development, one-off runs, CI/CD | Production, team use, running at scale | -| **Execution** | Synchronous, one run per process | Asynchronous, queued with configurable concurrency | -| **Human-in-the-loop** | Terminal prompts | Web UI or HTTP endpoints | -| **Events** | Printed to stderr | Streamed via SSE | -| **Persistence** | Checkpoint files only | SQLite database + checkpoint files | -| **Web UI** | Not available | Full React interface | -| **Authentication** | None | JWT and/or mTLS | - -## Starting the server - -```bash -fabro serve -``` - -This starts the API on `127.0.0.1:3000` by default. To also run the web UI: - -```bash -fabro serve # API on port 3000 -cd apps/fabro-web && bun run dev # Web UI on port 5173 -``` - -Common flags: - -| Flag | Default | Description | -|---|---|---| -| `--port` | `3000` | Port to listen on | -| `--host` | `127.0.0.1` | Host address to bind to | -| `--model` | — | Override default LLM model | -| `--sandbox` | — | Override default sandbox provider | -| `--max-concurrent-runs` | `5` | Maximum concurrent run executions | - -See [Server Configuration](/administration/server-configuration) for the full `server.toml` reference. - -## Submitting runs - -In server mode, workflows are submitted via the REST API and executed in the background: - -```bash -curl -X POST http://localhost:3000/runs \ - -H "Content-Type: application/json" \ - -d '{"workflow": "implement-feature", "goal": "Add user authentication"}' -``` - -The server returns immediately with a run ID. A background scheduler promotes queued runs to `Running` in FIFO order, up to the concurrency limit. - -## Run lifecycle - -1. **Submit** — `POST /runs` creates the run with status `Queued`. -2. **Schedule** — The scheduler picks up queued runs up to `max_concurrent_runs`. -3. **Execute** — The engine walks the graph, streaming events to all subscribers. -4. **Complete** — The run transitions to `Completed`, `Failed`, or `Cancelled`. - -## Web UI - -The web UI connects to the API server and provides: - -- **Runs board** — Monitor all active runs organized by status -- **Run detail** — Real-time stage progress, event stream, diffs, and usage stats -- **Start new run** — Submit workflows from the browser -- **Human-in-the-loop** — Answer agent questions through the web interface -- **Workflows** — Browse available workflows, view their graphs, and see run history -- **Insights** — SQL-based analysis across runs via DuckDB - - - Fabro web UI Runs board with Working, Pending, Verify, and Merge columns - - - - Fabro web UI run detail showing stages and workflow graph - - -## Event streaming - -The API streams run events via [Server-Sent Events (SSE)](/api-reference/runs#get-events). Every stage start, LLM call, tool invocation, and edge selection is emitted as a structured JSON event. Any HTTP client that supports SSE can subscribe — the web UI is just one consumer. - -## Human-in-the-loop - -In server mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is submitted, then continues execution. See the [Human-in-the-Loop API reference](/api-reference/human-in-the-loop) for the polling and answer endpoints. - -## Authentication - -Server mode supports two authentication strategies, configurable in `server.toml`: - -- **JWT** — EdDSA-signed bearer tokens. Used by the web UI. See [API Overview](/api-reference/overview#jwt-bearer-token) for token format. -- **mTLS** — Mutual TLS with client certificates. Used for service-to-service communication. See [API Overview](/api-reference/overview#mtls-mutual-tls) for setup. - -Both strategies can be enabled simultaneously — the first successful match wins. - -## Demo mode - -Send the `X-Fabro-Demo: 1` header on any API request to get static mock data with authentication disabled. The web UI enables this automatically with the `FABRO_DEMO=1` environment variable. This lets you explore the UI without API keys or real workflow execution. See [Demo Mode](/api-reference/demo-mode) for details. - -## Pointing the CLI at a server - -The CLI can delegate commands to a running Fabro server instead of executing locally. Set `mode = "server"` in `~/.fabro/cli.toml`: - -```toml title="cli.toml" -mode = "server" - -[server] -base_url = "https://fabro.example.com:3000" -``` - -Or use the `--mode` flag: - -```bash -fabro --mode server --server-url https://fabro.example.com:3000 models list -``` - -This applies to commands like `fabro models list`, `fabro llm chat`, and `fabro exec`. See [CLI Configuration](/reference/cli-configuration#mode) for the full options including mTLS setup. - -## Next steps - - - - Full server.toml reference — authentication, TLS, run defaults, and more. - - - Deploy Fabro to production infrastructure. - - - REST API for submitting runs, streaming events, and managing resources. - - - The workflow engine that powers both modes. - - diff --git a/docs/docs.json b/docs/docs.json index b7ea011c5..265289a25 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -20,9 +20,7 @@ "pages": [ "getting-started/introduction", "getting-started/why-fabro", - "getting-started/quick-start", - "getting-started/dark-factory", - "getting-started/comparison" + "getting-started/quick-start" ] }, { @@ -30,10 +28,10 @@ "icon": "lightbulb", "pages": [ "core-concepts/how-fabro-works", + "getting-started/dark-factory", "core-concepts/workflows", "core-concepts/agents", - "core-concepts/models", - "core-concepts/server-mode" + "core-concepts/models" ] }, { @@ -104,6 +102,7 @@ "group": "Reference", "icon": "book", "pages": [ + "getting-started/comparison", "reference/dot-language", "reference/cli", "reference/cli-configuration", diff --git a/docs/getting-started/quick-start.mdx b/docs/getting-started/quick-start.mdx index 6a097bb86..e14c2616d 100644 --- a/docs/getting-started/quick-start.mdx +++ b/docs/getting-started/quick-start.mdx @@ -7,7 +7,7 @@ description: "Get up and running with Fabro" Fabro has two modes: - **Standalone mode** — Run workflows directly from the CLI. This is what the quick start covers below. -- **Server mode** — An API server with a web UI for launching and managing workflow runs at scale. See [Server Mode](/core-concepts/server-mode) for details. +- **Server mode** — An API server with a web UI for launching and managing workflow runs at scale. See [Server Mode](/administration/deploy-server) for details. ## Install diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 4de7d7aec..e0d290b53 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -89,4 +89,4 @@ The UI provides: ## Comparison -See [Server Mode](/core-concepts/server-mode#standalone-vs-server-mode) for a full feature comparison between standalone and server mode. +See [Server Mode](/administration/deploy-server#standalone-vs-server-mode) for a full feature comparison between standalone and server mode.