> ## Documentation Index > Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # How floo Works > The mental model. Config in the repo, GitHub-backed deploys, CLI-first, dashboard as window. floo's control plane has four pillars. Once you understand them, the rest of the product is just depth. ## Four pillars ### 1. Config lives in the repo `floo.app.toml` defines the recoverable shape of your app: services, routing, workers, cron jobs, managed credential attachments, and resource limits. It's checked into git alongside your code. Durable resources like managed Postgres, Redis, and Storage are provisioned with explicit CLI commands and recorded in `.floo/services.lock`. This is why your agent can operate floo safely: every change is a git diff, reviewable in a pull request, reproducible from a commit SHA. ### 2. Deploys are GitHub-backed The CLI does not upload source. You connect a GitHub repo once with `floo apps github connect`, and from then on floo builds and deploys from that repo's commits. Every `git push` to the connected branch triggers a build and deploy automatically. Every deploy is traceable back to a SHA. Reproducible, auditable, rollable. ### 3. The CLI is the primary interface Every operation has a CLI command, and every command supports `--json`. That means you can script anything, your agent can parse every response, and error codes are stable and documented in the [error reference](/docs/reference/error-codes). ### 4. The dashboard is a window, not the source of truth The dashboard shows logs, releases, usage, and settings. It is a readable operational surface, but it does not own config. If the repo says one thing and the dashboard says another, the repo wins. This matters for agents: an ambiguous control plane is a broken control plane, and floo avoids the drift by keeping repo-backed config authoritative. ## A concrete example Alice's agent writes a SaaS app with sign-in, a Postgres-backed dashboard, a Stripe webhook worker, and a nightly cleanup job. **Without floo.** Alice's agent picks a host (Railway or Fly), adds Clerk for auth, Supabase for Postgres, Upstash for Redis, a separate worker runner, a cron service, and Cloudflare for the domain. Six accounts, six dashboards, six bills. The agent has to learn six APIs and keep the secrets synchronized across all of them. **With floo.** Alice's agent writes one `floo.app.toml` declaring the web service, worker, cron, and managed credential attachments. It runs `floo services add postgres` and `floo services add redis` for the durable data plane. `git push` and it's live on a custom domain with sign-in, logs, and a rollback button. One account, one dashboard, one bill. ## What floo manages vs what you manage | You own | floo manages | | -------------------------------------------------- | ---------------------------------------------------------------------- | | Source code and Dockerfile | Building and deploying the image | | `floo.app.toml` (the shape of the app) | Building services, routing traffic, and injecting declared attachments | | `floo services` commands and `.floo/services.lock` | Provisioning durable Postgres, Redis, and Storage resources | | Environment variable values | Injecting them into the container | | Custom domains (the DNS records) | TLS certificates, HTTPS termination | | App-level auth rules (who can sign in) | Hosted OAuth flow, JWT issuance, refresh tokens | | Worker and cron code | Scheduling, retries, log delivery | | Deciding when to roll back | Keeping every release reachable for rollback | Everything on the left lives in your repo or your agent's control. Everything on the right is infrastructure floo abstracts away. The split is deliberate: it keeps app shape reviewable in git without forcing secrets or interactive workflows into the repo. ## Why this matters for agents An agent writing and operating software has to touch three kinds of systems: 1. **Source.** The repo. Git handles this. 2. **Config.** The app shape. `floo.app.toml` handles this, reviewable in git. 3. **Runtime.** What's actually deployed. The CLI with `--json` handles this. There is no fourth surface. No separate auth console to configure. No separate database dashboard to provision. No separate scheduler UI to register cron jobs. Every operation is a CLI call your agent can make, with a JSON response it can parse, and either repo config or a generated lock-file diff a human can review. That is the product thesis: **one control plane that agents can operate safely, and humans can inspect trivially.** ## How incident detection routes to your agent When a deploy fails or a runtime error crosses threshold, floo packages the context (error signature, recent deploys, log excerpt) and POSTs a signed event to a webhook URL you configure, typically an agent, on-call bot, or incident pipeline. floo does not claim to generate code fixes itself. Detection and routing are the product boundary; remediation stays with your downstream workflow. See [agent webhooks](/docs/guides/agent-webhooks) for the event shape and the lifecycle states. ## Where to go next Tactical walkthrough from `floo auth login` to a live URL. Every field in `floo.app.toml` with types, defaults, and precedence rules.