Config file spec

floo’s primary config file is floo.app.toml. Services are declared inline under [services.<name>]. Managed-service declarations use [managed.<name>], and credential attachments live under service env blocks. A deploy provisions declared Postgres, Redis, and Storage resources that are missing. Removing a deployed declaration is tier-3. The shared default retains the resource without review or deletion; an explicit approval policy requires review. The legacy top-level [postgres], [redis], and [storage] sections are deprecated. floo.service.toml is an optional per-service config file that keeps a service’s configuration beside its code (the “delegated” layout). floo init creates floo.app.toml with your service declared inline.

Monorepos

By default a service builds with its own path as the Docker build context, and its Dockerfile must sit inside that directory. A service at ./apps/web cannot read ./packages, so a workspace whose packages import each other fails at install. Set dockerfile to build from the repository root instead:

floo.app.toml partial

[services.web]
type = "web"
path = "./apps/web"
dockerfile = "apps/web/Dockerfile"
port = 3000

[services.api]
type = "api"
path = "./apps/api"
dockerfile = "apps/api/Dockerfile"
port = 8000

The path is relative to the repository root, and it must stay inside the repository: an absolute path or one containing .. fails the deploy. Each service still builds its own image. The context is the whole repository, so COPY paths in those Dockerfiles are written from the root:

COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
COPY packages ./packages
COPY apps/web ./apps/web
RUN pnpm install --frozen-lockfile --filter web

path still marks where the service’s source lives, which is what floo dev and preflight’s source checks read, and it is what a service without dockerfile uses as its context. A service that sets dockerfile rebuilds whenever anything in the repository changes, not just its own directory. That is deliberate: its build can read the whole repository, so a change to a shared package has to invalidate it. floo init does not generate a Dockerfile for a workspace repository. The generated templates copy only the root manifest and lockfile, which cannot install a workspace, so it declines and says so rather than writing one that fails.

Config shapes

Shape	Files	When to use
Single service	`floo.app.toml`	One service, with or without managed credential attachments
Inline multi-service	`floo.app.toml`	All services defined in one file
Delegated multi-service	`floo.app.toml` + per-service `floo.service.toml`	Service config lives alongside service code

Single service

[app]
name = "my-app"
access_mode = "public"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
env_file = ".env"

[resources]
cpu = "1"
memory = "512Mi"
max_instances = 3

Single service with managed services

Declare the managed resources and app shape together:

[app]
name = "crm"

[managed.default]
type = "postgres"

[managed.cache]
type = "redis"

[managed.uploads]
type = "storage"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"

[services.web.env]
managed = ["postgres", "redis:cache", "storage:uploads"]

Inline multi-service

[app]
name = "full-stack"
access_mode = "accounts"

[resources]
cpu = "1"
memory = "512Mi"
max_instances = 3

[managed.default]
type = "postgres"

[managed.cache]
type = "redis"

[services.web]
type = "web"
path = "./web"
port = 3000
ingress = "public"

[services.web.env]
managed = []

[services.api]
type = "api"
path = "./api"
port = 8080
env_file = ".env"

[services.api.env]
managed = ["postgres", "redis:cache"]

[services.worker]
type = "worker"
path = "./worker"
port = 8081
command = "python -m worker"
cpu = "2"
memory = "2Gi"

[services.worker.env]
managed = ["postgres", "redis:cache"]

Inline and delegated are mutually exclusive per service. A service with port in floo.app.toml is inline, and both parsers ignore any floo.service.toml in its directory.

Delegated multi-service

Root floo.app.toml:

floo.app.toml

[app]
name = "full-stack"

[services.web]
type = "web"
path = "./web"

[services.api]
type = "api"
path = "./api"

web/floo.service.toml:

web/floo.service.toml

[app]
name = "full-stack"

[service]
name = "web"
type = "web"
port = 3000
ingress = "public"

api/floo.service.toml:

api/floo.service.toml

[app]
name = "full-stack"

[service]
name = "api"
type = "api"
port = 8080
ingress = "public"
env_file = ".env"

[resources]
cpu = "1"
memory = "1Gi"

The CLI requires type on every [services.<name>] entry, including delegated ones.

Field reference

`[app]`

Field	Type	Default	Description
`name`	string	required	App name (DNS-safe)
`access_mode`	string	`"public"` for a new app	`public` or `accounts`; `floo_accounts` is an alias for `accounts`. Applies to every environment without an override; see `[environments.<name>]`. When omitted, each environment keeps its current mode, and a new app starts `public`.

`[services.<name>]`

Field	Type	Default	Description
`type`	string	required	`web`, `api`, `worker`
`port`	integer	required, except on `worker`	Port the service listens on. A `worker` may omit it, but `floo dev` requires `port` on every service.
`ingress`	string	`"public"` for `web` and `api`, `"internal"` for `worker`	`public` (internet-facing) or `internal` (only reachable by other services in the same app)
`env_file`	string	none	Env file synced on deploy, relative to the service directory
`path`	string	required	Relative path to the service directory. Required by both parsers unless `repo` is set, in which case it defaults to that repository’s root. Declare `path = "."` for a local single-service app.
`repo`	string	none	GitHub repository for this service, in `owner/repo` form. Use inline configuration for a service in another repository.
`dockerfile`	string	none	Dockerfile path relative to the repository root. Setting it makes the repository root the build context, so the service can read shared packages outside its own `path`. Must stay inside the repository. See Monorepos.
`command`	string	image `CMD`	Production start command, run as `sh -c "<command>"` with the image `ENTRYPOINT` preserved. Required on a `worker` that shares a build `path` with a `web` or `api` service; the deploy is rejected without it, because the worker would otherwise boot the web command.
`dev_command`	string	none	Shell command run by `floo dev` to start the service locally. Example: `"npm run dev"`
`migrate_command`	string	none	Shell command run before `floo dev` starts the service, and as a one-off job on each deploy. Push deploys and promotions run it before traffic moves to the new revisions, and failure stops the deploy. Old code serves the migrated schema until cutover, so migrations must use expand-then-contract. See Run migrations through `migrate_command`. Example: `"alembic upgrade head"`
`cpu`	string	inherited	Per-service vCPU override. See CPU and memory values.
`memory`	string	inherited	Per-service memory override
`min_instances`	integer	inherited, then platform default	Web/API minimum. Omitted means `0` on every plan and in every environment, including production. Explicit `0` permits scale-to-zero. Set `1` or higher to keep instances warm. Invalid on workers.
`max_instances`	integer	inherited	Web/API autoscaling ceiling. Platform default is `3`.
`instances`	integer	`1` for workers	Fixed worker count. `0` pauses the worker. Invalid on web/API.

There is no build_args key. floo passes every env var whose name starts with NEXT_PUBLIC_, VITE_, or REACT_APP_ to the build as a Docker build arg, and a change to one of them rebuilds the service. Set them with floo env set NEXT_PUBLIC_API_URL=https://... --app my-app --env dev; they are also injected at runtime. Thread them through ARG and ENV in the Dockerfile. See Build-time variables and Thread build args into the build.

`[services.<name>.env]`

Per-service env contract in floo.app.toml, including single-service apps. In floo.service.toml, use the same fields in a top-level [env] block. Top-level [env] in floo.app.toml does not opt out: the CLI rejects it as an unknown key, and the push parser ignores it with an unknown_manifest_key warning. Move an existing [env] managed = [] under [services.NAME.env].

Field	Type	Default	Description
`required`	string array	`[]`	Env var names that must be set before deploy. A missing name fails the deploy with `MISSING_REQUIRED_ENV_VAR`.
`optional`	string array	`[]`	Env var names documented for the service but not required
`managed`	string array	implicit legacy mode	Managed service credentials to inject into this service: `postgres`, `redis`, `storage`, or named handles such as `postgres:analytics`

[services.web.env]
managed = []

[services.api.env]
required = ["STRIPE_SECRET_KEY"]
managed = ["postgres", "redis:cache"]

If no service declares managed, managed service credentials are injected into every service for backward compatibility. Once any service declares managed, services without it receive none.

`[service]` (floo.service.toml)

Each delegated service keeps its own floo.service.toml alongside its code. The CLI rejects unknown keys in this table.

Field	Type	Default	Description
`name`	string	required	Service name (DNS-safe). The CLI enforces 2-21 chars; the push parser accepts 1-63.
`type`	string	required	`web`, `api`, `worker`
`port`	integer	required	Port the service listens on
`ingress`	string	`"public"` for `web` and `api`, `"internal"` for `worker`	`public` or `internal`
`env_file`	string	none	Env file synced on deploy, relative to the service directory
`command`	string	image `CMD`	Production start command
`dev_command`	string	none	Shell command run by `floo dev` to start the service locally. Local only: the push parser ignores it with an `unknown_manifest_key` warning.
`migrate_command`	string	none	Shell command run before `floo dev` starts the service, and as a one-off job on each deploy
`min_instances`	integer	inherited, then platform default	Accepted by the CLI, but the push parser ignores it here with an `unknown_manifest_key` warning; set it in this file’s `[resources]` table. Web/API only; workers use `instances`.
`instances`	integer	`1` for workers	Fixed worker count. `0` pauses the worker.

cpu, memory, and max_instances do not belong in [service], and min_instances there has no effect on deploy. Put them in a [resources] table inside the same floo.service.toml; it takes the fields listed under [resources] and overrides the root file’s global values for that service.

`[resources]`

Field	Type	Default	Description
`cpu`	string	`"1"`	vCPU allocation. See CPU and memory values.
`memory`	string	`"512Mi"`	Memory allocation
`min_instances`	integer	`0`	Web/API minimum on every plan and in every environment, including production. Set `1` or higher to keep instances warm. Never inherited by workers.
`max_instances`	integer	`3`	Web/API autoscaling ceiling
`max_request_body_mb`	integer	`10`	Largest request body the gateway forwards to this app, in MB. Range `1` to `100`; other values fail the deploy.

Resource values are app-wide: each configured value applies to dev, preview, and prod alike. See [environments.<name>] for the fields that can vary. Per-instance request concurrency is fixed platform-wide at 80 and is not a config key; the CLI rejects a concurrency key, and the push parser ignores it with an unknown_manifest_key warning. Per-service resource fields override delegated service values, which override the global [resources] section. A delegated service’s per-service override goes in a nested [services.<name>.resources] table: flat cpu or memory on a delegated entry is rejected by the CLI and ignored on deploy. Workers use per-service instances instead of min_instances. See Scaling and availability for the four runtime postures and verification commands.

CPU and memory values

cpu accepts exactly four values, and each one accepts a fixed set of memory sizes:

`cpu`	Allowed `memory`
`"0.5"`	`256Mi`, `512Mi`, `1Gi`, `2Gi`
`"1"`	`512Mi`, `1Gi`, `2Gi`, `4Gi`
`"2"`	`1Gi`, `2Gi`, `4Gi`, `8Gi`
`"4"`	`2Gi`, `4Gi`, `8Gi`, `16Gi`

A cpu value outside this table, a memory value that appears in no row, or a memory value not allowed for the chosen cpu fails the deploy at config parse. When memory is omitted and the default 512Mi is not allowed for the chosen cpu, floo uses the largest size that row allows and writes the adjustment to the deploy log as a warning. Setting min_instances = 1 bills continuously for one ready instance, even while idle; rates are on getfloo.com/pricing. See Scaling and availability for migration behavior.

`[managed.<name>]`

Declare a managed service in config. <name> is a logical instance name and must be unique within the TOML [managed] table. Use [managed.default] for the resource that should expose conventional unsuffixed env vars. Additional named resources expose suffixed keys, such as DATABASE_URL_ANALYTICS or REDIS_URL_CACHE. A deploy provisions any declared service that doesn’t exist yet. Removing or disabling a previously deployed block produces a tier-3 to_deprovision proposal. By default, the resource keeps working without review or a teardown schedule. An explicitly configured approval policy requires human review; after approval, Redis and Storage receive a rescindable schedule while Postgres keeps working without one. Renaming a block proposes creation under the new name and removal of the old resource. Deploy does not delete data. Terminal deletion remains an explicit floo services remove action. floo services add <type> --name <name> is the operational provisioning lane for an existing app.

Field	Type	Default	Description
`type`	string	required	`postgres`, `redis`, or `storage`
`tier`	string	none	Ignored, except that a value other than `basic`, `standard`, or `performance` fails the deploy; see Postgres → Compute and limits.
`enabled`	boolean	`true`	Set `false` to exclude it from desired state; an existing config-declared resource becomes a removal proposal

[managed.default]
type = "postgres"

[managed.cache]
type = "redis"

The default Postgres service owns DATABASE_URL plus PG*; named Postgres services own only DATABASE_URL_<NAME>. Default and named Redis own REDIS_URL or REDIS_URL_<NAME>. Storage follows the same rule for STORAGE_BUCKET and the STORAGE_S3_* keys. Credentials are attached per service via the [services.<name>.env] managed field above. Managed Redis is cache-only: treat its contents as disposable. floo makes no backup, restore, or durability guarantee for it; keep authoritative data in Postgres.

`[preview]`

Deprecated for enablement. enabled and ttl_hours are read-time aliases for [github] preview_environments and preview_ttl_hours.

Field	Type	Default	Description
`enabled`	boolean	`true` when `ttl_hours` is present	Deprecated. Alias for `[github] preview_environments`; `ttl_hours` alone enables previews.
`ttl_hours`	integer	`72`	Deprecated. Alias for `[github] preview_ttl_hours`

They still work for one migration window, [github] wins whenever both are present, and each deploy that reads them emits a legacy_preview_toml warning. Move the values into [github] and delete them from [preview]. [preview.data] below is not deprecated and remains the hydration surface.

`[preview.data]`

Choose how a preview’s managed resources start. Applies to every attached managed Postgres, Redis, and Storage resource.

Field	Type	Default	Description
`mode`	string	`"empty"`	`empty`, `seed`, or `clone-dev`
`seed_command`	string	none	Required when `mode = "seed"`

[preview.data]
mode = "seed"
seed_command = "bin/rails db:seed"

Supported modes:

empty provisions a fresh preview Postgres branch with a blank database; migrations run from scratch.
seed provisions a fresh preview Postgres branch with a blank database, runs migrations, then runs seed_command once in a preview-scoped job.
clone-dev copies dev data from every attached managed resource: Postgres database data before migrations run, supported Redis key types with their TTLs, and Storage objects by server-side copy. Clone limits and per-resource behavior are in Preview environments.

Unsupported modes fail closed. Raw prod clone is not supported. clone-prod-sanitized, which requires sanitize_command, parses but fails at provisioning until the admin-gated runner exists. See Preview environments.

`[postgres]`, `[redis]`, `[storage]` (deprecated)

Deprecated in favor of [managed.<name>]. Top-level [postgres] / [redis] / [storage] sections still auto-provision on first deploy during the deprecation window, but every deploy that processes them emits a warning. floo services add provisions a missing resource or resolves a MANAGED_SERVICE_ALREADY_EXISTS 409 to the existing row, reporting it as already provisioned (already_provisioned: true in JSON). Replace legacy sections with modern [managed.<name>] blocks in floo.app.toml; declarations come from the manifest.

Legacy sections are top-level in floo.app.toml, not nested under [services.*].

Field	Type	Default	Description
`tier`	string	none	Ignored, except that a value other than `basic`, `standard`, or `performance` fails the deploy; see Postgres → Compute and limits.

`[environments.<name>]`

Per-environment overrides. <name> is dev, prod, or preview; a table with any other name that sets access_mode or edge fails the deploy. This table accepts only access_mode and edge. Resource fields are not accepted per environment (the CLI rejects them; the push parser ignores them with a warning) and must be set once in [resources] or on the service.

Field	Type	Default	Description
`access_mode`	string	`[app] access_mode`	`public` or `accounts` for this environment only; `floo_accounts` aliases `accounts`
`edge`	table	`[edge]`	Per-environment IP allow/deny rules. Same fields as `[edge]`.

[app]
name = "my-app"
access_mode = "public"

[environments.prod]
access_mode = "accounts"

Every forward deploy freezes one effective access mode for each of dev, prod, and preview, resolved per environment in this order:

[environments.<env>] access_mode
[app] access_mode
that environment’s current applied mode
the app’s stored access mode as the seed, only when the environment does not exist yet

The frozen map is applied to the target environment when its deploy goes live; a dev deploy never changes prod. Release and promote copy the map from the deploy they promote. Push, release, and promote apply a change from accounts to public unless your org or app has an approval policy that gates access broadening; then, for dev, an org admin or their authorized agent applies the committed change with floo redeploy --app <name> --rebuild.

`[domains."<hostname>"]`

Declare a custom domain in config. A prod release creates the domain, and floo activates it after DNS is configured. To stop serving a host, delete its block and release to prod; floo retires the host and retains its certificate and DNS authorization for 7 days. See Custom domains.

Field	Type	Default	Description
`service`	string	none	Service the hostname routes to. Omit on a single-service app.

[domains."app.example.com"]
service = "web"

Hostnames must be valid DNS names of at most 255 characters and appear once. Plan gates and reserved hostnames surface on the domain row after deploy, not as a parse error.

`[auth]`

Sign-in policy and branding for accounts mode. Both apply only to the target non-preview environment when a deploy goes live.

Field	Type	Default	Description
`access_policy`	string	`"invite"`	`invite`, `open`, or `domain`. Admission to an `accounts` app is by invitation only whichever value is set: `open` and `domain` are accepted but admit no one who was not invited.

[auth] allowed_domains is ignored. Push, release, and promote apply a looser access_policy unless your org or app has an approval policy that gates access broadening; then, for dev, an org admin or their authorized agent applies the committed change with floo redeploy --app <name> --rebuild.

`[auth.branding]`

Both parsers accept branding. The server validates lengths, URLs, and colors.

Field	Type	Default	Description
`display_name`	string	none	Name shown on the sign-in page, at most 80 characters
`logo_url`	string	none	`https` URL of the logo, at most 512 characters
`accent_color`	string	none	`#RRGGBB` hex color

[auth]
access_policy = "invite"

[auth.branding]
display_name = "Acme Internal"
logo_url = "https://static.example.com/logo.png"
accent_color = "#1f6feb"

A [auth] block that declares neither access_policy nor [auth.branding] changes nothing. A [auth] block without [auth.branding] clears stored branding for the target environment.

`[[routes]]`

Per-path access modes. Multi-service apps declare the complete table in floo.app.toml; each entry names a routable service and the table includes /. Implicit single-service apps keep the route grammar below and omit service.

Field	Type	Default	Description
`path`	string	required	Path prefix starting with `/`. No `?` or `#`; `/__floo` is reserved. Each path appears once.
`access`	string	required	`public`, `accounts`, or `api_key`
`api_key`	boolean	`false`	Also accept an app API key. `api_key = true` is valid only with `access = "accounts"`.
`scope`	string	none	Scope label a key must hold for this route. Valid only when `access = "api_key"` or `api_key = true`; `*` is rejected.
`service`	string	required for multi-service	Declared public-ingress `web` or `api` target. Omit for an implicit single service.

[[routes]]
path = "/"
access = "accounts"

[[routes]]
path = "/api"
access = "api_key"
scope = "read"

An app with any key-eligible route must also declare an explicit / route. In a multi-service app the table replaces conventional paths on every app hostname, including service aliases and verified custom domains. Add /api explicitly if it should still route to the API service. Longest-prefix selection chooses the service and auth policy; the backend receives the unchanged path. See App API keys and request history for the complete flow.

`[edge]`

IP and CIDR allow/deny rules evaluated at the gateway before a request reaches your app. Requires the Team plan or above. [environments.<env>.edge] overrides it for one environment; previews inherit the dev policy.

Field	Type	Default	Description
`rules`	array of tables	`[]`	Each rule has `action` (`allow` or `deny`) and `cidr`. First match wins. At most 100 rules.
`default_action`	string	`"allow"`	`allow` or `deny` for requests no rule matches
`enabled`	boolean	`true`	`false` keeps the policy in config without enforcing it

[edge]
default_action = "deny"
rules = [
  { action = "allow", cidr = "203.0.113.0/24" },
  { action = "allow", cidr = "2001:db8::/32" },
]

Inspect the live result with floo edge policy get --env prod and floo edge policy check <ip> --env prod.

`[cron.<name>]`

Scheduled jobs run by the platform, declared in floo.app.toml.

Field	Type	Default	Description
`schedule`	string	required	Cron expression, e.g. `"0 9 * * *"` for 9am UTC daily
`command`	string	required	Shell command executed in the target service container
`service`	string	required	Name of the service whose image runs the command
`timeout`	integer	`300`	Maximum execution time in seconds

Example:

[cron.daily-report]
schedule = "0 9 * * *"
command = "python -m reports.daily"
service = "api"
timeout = 600

`[github]`

Controls GitHub integration behavior for the connected repo.

Field	Type	Default	Description
`deploy_on_push`	boolean	`true`	When `false`, GitHub push webhooks do not trigger deploys, and the agent deploys with `floo redeploy`
`preview_environments`	boolean	`false`	When `true`, opening a pull request deploys a preview environment
`preview_ttl_hours`	integer	`72`	Lifetime from creation or the latest push refresh; traffic does not extend it

deploy_on_push is not Git-controlled: the push parser does not read it. Run floo redeploy from the local project without --app to send the value in the deploy request. A push alone does not apply it.

[github]
preview_environments = true
preview_ttl_hours = 72

Without legacy [preview] enablement keys, previews are off unless preview_environments = true; a missing key reconciles to off. preview_ttl_hours is read on every deploy whether or not previews are enabled, so a value declared next to preview_environments = false still applies to previews opted in per PR; when the key is absent those previews use the 72-hour default. Any pull request can override the app default with an authorized comment on that PR: /floo preview on opts one PR in, /floo preview off opts one PR out. See Preview environments.

Precedence

The CLI resolves the app in this order:

--app <name> flag
The nearest directory, walking up from the current one and stopping at a .git boundary, that holds floo.service.toml or floo.app.toml. When it holds both, floo.service.toml wins, and differing [app] name values in the two files are an error.

Access mode resolution, per environment:

[environments.<env>].access_mode
[app].access_mode in floo.app.toml
the environment’s current applied mode
the app’s stored access mode as the seed for an environment that does not exist yet

Resource precedence: per-service values override global [resources].

Validation

floo preflight --json

The CLI fails preflight if:

service names are duplicated
a service port is invalid, or a non-worker service has none
managed service sections are placed in floo.service.toml instead of floo.app.toml
a table contains a key the CLI does not know

​Monorepos

​Config shapes

​Single service

​Single service with managed services

​Inline multi-service

​Delegated multi-service

​Field reference

​[app]

​[services.<name>]

​[services.<name>.env]

​[service] (floo.service.toml)

​[resources]

​CPU and memory values

​[managed.<name>]

​[preview]

​[preview.data]

​[postgres], [redis], [storage] (deprecated)

​[environments.<name>]

​[domains."<hostname>"]

​[auth]

​[auth.branding]

​[[routes]]

​[edge]

​[cron.<name>]

​[github]

​Precedence

​Validation

Monorepos

Config shapes

Single service

Single service with managed services

Inline multi-service

Delegated multi-service

Field reference

`[app]`

`[services.<name>]`

`[services.<name>.env]`

`[service]` (floo.service.toml)

`[resources]`

CPU and memory values

`[managed.<name>]`

`[preview]`

`[preview.data]`

`[postgres]`, `[redis]`, `[storage]` (deprecated)

`[environments.<name>]`

`[domains."<hostname>"]`

`[auth]`

`[auth.branding]`

`[[routes]]`

`[edge]`

`[cron.<name>]`

`[github]`

Precedence

Validation