How floo Works

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.

​

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

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 for the event shape and the lifecycle states.

​

Where to go next