Skip to main content

​
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 git-backed

Every deploy builds a git commit, so every deploy traces back to a SHA. The commit comes from one of two places. Your GitHub repository. After a human installs the floo GitHub App and links it to your floo organization, 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 to dev, unless [github] deploy_on_push = false (see the config spec). A floo-hosted repository. No GitHub account needed. floo deploy pushes the committed code in a local git repository to a repository floo hosts, creating the project on the first run, and every push to its default branch deploys to dev. Uncommitted changes are never deployed. See Deploy without a GitHub repository.

​
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 with every operation in 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 an API call, and almost every one has a CLI command, so you can script anything and your agent can parse every response. A few settings are in the dashboard and API only: alert rules, error routing, and the spend-cap mode. 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, 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. See The dashboard is a window.

​
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

The split keeps app shape reviewable in git without forcing secrets or interactive workflows into the repo.

​
What lives in config

floo.app.toml is the source of truth for app shape and managed-service intent. Live provider state stays authoritative for the stored data itself. Repo-backed config holds:
  • app and service definitions
  • routing, [domains."host"] custom domain declarations, and edge rules
  • access mode and sign-in policy
  • ports and ingress
  • build settings
  • service paths
  • migrate and dev commands
  • managed Postgres, Redis, and Storage declarations
  • managed credential attachments
See floo.app.toml basics for common shapes and the config spec for every field.

​
What stays outside config

This state is managed outside the repo on purpose:
  • env vars and secrets
  • access grants and team membership
  • billing
  • API keys
  • live stored data, backups, and restores
  • confirmed terminal deletion, such as app or managed-service deletion
These are secret, operational, or live data. Config can declare that a managed service should exist, but never contains credentials or database contents. The platform database stays authoritative for live resource identity.

​
Service lifecycle

Each [services.NAME] name identifies a distinct application service. A rename creates a new identity and does not migrate data. When a service block is removed or renamed, the next successful full deploy to dev or preview retires the old runtime; prod deploys never retire one. The CLI has no application-service retirement command. floo services remove targets managed resources, not application services, and does not edit the manifest. If its managed declaration remains, a later push can provision the resource again. See managed-service removal for review and deletion. Put service environment contracts under [services.NAME.env], including for single-service apps. See credential attachments.

​
The dashboard is a window

The CLI and the HTTP API are the control plane. The dashboard is a readable view into the live system, for teammates who do not work from a shell:
  • releases and deploy history
  • logs and usage
  • team and access state
  • billing and operational settings
It is never a second source of truth for app shape in floo.app.toml. If the dashboard silently changed config the repo also declares, nobody could tell which state was real. Custom-domain status and DNS records are read-only there; declare or remove a host in floo.app.toml and release to prod.
  • Agents and power users operate from the CLI or the HTTP API.
  • Config changes are reviewed in git.
  • The rest of the team uses the dashboard for visibility.
The day-to-day loop:
  1. Write or update config in the repo.
  2. Run preflight and review the diff.
  3. Commit and push the config.
  4. Connect GitHub if needed, then watch the deploy.

​
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 an API call (almost always a CLI command too) with a JSON response the agent can parse, and every change to app shape is a config diff a human can review. Because config lives in the repo, agents read and edit it directly, and there is no second config system to reverse-engineer.

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

​
Next steps

Build with your stack

End-to-end guides for Next.js, Rails, FastAPI, Django, and Express.

floo.app.toml basics

The config patterns you reach for most.

Agent setup

Set up an agent on the CLI or the HTTP API.

Config spec

Every field in floo.app.toml with types, defaults, and precedence rules.