Skip to main content
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. Agents need a deterministic, reviewable file describing desired state. Keeping it in git means every change an agent makes arrives as a diff you can review.

​
What lives in config

Use repo-backed config for app shape:
  • 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
Example:

​
What stays outside config

Some state is intentionally managed outside the repo:
  • 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 by nature. Config can declare that a managed service should exist, but it never contains credentials or database contents. The platform database remains authoritative for live resource identity.

​
Why this matters for agents

When config lives in the repo:
  • agents can read and edit it directly
  • changes are reviewable in pull requests
  • the deploy surface is deterministic
  • there is no second config system to reverse-engineer
If the dashboard could mutate repo-backed config independently, the agent would no longer know which state was real.

​
Service lifecycle

Each [services.NAME] name identifies a distinct application service. A rename creates a new identity; it does not migrate data or retire the old runtime. Removing a service block does not retire its runtime, and the consumer 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. After a service change, run floo services list --app my-app --env dev --json. Compare both app_services and managed_services names with the declarations, and report missing or extra names. A running status can come from the environment’s deploy state and does not prove each service is healthy. A failed managed-service read can appear as an empty list in successful JSON, with its warning visible only in human output. Repeat the read without --json and check for that warning. If completeness is uncertain, report verification failure. Report retained application services, managed resources, and scheduled jobs explicitly; do not claim cleanup when retention is unverified.

​
The dashboard is a window

The dashboard is for visibility into the live system. It shows releases, logs, settings, team state, and usage. Custom-domain status and DNS records are read-only; declare or remove a host in floo.app.toml and release to prod. It does not become a competing source of truth for app shape that already lives in floo.app.toml.
  1. Write or update config in the repo.
  2. Run preflight and review it in git.
  3. Commit and push the config.
  4. Connect GitHub if needed, then watch the deploy.

Configuration

Learn the file shapes and common config patterns.

Dashboard vs CLI

See how the read/write split works in practice.