Skip to main content
Start all services in a floo app locally, with credentials from your floo-provisioned managed services injected automatically. 
floo dev [PATH]

​
Arguments

ArgumentDescriptionDefault
PATHProject directory containing floo.app.toml. (current directory)

​
Flags

FlagDescriptionDefault
--app APPApp name or UUID (reads from config if omitted)—
--fixture-user EMAILFor accounts-mode apps, start an auth proxy that injects X-Floo-User-* headers so you can test signed-in flows locally—
--fixture-id IDIdentity for the fixture userdev-fixture-<email-localpart>
--fixture-name NAMEDisplay name for the fixture userthe email
--fixture-role ROLERole for the fixture usermember
The --fixture-* flags only take effect for apps with access_mode = "accounts"; against any other mode floo dev warns and skips the proxy. See Add User Auth → Local development for the full walkthrough.

​
What happens

  1. Resolve — reads floo.app.toml and collects all services with a dev_command
  2. Session — creates a dev session via the floo API
  3. Postgres auth — if the app has managed Postgres, your public IP is authorized for direct connections
  4. Env injection — global + per-service env vars are decrypted and injected into each service process. Managed service credentials follow the same env.managed attachment plan as deploy; DATABASE_URL is rewritten to point to the Cloud SQL public IP when Postgres access is authorized.
  5. Migrations — if migrate_command is set for a service, it runs before that service starts
  6. Start — each service’s dev_command is spawned in its path directory with a colored prefix in the terminal
  7. 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 have dev_command, path, and port set
  • Each service must use a unique port

​
Example

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

[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"]

floo dev
Terminal output: 
Dev session started for my-app (abc12345)
  Postgres: your IP is authorized for direct connections
  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 services running locally:
VarExample value
<NAME>_URLhttp://localhost:8000
VITE_<NAME>_URLhttp://localhost:8000 (web services only)
NEXT_PUBLIC_<NAME>_URLhttp://localhost:8000 (web services only)
FLOO_ALLOWED_ORIGINShttp://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 emits managed-service credentials in plaintext. The startup envelope contains the same DATABASE_URL, REDIS_URL, and any custom env vars you would see in your local process. Treat the JSON stream as sensitive: do not commit it, paste it into chat, or pipe it to a service that retains logs. If you need to share output, redact the env_vars block first.
floo dev --json 2>/dev/null
Startup emits a single JSON object: 
{
  "success": true,
  "data": {
    "session_id": "abc12345-...",
    "app": "my-app",
    "postgres_authorized": true,
    "services": [
      {
        "name": "api",
        "port": 8000,
        "url": "http://localhost:8000",
        "env_vars": {
          "DATABASE_URL": "postgresql://user:pass@34.1.2.3:5432/myapp?sslmode=require",
          "REDIS_URL": "redis://...",
          "WEB_URL": "http://localhost:3000"
        }
      }
    ]
  }
}
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

CodeMeaning
NOT_AUTHENTICATEDRun floo auth login first
NO_CONFIG_FOUNDNo floo.app.toml found. Run floo init first
INVALID_PROJECT_CONFIGA service is missing dev_command, path, or port, or two services share a port
APP_NOT_FOUNDThe app doesn’t exist in floo
CANNOT_DETERMINE_IPfloo could not determine your public IP to authorize Postgres access