dev

Starts every service in a floo app locally, with credentials for its floo-managed services injected.

floo dev

Run it from the project tree containing floo.app.toml. It takes no path argument.

Flags

Flag	Description	Default
`--app APP`	App name or UUID (reads from config if omitted)	inferred from config
`--fixture-user EMAIL`	For `accounts`-mode apps, start an auth proxy that injects `X-Floo-User-*` headers so you can test signed-in flows locally	off
`--fixture-id ID`	Identity for the fixture user	`dev-fixture-<email-localpart>`
`--fixture-name NAME`	Display name for the fixture user	the email
`--fixture-role ROLE`	Role for the fixture user	`member`
`--preflight`	Print the services and ports that would start, without creating a dev session or starting processes	off

The --fixture-* flags take effect only for apps with access_mode = "accounts"; for any other mode floo dev warns and skips the proxy. Walkthrough: App sign-in → Local development.

What happens

Resolve: reads floo.app.toml and collects every service’s dev_command
Session: creates a dev session through the floo API
Env injection: readable dev config and managed credentials follow the service’s env.managed attachment plan. Write-only secrets are withheld; their names appear in withheld_secret_keys and each affected process’s FLOO_WITHHELD_SECRET_KEYS. Supply those values from your local environment or a local secret store.
Migrations: a service’s migrate_command, if set, runs before that service starts
Start: each dev_command is spawned in its service’s path directory with a colored terminal prefix
Cleanup: on Ctrl+C, all child processes are terminated and the dev session is deleted

Requirements

floo.app.toml must exist in the project directory
Every service must declare dev_command, except services with repo = "owner/repo", which are skipped with a warning
Every service floo dev starts must have path and port set
Each service must use a unique port

Example

# floo.app.toml
[app]
name = "my-app"

[managed.default]
type = "postgres"

[managed.cache]
type = "redis"

[services.web]
type = "web"
path = "./web"
port = 3000
dev_command = "npm run dev"

[services.api]
type = "api"
path = "./api"
port = 8000
dev_command = "uv run uvicorn app.main:app --reload --port 8000"
migrate_command = "uv run alembic upgrade head"

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

floo dev

Terminal output:

Dev session started for my-app (abc12345)
  Redis: connection env vars injected

Service  Port  URL
web      3000  http://localhost:3000
api      8000  http://localhost:8000

[api] Running migrations for api...
[api] started (pid 12345)
[web] started (pid 12346)
[api]  INFO  Application startup complete.
[web]  ready started server on 0.0.0.0:3000

Discovery vars

Each service receives env vars pointing to the other local services:

Var	Example value
`<NAME>_URL`	`http://localhost:8000`
`VITE_<NAME>_URL`	`http://localhost:8000` (web services only)
`NEXT_PUBLIC_<NAME>_URL`	`http://localhost:8000` (web services only)
`FLOO_ALLOWED_ORIGINS`	`http://localhost:3000` (non-web services)

For example, a web service in a web + api app receives API_URL=http://localhost:8000 and NEXT_PUBLIC_API_URL=http://localhost:8000.

JSON output

floo dev --json redacts secret-shaped values by default and sets contains_secrets: true so agent harnesses can reject the payload. Use --reveal-secrets only when you control the destination, such as a local file outside agent context. The child processes still receive the real values.

floo dev --json 2>/dev/null

Startup emits a single JSON object. postgres_authorized is a compatibility field and is false; postgres_reachable is null when no legacy authorization probe ran:

{
  "success": true,
  "data": {
    "session_id": "abc12345-...",
    "app": "my-app",
    "postgres_authorized": false,
    "postgres_reachable": null,
    "withheld_secret_keys": [],
    "services": [
      {
        "name": "api",
        "port": 8000,
        "url": "http://localhost:8000",
        "auth_proxied_url": null,
        "env_vars": {
          "DATABASE_URL": "***REDACTED***",
          "REDIS_URL_CACHE": "***REDACTED***",
          "WEB_URL": "http://localhost:3000"
        }
      }
    ]
  },
  "contains_secrets": true
}

Log lines stream as newline-delimited JSON events:

{"event": "log", "service": "api", "stream": "stdout", "line": "Application startup complete."}

Session end:

{"event": "session_ended", "session_id": "abc12345-..."}

Errors

Code	Meaning
`NOT_AUTHENTICATED`	Run `floo auth login` first
`NO_CONFIG_FOUND`	No `floo.app.toml` found. Run `floo init` first
`NO_DEPLOYABLE_SERVICES`	`floo.app.toml` defines no services
`INVALID_PROJECT_CONFIG`	A service is missing `dev_command` or `path`, or two services share a port
`MISSING_PORT`	A service has no `port`; `floo dev` needs one on every service, workers included
`APP_NOT_FOUND`	The app doesn’t exist in floo

CLI

Config and runtime

Errors

API

Flags

What happens

Requirements

Example

Discovery vars

JSON output

Errors

​Flags

​What happens

​Requirements

​Example

​Discovery vars

​JSON output

​Errors

Flags

What happens

Requirements

Example

Discovery vars

JSON output

Errors