How floo works

floo’s control plane has four pillars.

​

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’s checked into git alongside your code. Secret values stay outside git, and .floo/services.lock records operational managed-service mutations. 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

No deploy uploads source from your machine. 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.

​

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 has to assemble a host, an auth provider, a database, a Redis instance, a worker runner, a cron scheduler, and DNS with TLS from separate services, then keep the credentials synchronized across all of them. With floo. Alice’s agent writes one floo.app.toml declaring the web service, worker, cron, managed Postgres, managed Redis, and credential attachments. It 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

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.

​

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, such as an agent, an on-call bot, or an incident pipeline. 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