Golden Path

Still evaluating floo? Start with the introduction. This page assumes you’ve decided to build.

Before you start

You need a project directory with source code, a Dockerfile, and a GitHub repository. App names must be lowercase and hyphenated (e.g., my-saas-app). In examples below, replace owner/repo with your GitHub org and repo name. The --app flag is optional when you’re inside a directory with floo.app.toml. Use it when running commands from elsewhere.

First-time setup

floo auth login                          # one-time: opens browser to sign up or log in
cd my-project

floo init my-app                         # writes floo.app.toml into the repo
floo apps github connect owner/my-project # wires the repo and triggers the first deploy
git push origin main                     # ships the committed config and kicks off the build

floo auth login opens a browser. New users create an account automatically. In headless/CI environments, use floo auth login --api-key <key>. floo installs a GitHub webhook when you connect. After that, every git push triggers a build and deploy automatically. Check your deploy succeeded:

floo apps status my-app

Your app is live.

Dev URL: https://my-app-dev.on.getfloo.com
Every git push deploys to dev. When it’s ready, run floo releases promote --app my-app to publish to https://my-app.on.getfloo.com.
Watch live logs with floo logs --app my-app --follow.

Don’t bind a route to /healthz. Cloud Run’s serving edge reserves that exact path and returns a 404 before the request reaches your container. Use /health or /livez instead — those reach your app normally. If your framework registers /healthz by default, rename it. floo’s preflight emits a cloud_run_reserved_healthz warning when it detects this in your source.

Ship Changes

Commit and push to GitHub. The deploy triggers automatically.

git add . && git commit -m "feat: my change"
git push origin main
floo deploys watch --app my-app

Decision Table

I want to…	Run this
Create an account or log in	`floo auth login`
Deploy for the first time	`floo apps github connect owner/repo`
Ship a code change	`git push origin main`
Validate my config before pushing	`floo preflight` (local only, no auth needed)
Redeploy after env var change	`floo redeploy --app my-app`
Restart without rebuilding	`floo redeploy --restart --app my-app`
Watch a deploy in progress	`floo deploys watch --app my-app`
See deploy history	`floo deploys list --app my-app`
Roll back to a previous version	`floo deploys rollback my-app <id>`
Set an env var	`floo env set KEY=val --app my-app`
Add a custom domain	`floo domains add example.com --app my-app`
View logs	`floo logs --app my-app`
Run locally with prod credentials	`floo dev --app my-app` (requires `dev_command` in config)

Common Workflows

Add env vars and redeploy

floo env set API_KEY=secret --app my-app
floo redeploy --app my-app

Add a database

floo services add postgres --app my-app

The command provisions the database, injects DATABASE_URL plus standard PG* component vars into your app’s environment, and writes .floo/services.lock. Commit the lock file:

git add .floo/services.lock && git commit -m "feat: add postgres"
git push origin main

The next deploy uses the new standard PostgreSQL DATABASE_URL. Postgres is fully isolated between dev and prod (separate schemas, separate credentials, both provisioned up front). For Redis (floo services add redis) and Storage (floo services add storage), see Managed Services → Dev and prod isolation for how environments share state.

Add a custom domain

floo domains add app.example.com --app my-app

Follow the DNS instructions in the output.

Roll back a bad deploy

floo deploys list --app my-app
floo deploys rollback my-app <deploy-id>

Debug a failing deploy

floo deploys logs <deploy-id> --app my-app
floo logs --app my-app --since 1h --error

How floo works

The mental model. Config in the repo, GitHub-backed deploys, CLI-first.

Configuration

Understand floo.app.toml and how services are declared.

Get Started

Build with...

Build your app

Environments

Managed Services

Observe

Access

For Agents

Golden Path

Before you start

First-time setup

Ship Changes

Decision Table

Common Workflows

Add env vars and redeploy

Add a database

Add a custom domain

Roll back a bad deploy

Debug a failing deploy

How floo works

Configuration

​Before you start

​First-time setup

​Ship Changes

​Decision Table

​Common Workflows

​Add env vars and redeploy

​Add a database

​Add a custom domain

​Roll back a bad deploy

​Debug a failing deploy

How floo works

Configuration

Before you start

First-time setup

Ship Changes

Decision Table

Common Workflows

Add env vars and redeploy

Add a database

Add a custom domain

Roll back a bad deploy

Debug a failing deploy