docs(self-hosting): Standalone default, Distributed, Helm chart, telemetry (ships with the next release)

[nik13]

Summary

Rewrites the Self-Hosting section for the self-hosting overhaul in future-agi/future-agi. After that release, the default ./bin/install gives Standalone: 3 containers, 2 vCPUs and 4 GB of Docker memory. Distributed (./bin/install --distributed) is the former multi-container stack, and Helm is a signed OCI chart for Kubernetes.

Merge this at release time, not before. Until then, these pages would tell v1.41.x users to run commands and use images they don't have yet.

Code PRs this documents, all open:

• feat(deploy): light Standalone install by default, Distributed at scale, Helm chart and hot-reload dev future-agi#3097: Standalone default, Distributed, ./bin/dev.
• feat(helm): publish the chart (signed OCI) with production and enterprise options future-agi#3098: Helm chart published at oci://ghcr.io/future-agi/charts/futureagi, signed.
• fix(gateway): send an org's key only to its own base URL; opt-in private provider URLs; keys survive restarts future-agi#3104: gateway per-org base URL, AGENTCC_ALLOW_PRIVATE_PROVIDER_URLS, key sync.
• fix: self-hosted bugs from end-to-end verification (workspace create and dates, SDK snippets, KB status, code eval model, custom model URL, login lockout, session list 500, dataset grid, secrets in logs, alerts, gateway edit, zero token cost) future-agi#3105: self-hosted bug fixes that users see (sign-in lockout, custom model URL).
• fix(gateway): deliver buffered request logs on shutdown; no panic after close; bounded log buffer future-agi#3132: gateway flushes request logs on shutdown.

What changed

• Overview (/docs/self-hosting):
  • a "Choose a setup" table comparing the three setups, and what each one runs;
  • a warning that Standalone data cannot move to Distributed or Helm;
  • how installs made with v1.41.x or earlier stay on Distributed;
  • a "What leaves your network" table.
• Requirements and Installation:
  • sizing and install steps per setup, with the installer flags;
  • verifying the stack, everyday operations and switching setups;
  • one link to the repo's docs/development.md for ./bin/dev.
  • The Compose cookbook now follows the Standalone default.
• New: Helm (Kubernetes) (/docs/self-hosting/helm):
  • supported configurations;
  • verifying the signature and attestation;
  • evaluation and production installs;
  • the first account, upgrades, backups and troubleshooting;
  • the support bundle.
• New: Telemetry (/docs/self-hosting/configuration/telemetry):
  • exactly what is sent and how to turn it off;
  • every other outbound connection;
  • a restricted-networks checklist.
  • The overview's old "nothing leaves your network" wording is corrected.
• New: Configuration reference (/docs/self-hosting/configuration/reference): every environment variable, per setup (Standalone, Distributed, Helm). It replaces the docs/configuration.md that feat(deploy): light Standalone install by default, Distributed at scale, Helm chart and hot-reload dev future-agi#3097 no longer ships. The page is generated: python3 scripts/docs_site.py sync <this checkout>, run in the code repo, renders it from deploy/env-reference.toml, whose completeness that repo's CI checks. Do not edit it by hand.
• New: Images (/docs/self-hosting/images): published images, tags, variants, architectures and how to verify an image. Its tables are generated from deploy/images.toml and the size budgets.
• New: Develop with hot reload (/docs/self-hosting/development): ./bin/dev for contributors. It replaces the repo's docs/development.md.
• Telemetry now also carries everything from the repo's docs/telemetry.md: the payload fields, examples, settings and browser hosts. Its tables are generated from wire_reference.toml.
• Configuration:
  • The environment page keeps the commonly set variables and links the generated reference page.
  • The Profiles, System and First-run setup pages (title only; the URL stays /launch-mode) are updated.
  • "Users & sign-in" is back in the nav.
• Production:
  • the checklist, security and TLS, backups, monitoring and upgrades, per setup;
  • the advice to set FRONTEND_PORT=127.0.0.1:3000 is removed, because the installer takes a port number only and that value breaks it.
• Troubleshooting and Support are updated for the new containers and commands.
• Agent Command Center:
  • a self-hosted install already runs the gateway;
  • local model servers on private addresses need AGENTCC_ALLOW_PRIVATE_PROVIDER_URLS=true;
  • keys re-sync every 60 s on self-hosted installs, where the old text said "every 15 seconds", which the gateway doesn't do;
  • buffered request logs are delivered on shutdown.
• Removed: the orphan pages self-hosting/docker-compose and self-hosting/configuration, with redirects.

Links into the code repo use blob/main, which matches the released version once this merges.

How it was checked

• Against the code: every command, flag, port, environment variable, default, image name and size figure was checked against the branches of the five PRs. Each page had an accuracy review and a style review, and every finding was fixed or answered.
• Consistency across pages:
  • no leftover "8 GB+" default or 21-service default;
  • no futureagi/platform;
  • container counts match docker compose config.
• Build:
  • npm run build: 1178 pages built, including the two new pages and the redirect pages;
  • npm run audit-links: 0 broken nav links, 0 broken content links.
  • No em dashes, per the style guide.
• npm ci fails on dev too, because package-lock.json is out of sync with package.json. That is unrelated to this PR; I built with npm install --no-save.

Before merging

• From the release tag of future-agi/future-agi, run python3 scripts/docs_site.py sync <this checkout> --ref vX.Y.Z --check. The generated reference, telemetry and images blocks must match that release's data. Without --check it rewrites them.
• The release that ships #3097, #3098, #3104, #3105 and #3132 is published. If #3104 or #3132 misses it, remove the parts that describe them: the private-provider-URL and key-sync text, and the shutdown log flush.
• helm pull oci://ghcr.io/future-agi/charts/futureagi --version X.Y.Z works without signing in, which means the GHCR package is public.
• futureagi/standalone:vX.Y.Z is on Docker Hub.
• docs(self-hosting): add Colima on macOS and make the Mac pages runtime-aware #869 (Colima) merged first, then this branch rebased. Two small conflicts are expected: the Apple Silicon note in installation.mdx and the Docker VM sizing tip in requirements.mdx. Keep this branch's text and add the Colima link.
• docs(self-hosting): add Colima on macOS and make the Mac pages runtime-aware #869's colima.mdx updated for the new stack. It still describes a 13-service stack with 8 GiB of memory, an amd64-only backend image, and development mode through docker-compose.dev.yml and DOCKER_SOCKET (now ./bin/dev). After that, link it from troubleshooting's "Docker cannot see the checkout" entry.

Follow-ups (not in this PR)

• Several cookbook pages say to point FI_BASE_URL at "your self-hosted deployment" without saying which address:

  • cookbook/quickstart/instrument-and-verify*.mdx;
  • cookbook/trustworthy-rag.mdx;
  • simulation/guides/run-chat-simulation.mdx.

  Tracing uses the collector on port 4318, and the API is on port 8000.

• command-center/concepts/configuration.mdx says self-hosted deployments watch the config file. The gateway re-reads it on POST /-/reload instead. This predates the overhaul.

AI use: Claude Code (Claude Opus 5.5) wrote the pages and checked them against the code, with separate accuracy and style reviewers per page. A maintainer needs to review it.

🤖 Generated with Claude Code