scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-05 08:10:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10
fabro/docs/administration/server-configuration.mdx
Bryan Helmkamp ed68c8b1d4 docs: migrate reference and guide examples to v2 config shape 
Rewrite every docs/ reference and integration guide example that
previously showed legacy flat TOML (`[llm]`, `[vars]`, `[sandbox]`,
`[setup]`, `[exec]`, `[fabro]`, `[pull_request]`, `[mcp_servers]`,
`[git]`, `[web]`, `[api]`, `[features] retros`, `version = 1`,
top-level `storage_dir`) to use the v2 namespaced schema. Also update
the surrounding prose to describe v2 merge semantics (R22 run.inputs
wholesale replacement, R71 sticky sandbox.env/labels, R30 whole-list
prepare.steps replacement, hook id-based replacement).

Files touched:
- docs/reference/user-configuration.mdx (complete rewrite around
  [cli.*] ownership, [run.*] run-scoped defaults, [cli.target] /
  [cli.exec] / [cli.output] / [cli.updates] / [cli.logging], and
  [run.agent.mcps.<name>] with durations like "10s")
- docs/reference/cli.mdx (settings.toml example uses [cli.exec.*],
  [run.model], [cli.target])
- docs/execution/run-configuration.mdx (full run-config example
  rewritten to use [workflow].graph, [run].goal/working_dir,
  [run.model], [run.prepare.steps], [run.sandbox.daytona.snapshot]
  with Size values, [run.inputs], [run.artifacts], [run.agent.mcps],
  [run.pull_request], [[run.hooks]] with optional id and duration
  timeout; section docs explain the new merge semantics)
- docs/execution/environments.mdx and devcontainers.mdx (sandbox
  examples now use [run.sandbox.*])
- docs/execution/retros.mdx (retros moved to [run.execution] retros
  = true per R31)
- docs/execution/failures.mdx (fallbacks now a single ordered array
  under [run.model].fallbacks)
- docs/workflows/variables.mdx ([vars] → [run.inputs], wholesale
  replacement semantics explained)
- docs/administration/server-configuration.mdx (full reference
  rewritten around [server.listen]/[server.api]/[server.web]/
  [server.auth]/[server.storage]/[server.scheduler]/[server.logging]/
  [server.integrations])
- docs/api-reference/overview.mdx (auth strategies now enabled via
  [server.auth.api.jwt].enabled and [server.auth.api.mtls].enabled;
  listener TLS moved to [server.listen.tls])
- docs/integrations/daytona.mdx, github.mdx (provider config now
  nested under [run.sandbox.daytona] / [server.integrations.github])
- docs/human-tools/ssh-access.mdx (sandbox examples to v2)
- docs/agents/mcp.mdx (Playwright sandbox example to [run.agent.mcps])
- docs/core-concepts/models.mdx (model config and fallbacks array to
  [run.model])

Canonical fabro-cli overrides and server run_manifest now emit
verbose via [cli.output].verbosity = verbose rather than the prior
run.metadata staging. No code changes beyond those Stage 4 fixes that
were already in flight.
2026-04-09 11:30:52 -04:00

249 lines
8.9 KiB
Text
Raw Blame History

---
title: "Server Configuration"
description: "Server-owned settings.toml sections, CLI overrides, and environment variables"
---
## Config file
`fabro server start` reads `~/.fabro/settings.toml` by default. This is the same file schema used by the CLI.
On a same-machine setup, the CLI and server share one `settings.toml`. On a remote deployment, the server machine has its own `settings.toml`, and the client machine keeps a separate local `settings.toml` for CLI-only values such as `[cli.target]`.
<Note>
Legacy `server.toml`, `user.toml`, and `cli.toml` are ignored with a warning. Rename them to `settings.toml`.
</Note>
### Which sections are server-owned
| Scope | Examples |
|---|---|
| Server-owned (runtime-only from local `settings.toml`) | `[server.listen]`, `[server.api]`, `[server.web]`, `[server.auth]`, `[server.storage]`, `[server.artifacts]`, `[server.slatedb]`, `[server.scheduler]`, `[server.logging]`, `[server.integrations]`, `[features]` |
| Shared run defaults (layered through `fabro.toml`/`workflow.toml`) | `[run.model]`, `[run.prepare]`, `[run.sandbox]`, `[run.checkpoint]`, `[run.inputs]`, `[run.pull_request]`, `[run.git]`, `[run.hooks]`, `[run.agent]` |
The CLI-only `[cli.*]` sections (including `[cli.target]`) belong in the client machine's `settings.toml`. They tell CLI commands how to reach a server. The server process does not read `[cli.*]` for its own binding or routing.
### Full reference
```toml title="settings.toml"
_version = 1
[server.listen]
type = "tcp"
address = "0.0.0.0:3000"
[server.listen.tls]
cert = "/etc/fabro/tls/cert.pem"
key = "/etc/fabro/tls/key.pem"
ca = "/etc/fabro/tls/ca.pem"
[server.api]
url = "https://fabro.example.com/api/v1"
[server.auth.api.jwt]
enabled = true
[server.web]
enabled = true
url = "https://fabro-web.example.com"
[server.auth.web]
allowed_usernames = ["alice", "bob"]
[server.auth.web.providers.github]
enabled = true
client_id = "Iv1.abc123"
[server.integrations.github]
app_id = "123456"
client_id = "Iv1.abc123"
[server.integrations.github.webhooks]
strategy = "tailscale_funnel"
[server.storage]
root = "/var/lib/fabro"
[server.scheduler]
max_concurrent_runs = 8
[server.logging]
level = "info"
# Run defaults — applied to every run unless overridden by workflow/project config
[run.model]
name = "claude-sonnet-4-5"
provider = "anthropic"
fallbacks = ["gemini", "openai"]
[[run.prepare.steps]]
script = "npm install"
[run.sandbox]
provider = "daytona"
[run.sandbox.daytona]
auto_stop_interval = 60
[run.sandbox.daytona.labels]
team = "platform"
[run.checkpoint]
exclude_globs = ["**/node_modules/**", "**/.cache/**"]
[run.inputs]
default_branch = "main"
[run.git.author]
name = "fabro-bot"
email = "fabro-bot@company.com"
[features]
session_sandboxes = true
```
### CLI overrides
Several `settings.toml` settings can be overridden via `fabro server start` flags:
| Flag | Default | Description |
|---|---|---|
| `--bind` | `~/.fabro/fabro.sock` | Address to bind: `IP` or `IP:port` for TCP, or a path for Unix socket |
| `--web` | enabled | Enable the embedded web UI, browser auth routes, and web-only helper endpoints |
| `--no-web` | disabled | Disable the embedded web UI, browser auth routes, and web-only helper endpoints |
| `--foreground` | — | Run in the foreground instead of daemonizing |
| `--model` | — | Override default LLM model |
| `--provider` | — | Override default LLM provider |
| `--sandbox` | — | Override default sandbox provider |
| `--max-concurrent-runs` | `5` | Maximum concurrent run executions |
| `--config` | `~/.fabro/settings.toml` | Path to server config file |
| `--dry-run` | — | Execute with simulated LLM backend |
CLI flags take precedence over `settings.toml` values. See [Run Configuration — Precedence](/execution/run-configuration#precedence) for the full resolution order.
### `[server.web]` section
Control the embedded SPA and browser-oriented routes.
| Key | Description | Default |
|---|---|---|
| `enabled` | Serve the embedded SPA, `/auth/*`, and the web-only helper endpoints under `/api/v1` | `true` |
| `url` | External web UI URL used for OAuth redirects | none (no implicit derivation from `server.listen`) |
When `enabled = false`, the server still exposes the machine API and `/health`, but `/`, `/auth/*`, SPA client routes, `/api/v1/auth/me`, `/api/v1/setup/*`, and `/api/v1/demo/toggle` all return `404`.
### Run defaults
The `[run.*]` sections in `settings.toml` act as defaults for every run.
On a same-machine setup, `settings.toml` is the shared machine-default layer under `workflow.toml` and `fabro.toml`.
On a remote setup, the client bundles workflow, project, and user config into the run manifest. The server then layers those bundled client configs over its own local defaults for run-shaped fields. Server-owned values like `[server.storage]`, `[server.api]`, `[server.web]`, `[features]`, and `[server.scheduler]` always come from the server machine's own `settings.toml` or `fabro server start` flags.
Merge rules follow the normative matrix: `[run.inputs]` replaces wholesale, `[run.sandbox.env]` and `[run.sandbox.daytona.labels]` merge by key, `[run.prepare.steps]` replaces whole-list, and `[[run.hooks]]` merge by optional `id`. Most other fields use "higher-precedence wins" field-wise merging.
### `[server.logging]` section
Configure the default server log level. Precedence: `FABRO_LOG` env var > `--debug` flag > `[server.logging].level` > `"info"`.
| Key | Description | Default |
|---|---|---|
| `level` | Log level: `error`, `warn`, `info`, `debug`, `trace` | `"info"` |
The CLI has its own `[cli.logging]` section.
### `[run.git.author]` section
Customize the git author identity used for checkpoint commits. When not set, defaults to `fabro` / `fabro@local`.
| Key | Description | Default |
|---|---|---|
| `name` | Git author name | `"fabro"` |
| `email` | Git author email | `"fabro@local"` |
### `[server.integrations.github]` section
Configure a GitHub App integration. Required fields include `app_id`, `client_id`, and `slug`. Webhook delivery is configured under `[server.integrations.github.webhooks]`:
```toml title="settings.toml"
[server.integrations.github]
app_id = "123456"
client_id = "Iv1.abc123"
slug = "fabro-app"
[server.integrations.github.webhooks]
strategy = "tailscale_funnel"
```
When `webhooks.strategy = "tailscale_funnel"` is configured, `fabro server start` binds a local HTTP listener, exposes it through `tailscale funnel`, and updates the GitHub App's webhook URL on startup. Incoming webhooks are verified with HMAC-SHA256. Requires the `GITHUB_APP_WEBHOOK_SECRET` environment variable.
### `[run.checkpoint]` section
Configure checkpoint behavior for all runs.
| Key | Description |
|---|---|
| `exclude_globs` | Glob patterns for files to exclude from checkpoint commits (for example, `["**/node_modules/**"]`) |
`exclude_globs` replaces across layers — the highest-precedence layer wins wholesale. See [Run Configuration — Checkpoint](/execution/run-configuration#runcheckpoint) for per-run configuration.
### `[features]` section
Toggle experimental or opt-in features. All features default to `false`.
| Key | Description |
|---|---|
| `session_sandboxes` | Enable session sandboxes in the web UI |
The same `[features]` section can be set in `fabro.toml` (project-level) to enable features per-project.
## Secrets and environment variables
Fabro stores server-managed credentials in `<data_dir>/secrets.json` and also honors relevant environment variables from the server process environment as a fallback. Fabro no longer auto-loads `.env` files. Provider API keys are required for the models you want to use; everything else is optional.
### LLM provider keys
| Variable | Provider |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic (Claude) |
| `OPENAI_API_KEY` | OpenAI (GPT) |
| `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Google (Gemini) |
| `KIMI_API_KEY` | Kimi |
| `ZAI_API_KEY` | Zai (GLM) |
| `MINIMAX_API_KEY` | Minimax |
| `INCEPTION_API_KEY` | Inception (Mercury) |
### Sandbox and tools
| Variable | Description |
|---|---|
| `DAYTONA_API_KEY` | Daytona cloud sandbox API key |
| `BRAVE_SEARCH_API_KEY` | Brave Search API key (for the `web_search` tool) |
### Server authentication
| Variable | Description |
|---|---|
| `FABRO_JWT_PRIVATE_KEY` | Ed25519 private key (base64-encoded PEM) for JWT signing |
| `FABRO_JWT_PUBLIC_KEY` | Ed25519 public key (base64-encoded PEM) for JWT verification |
| `SESSION_SECRET` | Session encryption secret (64-character hex string) |
### GitHub App (optional)
| Variable | Description |
|---|---|
| `GITHUB_APP_CLIENT_SECRET` | GitHub App client secret |
| `GITHUB_APP_WEBHOOK_SECRET` | GitHub App webhook secret |
| `GITHUB_APP_PRIVATE_KEY` | GitHub App private key (base64-encoded) |
### Slack integration (optional)
| Variable | Description |
|---|---|
| `FABRO_SLACK_APP_TOKEN` | Slack App-level token |
| `FABRO_SLACK_BOT_TOKEN` | Slack Bot token |
### Logging
| Variable | Default | Description |
|---|---|---|
| `FABRO_LOG` | `info` | Log level: `error`, `warn`, `info`, `debug` |
Reference in a new issue View git blame Copy permalink