Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,12 @@
# FANOUT_DEFAULT_NAMESPACE=

# FANOUT_DUCKDB_MAX_CONNECTIONS; integer
# Caps the DuckDB connection pool. Reads scan immutable Parquet concurrently; rollup-cache writes are serialized by the query write gate. Zero means "size it from the machine" — the same spelling DuckDBThreads uses for deferring to a default. Resolution happens in resolveSizing and is reported in the startup configuration log.
# Caps the DuckDB read connection pool. Reads scan immutable Parquet concurrently; analytical and completed-batch writes use separate gates and connections. Zero selects available Go CPUs, bounded to 2–16. Startup logs and /readyz report the resolved pool size.
# Default: 0
# FANOUT_DUCKDB_MAX_CONNECTIONS=

# FANOUT_DUCKDB_MEMORY; string
# Caps DuckDB's memory (e.g. "8GB"). Empty means Fanout sizes it from detected memory, reserving headroom for the Go runtime; see resolveSizing. DuckDB's own default is 80% of detected RAM, which is calculated as though DuckDB owned the machine and has been observed to get the process OOM-killed once the Go heap is added on top.
# Caps DuckDB's memory (e.g. "8GB"). Empty selects 60% of detected available memory, reserving headroom for Go. If detection fails, DuckDB uses its default with a process headroom adjustment. Startup logs and /readyz report the resolved budget and detection status. Set an explicit cap when memory limit detection is incomplete.
# Default: (empty)
# FANOUT_DUCKDB_MEMORY=

Expand All @@ -91,7 +91,7 @@
# FANOUT_INGEST_BATCH_SIZE=

# FANOUT_INGEST_MAX_IN_FLIGHT_BYTES; integer
# Caps the decoded telemetry the process will hold across concurrent requests. Concurrency is HTTP/2 streams times connections and each handler holds its batch until the commit is durable, so without a ceiling a burst is bounded only by memory. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit.
# Caps decoded telemetry held across concurrent requests until durable publication. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit.
# Default: 268435456
# FANOUT_INGEST_MAX_IN_FLIGHT_BYTES=

Expand Down Expand Up @@ -178,7 +178,7 @@
# FANOUT_PPROF_ENABLED=

# FANOUT_PUBLIC_URL; string
# Sets the external browser origin. Required for OIDC; HTTPS is required with MCP.
# Sets the external browser origin, MCP token audience, and trusted MCP request origin. Required for OIDC; HTTPS is required with MCP.
# Default: (empty)
# FANOUT_PUBLIC_URL=

Expand Down
26 changes: 10 additions & 16 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,17 +62,16 @@ Run `just e2e` with Google Chrome installed for the separate CI browser smoke
suite. See [browser smoke testing](docs/testing.md) for coverage and failure artifacts.

`just install` also installs [Lefthook](https://lefthook.dev)'s Git hooks, which run
formatting and linting on commit and the full gate on push. That is the fastest
way to avoid a red CI run.
The pre-push hook may be skipped when Lefthook detects no changed files;
formatting and linting on commit and the full gate on push. The pre-push hook
may be skipped when Lefthook detects no changed files;
CI runs the same `just check` unconditionally and enforces the gate.

The browser workspace uses `package.json` overrides for transitive security
fixes that their direct dependencies have not locked yet. Keep those overrides
until the upstream ranges resolve to patched versions; `just ui-audit` accepts
only the existing build-only braces advisory exception documented in the justfile.

## Things that surprise people
## Repository conventions

**The browser assets are committed.** `ui/host` builds into `internal/ui/dist`
and its MCP app builds into `internal/mcp/apps`; both outputs are tracked in
Expand All @@ -96,15 +95,11 @@ the clone is labstack/fanout and contains the pinned revision. Archify normalize
and verifies repository identity and the pinned revision during `finalize`.
JSON inputs, SVG outputs, and the site copy still use your contributor checkout.

**The social preview card is generated.** `site/public/social-card.png` is
rendered from `docs/media/social-card.typ` by `just social-card`, which needs Inter on a
font path — set `FANOUT_FONT_PATH` to a directory holding it. CI has no such
directory, so nothing re-renders the card to compare it; what `site-build` does
assert is that the committed PNG exists and still matches the dimensions the
site's head advertises. If you edit the source, run the recipe and commit the
PNG in the same change. The recipe fails when the
font is missing rather than shipping a card in a substitute face, which typst
would otherwise do without complaint.
**The social preview card is generated.** `just social-card` renders
`docs/media/social-card.typ` into `site/public/social-card.png`. Set
`FANOUT_FONT_PATH` to a directory containing Inter; the recipe requires Typst
0.15.1 and fails if the font is missing. Commit the source and PNG together.
The site build checks the committed image’s dimensions; CI does not rerender it.

**Runtime configuration is strict.** `internal/config/config.go` owns the
schema. New settings need an environment name, a documentation `group` tag,
Expand Down Expand Up @@ -168,9 +163,8 @@ Before your first pull request can be merged, you need to sign the
[CLA](CLA.md). A bot comments on the pull request with a sentence to reply
with; that is the whole process, and it is only needed once.

The CLA grants LabStack the right to relicense contributions. That is what
keeps future licensing decisions possible — without it, any change would
require permission from every past contributor individually.
The CLA grants LabStack the right to relicense contributions. Review the
agreement before contributing.

## License

Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
</picture>

Fanout keeps OpenTelemetry traces, logs, and metrics in one binary and one data directory, with no
external services to operate. Fanout is pre-release and changes without migration paths; the browser
client, chat investigator, MCP tools, dashboards, and alerts are preview capabilities
external storage services to operate. Fanout is pre-release and changes without migration paths; the browser
client, built-in agent, MCP tools, dashboards, and alerts are preview capabilities
([status](https://fanout.run/status/capabilities)). Start with the
[documentation](https://fanout.run) or run it below.

Expand Down Expand Up @@ -101,7 +101,8 @@ See [AI settings](https://fanout.run/reference/settings/ai).

Set `FANOUT_PUBLIC_URL` to your stable, externally reachable HTTPS origin, then point a remote MCP
client at that origin's `/mcp` endpoint. The client discovers and registers through OAuth; you
authorize its scopes in the browser. See [connect over
authorize its scopes in the browser. The client must support MCP protocol `2026-07-28` over
stateless Streamable HTTP; older versions and the `initialize` handshake are unsupported. See [connect over
MCP](https://fanout.run/guides/connect-over-mcp) for setup and permissions.

## How it compares
Expand Down Expand Up @@ -207,7 +208,7 @@ generated assets, hooks, and project layout.
## Releases

Versions are CalVer — `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each month across all
maturity suffixes. Fanout is currently alpha (for example, `v2026.10.1-alpha`); GA has no suffix.
maturity suffixes. Fanout is alpha (for example, `v2026.10.1-alpha`); GA has no suffix.
Container tags omit the leading `v`, and every release moves `latest`. Tagged releases publish
identical manifests to Docker Hub (`labstack/fanout`) and GHCR (`ghcr.io/labstack/fanout`); GHCR is
canonical and also carries development images.
Expand Down
7 changes: 4 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,12 @@ these areas are especially relevant:
- Authentication and session handling — local email codes, OIDC, MCP OAuth
- Authorization between roles, and between browser sessions and MCP clients
- Ingest credential generation, storage, rotation, and enforcement
- Query paths that could read data outside the requesting namespace
- Query paths that bypass an explicit namespace filter or dashboard ownership
- Anything that turns telemetry content into executable behavior

The credential classes above are deliberately separate and are never
interchangeable. A finding that crosses those boundaries is in scope.
Namespaces filter telemetry queries; they do not restrict account access to data.
Every telemetry reader can query every namespace. Credential substitution and
cross-owner dashboard access are authorization findings.

## Supported versions

Expand Down
4 changes: 2 additions & 2 deletions cmd/fanout-docgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -486,10 +486,10 @@ var groups = map[string]groupPage{
},
"ai": {
Title: "AI provider settings",
Description: "The provider, key, model and base URL backing the chat investigator.",
Description: "The provider, key, model and base URL backing the built-in agent.",
Summary: "Chat is disabled unless a provider is selected; its API key is then required.",
ReadWhen: []string{
"The chat investigator is disabled and you want it on.",
"The built-in agent is disabled and you want it on.",
"You are pointing Fanout at a self-hosted or proxied model endpoint.",
},
},
Expand Down
20 changes: 2 additions & 18 deletions cmd/fanout-docgen/mcptools.go
Original file line number Diff line number Diff line change
Expand Up @@ -169,23 +169,7 @@ func renderMCPTools() ([]byte, error) {
b.WriteString("\n")
}
b.WriteString("## Authentication\n\n")
b.WriteString("MCP uses OAuth, not a static key, and **not the ingest token** — an agent\n")
b.WriteString("presenting the ingest token is rejected. A client discovers the endpoints,\n")
b.WriteString("registers itself, and is issued a token bound to this instance's resource\n")
b.WriteString("URI. [Connect an agent](/guides/connect-over-mcp) covers the flow.\n\n")

b.WriteString("The dashboard tools act on the authenticated user's **own** dashboards. The\n")
b.WriteString("capability boundary is `dashboards:manage-own`: an agent acts as the user\n")
b.WriteString("whose credential it holds and cannot reach anyone else's. A tool description\n")
b.WriteString("that tells a model when to call it is guidance to the model, not a\n")
b.WriteString("permission check — see [roles](/reference/roles).\n\n")

b.WriteString("## What is not here\n\n")
b.WriteString("No tool writes telemetry, changes configuration, manages users, or edits\n")
b.WriteString("alert rules. Ingest is OTLP only and the rest is HTTP surface — see\n")
b.WriteString("[HTTP routes](/reference/http-routes). An agent connected over MCP can read\n")
b.WriteString("everything the instance knows and manage its own dashboards, and that is the\n")
b.WriteString("whole envelope.\n")
b.WriteString("MCP uses OAuth tokens bound to the instance’s resource URI.\n[Connect an agent](/guides/connect-over-mcp#scopes) documents protocol\nrequirements and delegated scopes. Dashboard tools operate on the authenticated\nuser’s own dashboards and require the account capability\n`dashboards:manage-own`; see [roles](/reference/roles).\n\n## Other interfaces\n\nUse OTLP to write telemetry. Configuration uses environment variables, and user\nand alert management use the [HTTP API](/reference/http-routes).\n")

toolCount = tools
return []byte(b.String()), nil
Expand All @@ -206,7 +190,7 @@ func effect(tool mcp.ToolDoc) string {
func effectProse(tool mcp.ToolDoc) string {
switch {
case tool.ReadOnly:
return "Read-only. Calling it changes nothing."
return "Read-only."
case tool.Destructive && tool.Idempotent:
return "**Replaces existing state.** Calling it twice with the same arguments " +
"leaves the same result as calling it once, but the first call has already " +
Expand Down
10 changes: 2 additions & 8 deletions cmd/fanout-docgen/roles.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ var capabilityNotes = map[string]string{
"dashboards:manage-own": "Create and edit dashboards you own. Owner-scoped for every role, including admin.",
"ingest:read-metadata": "See ingest settings, but not the token itself.",
"alerts:manage": "Create, change and delete alert rules.",
"agent:run": "Run the chat investigator, which calls a model provider and acts on the instance's behalf.",
"agent:run": "Run the built-in agent, which calls a model provider and acts on the instance's behalf.",
"ingest:manage": "Rotate the ingest token.",
"users:manage": "Create, change and remove user accounts and their roles.",
"operations:read": "Read the instance's own internals: Prometheus metrics and, when enabled, the profiling endpoints.",
Expand Down Expand Up @@ -83,13 +83,7 @@ func renderRoles() ([]byte, error) {

b.WriteString("{/* Generated by cmd/fanout-docgen from internal/api. Edit the generator, not this page. */}\n\n")

b.WriteString("Fanout has three roles. They are fixed — there is no custom role builder, and\n")
b.WriteString("a user holds exactly one.\n\n")

b.WriteString("Every protected route names a capability rather than a role, and a role is a\n")
b.WriteString("set of capabilities. The table below is that set, read from the same map the\n")
b.WriteString("middleware consults, so it cannot describe a permission the server does not\n")
b.WriteString("grant.\n\n")
b.WriteString("Each user has one fixed role: `viewer`, `operator` or `admin`. The table is\ngenerated from the capability map enforced by the authorization middleware.\n\n")

b.WriteString("| Capability |")
for _, role := range roleOrder {
Expand Down
42 changes: 9 additions & 33 deletions cmd/fanout-docgen/routes.go
Original file line number Diff line number Diff line change
Expand Up @@ -249,14 +249,8 @@ func renderRoutes(routes []api.RouteDoc) []byte {
b.WriteString("OTLP shares this listener but uses its own handlers and ingest credential; see\n")
b.WriteString("[send your first telemetry](/start/send-telemetry).\n\n")

b.WriteString(":::note[What this table is, and what it is not]\n")
b.WriteString("Every route the binary registers, wherever it is registered — the application\n")
b.WriteString("handlers, the agent runtime, the operational and protocol endpoints, and the\n")
b.WriteString("SPA catch-all. A route the generator cannot get a classification for fails\n")
b.WriteString("the build, so a new route cannot quietly go undocumented.\n\n")
b.WriteString("It is the surface the binary *can* register, not the surface any particular\n")
b.WriteString("instance exposes. Some of it is conditional, so check the instance before\n")
b.WriteString("concluding a route is reachable — or that it is not:\n\n")
b.WriteString("## Conditional routes\n\nThe table includes every route the binary can register. These routes depend on\nconfiguration:\n\n")

b.WriteString("- `/debug/pprof/*` — only when `FANOUT_PPROF_ENABLED` is true, which is\n")
b.WriteString(" **not** the default. Enabling it also turns on mutex and block sampling.\n")
b.WriteString("- `/mcp`, `/api/mcp`, `/oauth/*` and `/.well-known/*` — only when\n")
Expand All @@ -267,27 +261,13 @@ func renderRoutes(routes []api.RouteDoc) []byte {
b.WriteString(" `FANOUT_AUTH_MODE=oidc`.\n\n")
b.WriteString("Everything else is always registered. A path shown with `:name` or `*` is the\n")
b.WriteString("pattern Echo matches on, not a literal URL.\n")
b.WriteString(":::\n\n")

b.WriteString(":::caution[Most of this is not a public API]\n")
b.WriteString("The `/api/*` routes are the browser client's own backend. They are listed here\n")
b.WriteString("so an operator can see the whole surface and what guards it — not as an\n")
b.WriteString("interface to build against. They change with the client, without notice and\n")
b.WriteString("without migration paths.\n\n")
b.WriteString("The supported programmatic interface is **MCP**, at `/mcp` — see\n")
b.WriteString("[MCP tools](/reference/mcp-tools). The stable non-MCP surfaces are OTLP\n")
b.WriteString("ingest, and the operational endpoints in [endpoints](/reference/endpoints).\n\n")
b.WriteString("Alert rules (`/api/alerting/rules`, `/api/alerting/alerts`) currently have no browser\n")
b.WriteString("page. Ingest-token rotation uses `POST /api/settings/ingest/token/rotate`\n")
b.WriteString("and is also available to administrators on **Connect telemetry**.\n")
b.WriteString(":::\n\n")
b.WriteString("\n")

b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client and can change without migration\npaths. [MCP](/guides/connect-over-mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/reference/endpoints) have their own contracts.\n\nManage alert rules through the [HTTP API](/guides/set-up-alerts). Administrators\nrotate ingest tokens on **Connect telemetry** or with\n`POST /api/settings/ingest/token/rotate`.\n\n")

b.WriteString("## Errors\n\nApplication API errors, including unknown routes and wrong methods, return objects shaped like\n`{\"code\":\"bad_request\",\"message\":\"Safe explanation\"}`. Codes are stable\nsnake_case identifiers; clients branch on `code` rather than message text.\nInvalid dashboard or panel specs also include `problems` with field paths,\nmessages and optional hints. Every error response uses `Cache-Control: no-store`;\nHEAD errors have no body. Server failures return a short, safe message; the\nunderlying error is logged and never returned.\n\nDefault codes by HTTP status:\n\n| Status | Code |\n|---|---|\n| 400 | `bad_request` |\n| 401 | `unauthorized` |\n| 403 | `forbidden` |\n| 404 | `not_found` |\n| 405 | `method_not_allowed` |\n| 409 | `conflict` |\n| 413 | `payload_too_large` |\n| 415 | `unsupported_media_type` |\n| 422 | `unprocessable` |\n| 429 | `rate_limited` |\n| 500 | `internal` |\n| 502 | `bad_gateway` |\n| 503 | `unavailable` |\n| 504 | `timeout` |\n\nOther 4xx statuses use `bad_request`; other 5xx statuses use `internal`.\nSpecific conditions use `already_current`, `dashboard_version_not_found`,\n`dashboard_version_conflict`, `invalid_spec` and `last_active_administrator`.\nTool failures carry `error: {code, message}` inside the tool result.\nPanel execution results keep their own status and error fields.\nOAuth, OTLP/gRPC, MCP JSON-RPC and AG-UI run errors keep their protocol spelling.\nOperational responses at `/healthz`, `/readyz` and `/metrics` keep their bodies.\n\n")

b.WriteString("The **Requires** column is not a description of the rule. It is the answer the\n")
b.WriteString("authorization middleware gives for that exact method and path, so a route\n")
b.WriteString("cannot be documented as public while the server treats it otherwise.\n")
b.WriteString("Capabilities map to roles in [roles](/reference/roles).\n\n")
b.WriteString("The **Requires** column comes from the authorization middleware for each method\nand path. [Roles](/reference/roles) maps capabilities to roles.\n\n")

b.WriteString("| Method | Path | Requires |\n")
b.WriteString("|---|---|---|\n")
Expand All @@ -296,19 +276,15 @@ func renderRoutes(routes []api.RouteDoc) []byte {
}

b.WriteString("\n## What the requirements mean\n\n")
b.WriteString("- **none** — reachable without a credential. The health endpoints are\n")
b.WriteString(" deliberately here: a probe that needs a credential fails for the wrong\n")
b.WriteString(" reason during an outage.\n")
b.WriteString("- **none** — reachable without a credential.\n")

b.WriteString("- **any signed-in user** — a session, but no particular capability.\n")
b.WriteString("- **protocol handshake** — the OAuth and MCP endpoints, which authenticate\n")
b.WriteString(" as part of their own protocol rather than through the middleware.\n")
b.WriteString("- **a named capability** — the caller's role must carry it.\n")
b.WriteString("- **or a service credential** — additionally reachable without a browser\n")
b.WriteString(" session, which is how a scraper reaches the metrics endpoint.\n\n")
b.WriteString("A method of `Any` means the route is registered for every verb, and the middleware\n")
b.WriteString("gives the same answer for all of them — where it would not, this page fails\n")
b.WriteString("to build rather than pick one. `GET /*` serves the single-page application\n")
b.WriteString("for browser paths. Unknown `/api/*` and OTLP paths return errors instead.\n")
b.WriteString("`Any` registers every HTTP method with the same authorization requirement.\n`GET /*` serves the single-page application for browser paths. Unknown `/api/*`\nand OTLP paths return errors.\n")

return []byte(b.String())
}
Loading
Loading