> ## 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, the CLI or the API for agents, dashboard as window. ## Four pillars ### 1. Config lives in the repo `floo.app.toml` defines the auditable shape of your app: services, routing, workers, cron jobs, managed Postgres, Redis, and Storage declarations, credential attachments, and resource limits. It is checked into git beside your code. Secret values stay outside git. That is what lets an agent operate floo safely: every change is a git diff, reviewable in a pull request, reproducible from a commit SHA. ### 2. Deploys are GitHub-backed No deploy uploads source from your machine. After a human [installs the floo GitHub App on the repo's owning account and authorizes floo through the setup link](/docs/guides/cli#find-the-command) in a browser, you connect a GitHub repo once with `floo apps github connect`. From then on floo builds and deploys from that repo's commits: every `git push` to the connected branch triggers a build and deploy, and every deploy traces back to a SHA. ### 3. Agents use the CLI or the API An agent drives floo through either of two equal surfaces: the floo CLI, where every command supports `--json`, or the HTTP API at `https://api.getfloo.com/v1`, starting from [agents.md](https://getfloo.com/agents.md) with every operation in [openapi.json](https://api.getfloo.com/openapi.json). Both sign in through the same device flow: `floo auth login` for the CLI, step 1 of agents.md for the API. Every operation has a CLI command, so you can script anything and your agent can parse every response. 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, but it does not own config. If the repo and the dashboard disagree, the repo wins, so an agent never has to guess which one is 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.** The agent assembles a host, an auth provider, a database, a Redis instance, a worker runner, a cron scheduler, and DNS with TLS from separate services, then keeps the credentials synchronized across all of them. **With floo.** The agent writes one `floo.app.toml` declaring the web service, worker, cron, managed Postgres, managed Redis, and credential attachments, runs preflight, and pushes the reviewed config. floo reconciles the declared resources and deploys the app on a custom domain with sign-in, logs, and every release kept for rollback. 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` (app shape and managed-service intent) | Reconciling services, routes, resources, and declared attachments | | Explicit lifecycle commands, from the CLI or the API | Inspecting state and executing confirmed operational changes | | 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 | The split 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 touches three kinds of systems: 1. **Source.** The repo, handled by git. 2. **Config.** The app shape, handled by `floo.app.toml` and reviewable in git. 3. **Runtime.** What is deployed, handled by the CLI with `--json` or by the HTTP API. There is no fourth surface: no separate auth console, database dashboard, or scheduler UI. Every operation is a CLI command or API call with a JSON response the agent can parse, and every change to app shape is a config diff a human can review. ## How incident detection routes to your agent When a deploy fails or a runtime error crosses its threshold, floo packages the context (error signature, recent deploys, log excerpt) and POSTs a signed event to a webhook URL you configure: an agent, an on-call bot, or an incident pipeline. floo detects and routes; 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.