Quickstart

floo builds and runs your app from its GitHub repository. Every push deploys to a dev URL, and a GitHub release ships that build to prod. This page goes from install to a live dev URL, either through your coding agent or by running the commands yourself. Requires a project directory with source code and a GitHub repository, and a Dockerfile for each service. Dockerfiles has one to copy for each common stack. For your own GitHub repository: install the GitHub App, link that installation to your floo organization, then connect the repository to deploy. No GitHub account? See Start without GitHub.

With your agent

An agent drives floo through the floo CLI, where every command supports --json, or through the HTTP API at https://api.getfloo.com/v1, starting from agents.md with every operation in openapi.json. The steps below use the CLI. Paste into Claude Code, Cursor, or any agent in your project.

Read https://getfloo.com/docs/introduction.md and deploy this app to floo.

Or paste the steps directly

Install floo and deploy this app.
Install the CLI:      curl -fsSL https://getfloo.com/install.sh | bash
Sign in:              floo auth login
Confirm the intended floo organization. To switch, replace acme with its slug:
floo orgs switch acme
If the org has no plan, have the user pick one:  floo billing upgrade
Have the user open https://github.com/apps/getfloo/installations/new, choose <owner>, select <owner>/<repo>, and install or save. Wait for any GitHub organization approval.
Link GitHub to floo:  floo apps github setup --no-browser
Give the printed setup link to the user. They must authorize floo with GitHub and choose <owner> if prompted. Wait for them to confirm GitHub access.
Write the config:     floo init <app-name>
Validate it locally:  floo preflight
Commit and push the config to the default branch.
Connect the repo:     floo apps github connect <owner>/<repo> --no-browser
If setup is still required, relay the error's URL, owner, repository, and next command to the user. Resume after they finish.
Verify the repo:      floo apps github status --app <app-name>
Verify the deploy:    floo deploys status --app <app-name> --json
Report the live URL only after the deploy is live.

Connect deploys the commit you pushed. Every push after that deploys automatically.

Yourself

curl -fsSL https://getfloo.com/install.sh | bash
floo auth login

The script supports macOS and Linux; for Windows, version pinning, and other options, see Install the CLI. Finish sign-in in the browser. If you belong to several floo organizations, switch to the one that should own this app before linking GitHub. Replace acme with its slug:

floo orgs switch acme

A new organization needs a plan before it can create apps or deploy. Run floo billing upgrade to pick one or add prepaid funds. Without one, connect fails with PLAN_REQUIRED.

2. Give floo access to your GitHub repository

Open Install the floo GitHub App.

Choose the GitHub account or organization that owns the repository. For acme/storefront, choose acme. Installing on your personal account does not grant access to acme’s repositories.
Under Repository access, choose Only select repositories and select the repository you want to deploy. If the App is already installed, update its repository access to include this repo.
Install or save. If GitHub requires organization-owner approval, wait for approval before continuing.

3. Link GitHub to your floo organization

floo apps github setup

In the browser it opens, authorize floo with the GitHub login that can access that installation. If floo asks you to choose a GitHub account, select the repository’s owner. Wait for GitHub access confirmed; the CLI then reports Linked the floo GitHub App to your org. This links the installation to the floo organization selected in step 1. It does not deploy your app. If the browser does not open, run floo apps github setup --no-browser and open the printed link. An expired link needs a fresh setup command; retrying does not require uninstalling the GitHub App.

4. Prepare and push the app

From your project directory:

cd my-project
floo init my-app

Edit the generated floo.app.toml to declare your services, ports, and managed services. See Configuration. App names are lowercase and hyphenated.

floo preflight
git add . && git commit -m "chore: configure floo"
git push origin main

Push the configuration before connecting. The first deploy reads the commit already on GitHub.

5. Connect the repository and verify the deploy

Replace owner/my-project with the repository you selected in step 2:

floo apps github connect owner/my-project
floo apps github status --app my-app
floo deploys status --app my-app --json

connect creates the app and starts its first deploy. Before opening its URL, confirm that github status names the intended repository and branch and that deploys status reports a live deploy. GitHub setup confirmation alone does not mean the app is live. Every later push to the connected branch deploys to dev. To publish to production, run gh release create v1 --repo <owner/repo>; see Environments.

If GitHub setup stops

What you see	Next action
The App is installed but floo says `GITHUB_INSTALLATION_NOT_AUTHORIZED`	Repeat step 3 in the intended floo organization, then run `connect`.
`GITHUB_APP_NOT_INSTALLED`	Repeat step 2 on the account that owns this repository.
`GITHUB_REPO_NOT_IN_INSTALLATION`	Open the settings link in the error and add this repository to the installation’s access.
GitHub approval pending	Ask the GitHub organization owner to approve the installation, then resume setup.
`PLAN_REQUIRED`	Run `floo billing upgrade`, pick a plan or add prepaid funds, then run `connect` again.

For command flags and connection details, see the GitHub reference.

Do not bind a route to /healthz; floo reserves that path, so use /health or /livez (see the container contract).

Start without GitHub

floo can host the repository for you. floo projects create makes a Next.js app with sign-in and managed Postgres, deploys it, and returns its URL:

floo projects create my-app
floo projects clone my-app

clone checks out the floo-hosted repo with credentials for that repo only. Push to deploy to dev, and run floo releases promote --app my-app to publish to prod. See projects.

Next steps

Recommended defaults

A complete floo.app.toml with floo’s defaults, and when to change each one.

CLI cheat sheet

Env vars, databases, domains, rollbacks, and debugging a failed deploy.

How floo works

Config in the repo, deploys from GitHub, the CLI or the API as the operating surface.

Build with your stack

End-to-end guides for Next.js, Rails, FastAPI, Django, and Express.

Get started

Build with your stack

Deploy from your agent

Configure your app

Ship and release

Data

Domains and networking

App users and access

Operate

Team and billing

For agents

With your agent

Yourself

2. Give floo access to your GitHub repository

3. Link GitHub to your floo organization

4. Prepare and push the app

5. Connect the repository and verify the deploy

If GitHub setup stops

Start without GitHub

Next steps

Recommended defaults

CLI cheat sheet

How floo works

Build with your stack

​With your agent

​Yourself

​1. Sign in to floo

​2. Give floo access to your GitHub repository

​3. Link GitHub to your floo organization

​4. Prepare and push the app

​5. Connect the repository and verify the deploy

​If GitHub setup stops

​Start without GitHub

​Next steps

Recommended defaults

CLI cheat sheet

How floo works

Build with your stack

With your agent

Yourself

1. Sign in to floo

2. Give floo access to your GitHub repository

3. Link GitHub to your floo organization

4. Prepare and push the app

5. Connect the repository and verify the deploy

If GitHub setup stops

Start without GitHub

Next steps