# Fanout

One self-hosted binary for OpenTelemetry. The same Go process accepts OTLP
over gRPC and HTTP, publishes authoritative Parquet batches with persistent
trace indexes, runs embedded DuckDB analytics and rollups, evaluates alert
rules, serves a chat investigator and MCP tools, and hosts the browser client.

> Use this file as a map of the Fanout documentation. Fetch any page as
> Markdown by appending `.md` to its URL. Fanout is pre-release: entries
> marked PREVIEW run today but may change shape without a migration path,
> and entries marked PLANNED do not execute yet. Trust the marker over the
> confidence of the prose.

## Agent Resources

- [Markdown page export](https://fanout.run/docs/get-started/install.md): Append `.md` to any docs page URL for clean Markdown.
- [Full documentation text](https://fanout.run/llms-full.txt): Every page concatenated, for one-shot ingestion.
- [Sitemap](https://fanout.run/sitemap-index.xml): Crawler URL index.

## Operating Fanout from an agent

- Fanout reads built-in defaults and process environment. Native installs listen on 127.0.0.1:7520; the image supplies FANOUT_ADDR=:7520. Secret variables accept _FILE paths. Commands: `fanout [flags]`, `fanout version`, `fanout login-link <email>` (local recovery with host access), `fanout healthcheck [url]`, `fanout repair verify`, and `fanout repair quarantine --batch <id>`. Product operations use HTTP or MCP.
- MCP is the intended agent interface. The server exposes its tools at `/mcp`.
- External MCP clients authenticate with resource-bound OAuth tokens. The browser API uses browser sessions; `/api/mcp` uses the same session. These credentials do not authorize OTLP ingest.
- Telemetry goes in over OTLP only: gRPC and HTTP on the same port as the application (7520 by default). There is no bespoke ingest API to script against.
- Ingest always requires the ingest token, and rejects everything until the first administrator exists — a collector started before setup will fail until setup completes.
- Configuration is environment-only: built-in defaults followed by nonempty process environment values. Custom settings use FANOUT_; AI credentials and endpoints use ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, OPENAI_API_KEY and OPENAI_BASE_URL. Unknown FANOUT_ setting names fail startup, except platform-injected service-discovery names. Chat is off unless FANOUT_AI_PROVIDER selects anthropic or openai and its required key is supplied; OPENAI_BASE_URL includes /v1.

## Overview

- [Documentation](https://fanout.run/docs.md): Install Fanout, send OpenTelemetry, and configure investigations, dashboards and alerts.
- [Observability your agents can operate.](https://fanout.run/index.md): Investigate with Fanout's built-in agent, or use the same typed tools from your own agent over MCP.

## Get started

- [First boot](https://fanout.run/docs/get-started/first-boot.md): Configuration validation, the one-time setup URL, and the ingest token you are shown once. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The process refuses to start and you want to know what it validated.
  - Read when: You have a running instance and need to create the first administrator.
- [Install](https://fanout.run/docs/get-started/install.md): The three ways to get the binary onto a machine, and the ports and paths each one opens.
  - Read when: You are putting Fanout on a machine for the first time.
  - Read when: You need to know which ports and paths an instance uses.
- [What Fanout is](https://fanout.run/docs/get-started/overview.md): Agent investigations, dashboards and telemetry storage in one process, with one data directory. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding whether Fanout fits before installing anything.
  - Read when: You want to know what Fanout replaces in an existing observability stack.
- [Send your first telemetry](https://fanout.run/docs/get-started/send-telemetry.md): The ingest token, one shared OTLP address, and a working SDK and Collector configuration. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You have a running instance and nothing in it yet.
  - Read when: An exporter is being rejected and you need to know which credential it wants.

## Guides

- [Set up alerts](https://fanout.run/docs/guides/alerts.md): The rule model, the variables available to an expression, the pending/firing/resolved lifecycle, and webhook delivery. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to be told when a service degrades.
  - Read when: A rule is not firing when you expect it to.
- [Back up and restore](https://fanout.run/docs/guides/backup-and-restore.md): The whole data directory is the unit of backup. Copying part of it does not produce a recoverable instance.
  - Read when: You are putting an instance into production.
  - Read when: You are restoring after a host loss, or moving an instance between machines.
- [Build and refine dashboards](https://fanout.run/docs/guides/dashboards.md): Chat authoring, fifteen panel types, variables, comparison, view links, saved versions and keyboard controls. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to build or change a dashboard from chat.
  - Read when: You want to inspect a failed panel, share a view or restore a saved version.
- [Connect an agent over MCP](https://fanout.run/docs/guides/mcp.md): The OAuth flow an MCP client uses, the two scopes, and the one setting that has to be right before any of it works. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting Claude Code or another MCP client to an instance.
  - Read when: A client registers but its tokens are rejected.
- [Tune retention](https://fanout.run/docs/guides/retention.md): Retention, atomic batch sizing, and the maintenance pass that keeps query latency bounded. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Disk use is growing faster than expected.
  - Read when: Query or rollup latency is climbing on an instance that was fine.
- [Terminate TLS](https://fanout.run/docs/guides/tls.md): The two supported TLS patterns, and the proxy-trust setting that has to accompany the second one. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are exposing an instance beyond a trusted network.
  - Read when: Browser session cookies are not coming back Secure.
- [Troubleshoot](https://fanout.run/docs/guides/troubleshooting.md): Startup refusals, rejected exporters, locked-out users, and where to look when telemetry is not arriving. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The process will not start, or an exporter is being rejected.
  - Read when: Someone cannot sign in and SMTP is not configured.

## Reference

- [Alert expression variables](https://fanout.run/docs/reference/alert-expressions.md): The variables available to a CEL alert rule. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are writing an alert rule and need the variable names.
  - Read when: A rule compiles but never fires, and you want to check what it is reading.
- [HTTP routes](https://fanout.run/docs/reference/api.md): Application, operational and protocol routes and the SPA catch-all, with the authorization requirement for each. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are auditing what an instance exposes and what guards each route.
  - Read when: A request came back 401 or 403 and you want to know which capability it wanted.
- [Shipped vs planned](https://fanout.run/docs/reference/capabilities.md): Capability availability, contract stability and operating limits. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding whether to build something durable on a Fanout capability.
  - Read when: A page describes something and you want to know whether it executes today.
- [Configuration](https://fanout.run/docs/reference/configuration.md): Setting precedence, naming, secret files, and validation. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are configuring an instance and want the rules before the list.
  - Read when: A setting you set appears to have been ignored.
- [AI provider settings](https://fanout.run/docs/reference/configuration/ai.md): Chat is disabled unless a provider is selected; its API key is then required. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The built-in agent is disabled and you want it on.
  - Read when: You are pointing Fanout at a self-hosted or proxied model endpoint.
- [Alert settings](https://fanout.run/docs/reference/configuration/alerts.md): Settings for the alert evaluation loop. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Alerts are evaluating too slowly, or not at all.
- [Authentication settings](https://fanout.run/docs/reference/configuration/auth.md): Settings for how people sign in and how long their sessions last. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are moving an instance from local sign-in to an identity provider.
  - Read when: You need to map provider groups onto Fanout roles.
- [Ingest settings](https://fanout.run/docs/reference/configuration/ingest.md): Settings for how telemetry arrives and how it is batched before it is written. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Exporters cannot reach the instance.
  - Read when: You are tuning write throughput or flush latency.
- [MCP settings](https://fanout.run/docs/reference/configuration/mcp.md): Settings for the MCP endpoint external agents connect to. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting an external agent to a Fanout instance.
- [Metrics settings](https://fanout.run/docs/reference/configuration/metrics.md): Settings for the Prometheus scrape endpoint at /metrics. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are scraping Fanout's own metrics.
- [Server settings](https://fanout.run/docs/reference/configuration/server.md): Settings for the listener that serves the browser, API, chat, MCP and both OTLP transports. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are putting Fanout behind a reverse proxy.
  - Read when: Browser sessions are not getting Secure cookies.
- [SMTP settings](https://fanout.run/docs/reference/configuration/smtp.md): Settings for outbound email, which local sign-in uses to deliver codes. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Sign-in codes are not arriving.
- [Storage settings](https://fanout.run/docs/reference/configuration/storage.md): Settings for where telemetry lives, how long it is kept, and how DuckDB is sized. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing an instance for a host.
  - Read when: Disk use or query latency is growing and you need the maintenance knobs.
- [Data layout](https://fanout.run/docs/reference/data-layout.md): The exact contents of FANOUT_DATA_DIR, and why the directory is one unit. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing disk or deciding what to back up.
  - Read when: You are inspecting an instance's files and want to know what you are looking at.
- [Endpoints](https://fanout.run/docs/reference/endpoints.md): Health, readiness, metrics, profiling and the protocol endpoints, with the credential each expects. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are configuring a load balancer, a probe or a Prometheus scrape.
  - Read when: You need to know which endpoints are reachable without authentication.
- [FanQL](https://fanout.run/docs/reference/fanql.md): FanQL syntax, fields, functions, variables, null semantics and examples, generated from query registries. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are writing a FanQL query and need syntax or field names.
- [MCP tools](https://fanout.run/docs/reference/mcp.md): 20 tools served at /mcp, each with its inputs and mutation semantics. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting an agent and want to know what it can call.
  - Read when: You need to know which tools mutate state and which cannot.
- [Roles](https://fanout.run/docs/reference/roles.md): viewer, operator and admin, and what each is permitted to do. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding which role to give someone.
  - Read when: You are mapping identity-provider groups onto Fanout roles.
  - Read when: A request came back 403 and you want to know which capability it needed.

## Concepts

- [Why one binary](https://fanout.run/docs/concepts/architecture.md): What collapsing an observability stack into one process buys, and what it costs.
  - Read when: You are evaluating Fanout against an assembled stack.
  - Read when: You want to know where the single-process design stops being an advantage.
- [Authentication modes](https://fanout.run/docs/concepts/authentication.md): Local codes versus an identity provider, who owns roles in each, and what happens on every login. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are choosing between local sign-in and OIDC.
  - Read when: You expect a provider group change to take effect and want to know when it does.
- [Performance](https://fanout.run/docs/concepts/performance.md): Sustained mixed ingest at 415,859 items/s on a Hetzner ccx33.
  - Read when: You want to understand the performance figure on the landing page.
  - Read when: You need to measure an instance for your own load.
- [How storage works](https://fanout.run/docs/concepts/storage.md): Atomic Parquet ingestion, indexed trace reads, DuckDB analytics, and SQLite control state. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing disk, or deciding what to back up.
  - Read when: You want to understand ingest durability or query performance.

## Site terms

- [Privacy](https://fanout.run/privacy.md): Website analytics, consent controls, browser storage and hosting; separate from a self-hosted Fanout instance.
  - Read when: You want to know what this website records about your visit.
  - Read when: You allowed or declined analytics and want to change that answer.