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 used only when you want service configuration to live alongside each service’s 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 = "password"

[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. If a service has type and port in floo.app.toml, do not also place a floo.service.toml in that service’s directory. The CLI rejects this during preflight.

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"`	`public`, `password`, or `accounts`; `floo_accounts` is an alias for `accounts`. The default for every environment; see `[environments.<name>]` for overrides.

`[services.<name>]`

Field	Type	Default	Description
`type`	string	required	`web`, `api`, `worker`
`port`	integer	required	Port the service listens on. The deploy parser lets a `worker` omit it, but `floo preflight` and `floo redeploy` require `port` on every inline service, so declare one on workers too.
`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. Release promotion without rebuilding runs it before any application revision changes, so migrations must use expand-then-contract while old code can still serve the migrated schema. Failure semantics differ by lane; 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. Both parsers ignore top-level [env] in floo.app.toml without error, so an existing [env] managed = [] no longer opts out; move it 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, 2-21 chars)
`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, accepted by the push parser. The CLI rejects it here; declare it on the root `[services.<name>]` entry for CLI deploys.
`dev_command`	string	none	Shell command run by `floo dev` to start the service locally
`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	Web/API minimum. Omitted means `0` on every plan and in every environment, including production. Invalid on 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]. 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; a concurrency key fails config parse. Per-service resource fields override delegated service values, which override the global [resources] section. 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, or a memory value that appears in no row, fails the deploy at config parse. A memory value that is valid in general but not for the chosen cpu is adjusted to a size that row allows, and the adjustment is written to the deploy log as a warning. Setting min_instances = 1 bills continuously for one ready instance, even while idle. Under the floo-credits-2026-09 rate policy the default 1 vCPU / 512 MiB shape is about

42/month warm, and the 1.5 vCPU / 768 MiB shape a managed-Postgres attachment runs is about

63/month warm, excluding request activity and credits. See Scaling and availability for the arithmetic and 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	Validated against `basic`, `standard`, and `performance`; any other value fails the deploy. The accepted value has no effect: every managed service ships with the same defaults.
`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 STORAGE_URL. 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 fresh preview branches and copies no data.
seed provisions fresh preview branches, runs migrations, then runs seed_command once in a preview-scoped job.
clone-dev copies dev data from every attached managed resource: Postgres schema 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, and sanitized prod clone is unavailable 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.

If you’re still on the legacy authoring path, the sections are top-level in floo.app.toml (not nested under [services.*]).

Field	Type	Default	Description
`tier`	string	none	Validated against `basic`, `standard`, and `performance`; any other value fails the deploy. The accepted value has no effect: every managed service ships with the same defaults. See Postgres defaults and limits.

`[environments.<name>]`

Per-environment overrides. <name> is dev, prod, or preview; any other name fails the deploy. This table accepts only access_mode and edge; resource fields are not accepted per environment and must be set once in [resources] or on the service.

Field	Type	Default	Description
`access_mode`	string	`[app] access_mode`	`public`, `password`, 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
[app] 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 cannot loosen an environment from accounts or password to public; for dev, an org admin or their authorized agent can apply the committed change with floo redeploy --app <name> --rebuild. Setting password requires a shared password to exist already, which an org admin creates through the app’s access settings.

`[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` admits only invited users; `open` lets anyone sign up; `domain` admits emails matching a domain in the existing allowlist.

The existing domain allowlist still governs domain admission, but cannot be extended: its dashboard/API management controls were retired. [auth] allowed_domains is ignored. Push, release, and promote cannot loosen access_policy; for dev, an org admin or their authorized agent can apply the committed change with floo redeploy --app <name> --rebuild.

`[auth.branding]`

The push parser accepts branding. The CLI parser rejects [auth.branding], so a manifest declaring it cannot pass floo preflight or a local-config floo redeploy until schema parity lands.

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`, `password`, or `api_key`
`api_key`	boolean	`false`	Also accept an app API key on an `accounts` or `password` route
`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 as [cron.<name>] sections 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`	Idle preview lifetime before the reaper tears it down

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

When you run a command without --app, the CLI resolves the app in this order:

--app <name> flag
Nearest floo.service.toml
Nearest floo.app.toml

Access mode resolution, per environment:

[environments.<env>].access_mode
[app].access_mode in floo.app.toml
the environment’s current applied mode
[app].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 missing
an inline service also has a floo.service.toml in its directory
a multi-service app has no public service
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